Planetary states API

Update: This API is deprecated. Use the new json api instead.

I needed a way to deal with planetary positions and velocities and found NASA's HORIZONS and the ephemerides. But I wanted a simpler interface than telnet or lugging around the massive ephemeris files with my applications. So instead, I wrote a simple JSON api for dealing with ephemeris files.

Suppose one wanted to get the chebyshev coefficients for computing mercury's state for today's date (November 5th), the URL query would look like this:

http://www.astro-phys.com/api/coeffs?date=2011-11-5&bodies=mercury

Which would return a JSON object whose structure looks like this:

{
  "date": 2455870.5,
  "results": {
    {"mercury": {
      "coeffs": ...
      "start": 2455856.5,
      "end": 2455872.5
    }
  }
}

Where "coeffs" contains the chebyshev coefficients for evaluating the state of mercury between the julian dates 2455856.5 and 2455872.5

To simplify it even further, you can grab the state of mercury at 9:30am on November 5th 2011 by using this url:

http://www.astro-phys.com/api/states?date=2011-11-5+9:30am&bodies=mercury

Which would return:

{
  "date": 2455870.89583,
  "results": {
    "mercury": [
      [30007449.557, -50119248.882, -29922524.4351],
      [2879610.10503, 2030853.04543, 786401.74378]
    ]
  }
}

Where the first array in "mercury" is the position vector (x, y, z) and the second array is the velocity vector (vx, vy, vz)

Multiple planets can be entered, comma-separated.

Applications requiring entire ephemeride records can use this:

http://www.astro-phys.com/api/records?date=2011-11-5+9:30am

This will give you...

{
  "date": 2455870.89583,
  "start": 2455824.5,
  "end": 2455888.5,
  "results": {
    "mercury": [
      [...]
    ],
    ...
  }
}

Where date is the date asked for, start is the beginning of the record and end is the end of the record. "results" contains every ephemeris body mapped to a list of its coefficient chunks for that record.

The ephemeris being used is DE406 for the time being, though I may add others later (and a backwards compatible means of specifying).

It doesn't include the full date range of DE406 yet, it only contains dates between 2000-2200 (I'll be adding more as needed, if you request a range increase it will probably be granted).

To see a web application using it in action, visit http://www.astro-phys.com and click "start" (its streaming the records to evaluate positions for the planets, the interface can be dragged and zoomed with the mouse).

Lastly, the constants section of the ephemeris is also available from the url

http://www.astro-phys.com/api/constants

When querying for coefficients, you can't ask for earth or moon directly. You have to use "earthmoon" (the earthmoon barycenter) and "geomoon" (the geocentric moon) and compute their states from those. However, when querying for "states", astro-phys does this for you.

PS: All api queries can also take a '&callback=somefunction' to be treated as jsonp. This works great with jquery's getJSON

Here's an example using jQuery.getJSON (note, when date is missing the current time is assumed)

var url = 'http://www.astro-phys.com/api/states?callback=?';
$.getJSON(url, {bodies: 'mercury'}, function(data) {
  var p = data.results.mercury[0];
  var v = data.results.mercury[1];
  alert('Position:\nx='+p[0]+'\ny='+p[1]+'\nz='+p[2]);
  alert('Velocity:\nx='+v[0]+'\ny='+v[1]+'\nz='+v[2]);
});