API Documentation (v2.0)

Rate Limiting

The service is not currently rate limited, however we are monitoring API usage and may add it in the future out of respect for Heavens Above.

Requests

UHAAPI has support for a number of HTTP request headers to help control the output of the service.

From

We encourage users of the API to include the HTTP From header with a valid email address in all requests. This information while solely be used to contact you in the event your client misbehaves or your usage is a little on the high side and will never be shared with anyone ever (we hate SPAM as much as you do).

User-Agent

The HTTP User-Agent header is another optional header that provides us with a bit of information about your client. Most browsers and client libraries set this automatically which gives us an idea of which programming languages and browsers we need to focus on supporting. If your client has a URL to more details you could include it here so we can check out your project and add it to the projects page.

Accept

Unless otherwise noted all API calls support returning either XML or JSON data. You can choose your preferred format by providing an HTTP Accept header.

Example

curl -H "Accept: application/xml" "http://api.uhaapi.com/satellites/25544/"
curl -H "Accept: application/json" "http://api.uhaapi.com/satellites/25544/"

Accept-Encoding

Requested data can also be returned in the gzip format by adding a gzip element to the HTTP Accept-Encoding header.

Example

curl -H "Accept-Encoding: gzip" "http://api.uhaapi.com/satellites/25544/"

Resources

Satellites

GET /satellites/

A simple service health indicator.
Response
A 200 OK status code indicates that satellite resources are currently available. Any other none 2XX status code indicates a problem with the service.
Response Body
The body of this response will always be empty.

GET /satellites/[id]/

Retrieves more detailed information about a satellite.
Path Parameters
  • id - USSPACECOM Catalog Number
Response
Under normal circumstances the method with return a 200 OK response with satellite details in the body. If no details are available for the specified satellite a 404 NOT FOUND is returned.
Response Headers
  • Link - A RFC5988 link to the passes and tle resources
Response Body
The following are results you can expect for the International Space Station (api.uhaapi.com/satellites/25544/)
JSON
{
"id":25544,
"idc":"1998-067-A",
"name":"ISS",
"launched":911544000
}
XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<satellite id="25544">
<idc>1998-067-A</idc>
<name>ISS</name>
<launched>1998-11-20T06:40:00Z</launched>
</satellite>

GET /satellites/[id]/passes

Returns all visible passes of the specified satellite within a minimum of the next 24 hours.
Path Parameters
  • id – USSPACECOM Catalog Number
Query Parameters
  • lat – Latitude of the observation
  • lng – Longitude of the observation
  • lm – Limiting magnitude (optional)
Response
The passes resource will return a 200 OK response on success. If no pass information is available then a 404 NOT FOUND will be returned.
Response Caching
Requests for satellite pass information specify both a Cache-Control header and Expires header indicating the maximum amount of time the pass data is fresh. While simply querying UHAAPI every 24 hours is still an acceptable way of requesting data, following the caching instructions is encouraged. This alleviates the need for your application to make frequent requests and also alleviates load on the UHAAPI servers.
Response Body
These are the expected response bodies for all visible passes of Envisat from JPL in California (http://api.uhaapi.com/satellites/27386/passes?lat=34.201694&lng=-118.171667)
JSON
{
"id":27386,
"location":{
"lat":34.2,
"lng":-118.15
},
"altitude":426.3936462402344,
"from":1345156168,
"to":1345265679,
"results":[
{
"magnitude":3.9,
"start":{
"time":1345181481,
"alt":44.0,
"az":0.0
},
"max":{
"time":1345181481,
"alt":44.0,
"az":0.0
},
"end":{
"time":1345181687,
"alt":10.0,
"az":0.0
}
}
]
}
XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<satellite_passes id="27386">
<location>
<lat>34.2</lat>
<lng>-118.15</lng>
</location>
<altitude>426.3936462402344</altitude>
<from>2012-08-16T22:31:26.332Z</from>
<to>2012-08-18T04:54:39Z</to>
<pass>
<magnitude>3.9</magnitude>
<start>
<time>2012-08-17T05:31:21Z</time>
<alt>44.0</alt>
<az>0.0</az>
</start>
<max>
<time>2012-08-17T05:31:21Z</time>
<alt>44.0</alt>
<az>0.0</az>
</max>
<end>
<time>2012-08-17T05:34:47Z</time>
<alt>10.0</alt>
<az>0.0</az>
</end>
</pass>
</satellite_passes>

GET /satellites/[id]/tle

Retrieve the most recent two line element for the specified satellite
Path Parameters
  • id - USSPACECOM Catalog Number
Response
Until we receive permission from the U.S. government to serve satellite TLE information this method will return 501 NOT IMPLEMENTED.

GET /satellites/iridium/flares

Retrieve upcoming Iridium flares
Query Parameters
  • lat – Latitude of the observation
  • lng – Longitude of the observation
  • lm – Limiting magnitude (optional)
Response
The flares resource will return a 200 OK response on success. If no flare information is available then a 404 NOT FOUND will be returned.
Response Body
JSON

XML

14 comments

  1. Xavier says:

    Are irdium flares working? Because this is what I get when I try to retrieve the flares.

    40.0
    -30.0

    214.092041015625
    2012-12-25T10:54:53.573Z
    2012-12-30T10:54:53.573Z

  2. Zakk says:

    Great service! Thank you for providing it.

    I fully understand your examples above. Question though.

    @Xavier is asking if Iridium Flares are working. How do you request this specifically? I don’t see anything mentioned here about flares. I was expecting to have to extract data to find them, but if there is actually a call for this already, that would be wonderful.

    Thanks!

    • Zakk says:

      I’m sorry. I overlooked a section on this page where it is explained.

      I entered:

      GET http://api.uhaapi.com/satellites/iridium/flares?lat=34.201694&lng=-118.171667

      which output

      {“location”:{“lat”:34.2,”lng”:0.0},”altitude”:996.719970703125,”from”:1357174375,”to”:1357606375,”results”:[]}

      How am I to interpret these results? I assume you are giving me a 3 point coordinate (x,y,z basically), but dont’ the flares shine in a particular direction?

      This json data also seems looks like an empty set. Another oddity is that the lng that is returned is 0.0.

      I checked some other apps for iridium flares to compare the results, and they do list quite a few upcoming in the next 5 days, so I’m assuming that the IF service isn’t fully functioning?

      Any guidance would be great. Thanks!

      • Kevin Loney says:

        I have been having some issues with the Iridium flares API which I unfortunately have not had time to look into yet. I will be looking into it as soon as possible.

        In the mean time I will expand the documentation a bit to include samples of the expected output.

  3. Rémy says:

    Hello. First I would like to say I love your project, this is a great idea to make these data accessible to developers.
    As you have worked with heavens-above’s data, maybe do you know the answer of my question: do you know how the planets page (http://heavens-above.com/planets.aspx) works? I mean, do you have any idea how these distances are calculated (or found)?

    Now, as a developer, as someone who loves to understand how things work, can you tell me (or give me some clues) how you built this API?

    And finally, is it in your plans to add a “planets distances” service to your API?

    Thank you and, again, congrats for this project.

    • Kevin Loney says:

      Positions and distances to pretty much anything in space can calculated using something called an orbital element which describes a bodies motion through space. Using a known starting position and iterating repeatedly you can get a pretty good idea of where the object will be at any given time. The math involved is mostly beyond me however planetary orbital elements are easy enough to find.

      Unfortunately due to work and school I haven’t been able to maintain UHAAPI as actively as I would like. So while adding a planet distances API to the service would certainly be possible it will likely not happen until May after I’ve done some other outstanding work on the service.

      The API itself is a Tomcat servlet that relies heavily on a memcached instance to reduce load on the Heavens Above servers. When someone makes a request for data that isn’t already in memcached UHAAPI make a request for the page from Heavens Above, parses the HTML, pulls out the appropriate data, adds it to memcached, and returns it to the requester.

  4. Mike Stiggy says:

    Greetings. Fantastic API. the past couple of days I keep getting an error returned stating that response from Heavens-Above was taking longer than usual??? Is this a common occurrence or is it something on my end.

    • Carl Gruber says:

      I can’t even access the Heavens-Above website as of today (9th May). I suspect the site itself is having some troubles.

      • Kevin Loney says:

        Heavens Above has been down for the last 14 hours, but there are some issues with the API itself that are causing it to return 503 responses even when HA is up.

Leave a Reply

Your email address will not be published. Required fields are marked *