Building a Simple Eclipse App

How I built

I’ll be headed to Asheville, NC next week to visit family and experience the total solar eclipse on Monday, the 21st. I wouldn’t call myself a die hard fan of celestial occurrences but at the same time, I’m not going to pass up the opportunity to see the moon cover the sun!

While preparing for this event, I visited a lot of eclipse websites to forecast the best location and viewing times. Most of these websites take the kitchen sync approach and tend to pile on all the grindy science details. I thought it might be fun to build a ridiculously simply eclipse app.

Here’s what features made the cut:

  1. Get the user’s current coordinates and inform them if the eclipse will be visible in their location.
  2. If the eclipse is visible, explain when it will begin, peak, and end. In addition provide a visual representation of the event.
  3. Allow the user to switch to a different location.
  4. Inform the user on what safety precaution to take.

In hindsight, I probably would have dropped the ability to switch to a different location too. Head over to and try it out!

Getting the Data

Ahead of the eclipse event this year, The United States Naval Observatory turned their solar eclipse calculator into a publicly accessible API. Sadly, it was up and down throughout my development process so I had to look elsewhere. Not knowing how to proceed, I reached out to Xavier Jubier, an eclipse expert, on Twitter and he responded with an API of his own!

This end point receives the following parameters via a GET request:

Ecl (string) The eclipse event date. +20170821
Lat (float) The latitude coordinate.
Lng (float) The longitude coordinate.
TZ (string) A timezone offset in the format +0000
Alt (integer) The altitude of the viewing location.

Here’s an example response for Asheville, NC. Taking a look at what we receive back, I’m only concerned with a few values, namely: eclipse type, magnitude, contacts, and mid event “o’clock” position. Using eclipse type, we can inform the user if an eclipse is occurring or not. I’ll be using the magnitude value later to adjust the visualization of the event and the brightness of the background. The contacts are used write a description of the event timings. Finally, the mid event position is a crucial element to creating a simulation of the event.

Getting user’s position and timezone

Obtaining the user’s initial location is made simple with the HTML5 Geolocation API. Simply respond to the following call.

// data.coords.latitude
// data.coords.longitude

By adding the ability to jump from one location to another, we add some complexity. In addition to turning a query such as “London” into a pair of coordinates, we also need to be aware of the timezone offset of this new location. I decided on a combination of the Mapbox geocoder and Google Maps Timezone API. Forgive me ToS for I have sinned. Both of these APIs are well documented so I would suggest checking them out. Also, special shout out to Moment.js for helping convert timezones and formatting times into something a human can read.

Visualizing the Eclipse

I think what excited me most about tackling this problem was figuring out a solution to create the visual of the eclipse. Naturally you can use CSS to put one circle in front of another but when you add a glow (box-shadow) effect, you get this sad looking sharp line of contact where it should be glowing also. Paper.js to the rescue. Since Paper is built on a smart vector engine, I was able to create a third shape which was the subtraction of the moon and sun circle shapes. This new obscuration shape is then given the glow to complete the effect. To over simplify things:

var sun         = new Path.Circle();
var moon = new Path.Circle();
var obscuration = sun.subtract(moon);

Throw in a bit of Tween.js for good measure and you’ve created a solid eclipse simulation. 🙌🏻

Remember, if you aren’t in the zone of totality, you must wear solar glasses at all times. Even if you’re lucky enough to be in the zone, you should only remove your glasses for the two minutes of darkness. Check out the app and have a safe eclipse! 😎

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.