[Editors note: This is the first of serveral posts where we show how to use APIs to solve problems. Let us know what you think of them on twitter (@nordicapis) or via the comments on this post.]

  by  Ryan Wick 

Some of the objects you can spot on a clear, starry night move a bit faster across the sky than stars or planets. The space above us is sprinkled with airplanes, satellites and other man-made objects. Every now and then, from where you are, you can spot the International Space Station (ISS), soaring like a bright shining bullet across the night sky. Depending on where you are on the planet, it may be several days between sightings.

Spot The Station. Here, you can sign up for an alert email, or use the RSS feed, for thousands of places worldwide. It tells you the exact time of appearance, and where to look for the ISS on the night sky.

Houston, we have a problem

The alert from NASA works perfectly, but it does not take into account the weather conditions. No point waking up in the early morning hours to find the sky is too cloudy for an ISS sighting, is there? But if we can match the ISS alerts against a weather forecast, we could filter out only those alerts which are likely to appear on a clear, starry night.

For example, we can use the weather forecast API from yr.no, which is available in XML format. The RSS feed from Spot The Station provides ISS sightings. Both services should be free to use for experimental purposes like this, and require no API keys. For complete terms of use, please see om.yr.no/verdata/free-weather-data and spotthestation.nasa.gov respectively.

The essentials of the API provided by yr.no

It is easy access the weather forecast from yr.no in XML format. Search for your location on yr.no,. When you see the forecast web page, just add "forecast.xml" to the URL. The XML output starts with a header, containing for example your location:

<location>
<name>Lund</name>
<type>Administration centre</type>
<country>Sweden</country>
<timezone id="Europe/Stockholm" utcoffsetMinutes="120"/>
<location altitude="51" latitude="55.70584" longitude="13.19321" geobase="geonames" geobaseid="2693678"/>
</location>

The actual weather forecasts begin after the tags <forecast> <tabular>, and each time period is enclosed by the tags <time from=... and </time>. The code symbol number=“1” below is the essential information, that this particular time period will have a clear sky:

<forecast>
<tabular>
<time from="2014-05-23T09:00:00" to="2014-05-23T12:00:00" period="1">
<!-- Valid from 2014-05-23T09:00:00 to 2014-05-23T12:00:00 -->
<symbol number="1" numberEx="1" name="Clear sky" var="01d"/>
<precipitation value="0"/>
<!-- Valid at 2014-05-23T09:00:00 -->
<windDirection deg="133.8" code="SE" name="Southeast"/>
<windSpeed mps="5.5" name="Moderate breeze"/>
<temperature unit="celsius" value="21"/>
<pressure unit="hPa" value="1008.0"/>
</time>
...

The NASA RSS feed for ISS sightings

Go to spotthestation.nasa.gov and select Location lookup. When you found your location, there is a button for the RSS feed. If you save the file and look in the header, it includes the link to your location:

<link>https://spotthestation.nasa.gov/sightings/view.cfm?country=United_States&amp;region=Alabama&amp;city=Abbeville</link>

Following the header, you have a list of sightings ahead, each enclosed by the tag <item>:

<item>
<title>2014-05-11 ISS Sighting</title>
<pubDate>06 May 2014 08:34:00 GMT</pubDate>
<description>
Date: Sunday May 11, 2014 &lt;br/&gt;
Time: 5:04 AM &lt;br/&gt;
Duration: 3 minutes &lt;br/&gt;
Maximum Elevation: 16 ° &lt;br/&gt;
Approach: 10 ° above SSE &lt;br/&gt;
Departure: 14 ° above ESE &lt;br/&gt;
</description>
<guid>https://spotthestation.nasa.gov/sightings/view.cfm?country=United_States&amp;region=Alabama&amp;city=Abbeville&amp;ss=26AE328A-A321-777C-A06E3DAFC6069155</guid>
</item>

The tag <title> includes the dates, which we can match against the dates in the weather forecast from YR. The tag <description> includes all the details of the sighting, which are useful in an email alert. Note that NASA only lists sightings which will occur during dark hours, in local time for your location.

Putting it all together

Now, these data sources provide the sources we need to create our own alert function. It filters out only those ISS sightings which are likely to occur on a clear, starry night sky. I have put together a working PHP script, which you can use to experiment further: github.com/staffansolve/Hello-Sky

Happy star-gazing!