API

API Documentation:

Warning! This is under construction still and may change without notice.

List of APIs:

  1. International Space Station Pass Times
    1. Overview
    2. Inputs
    3. Output
    4. Examples
  2. International Space Station Location Right Now

    1. Overview
    2. Output
    3. Examples
  3. Interplanetary Spacecraft

    1. Overview
    2. Key

International Space Station Pass Times

http://api.open-notify.org/iss/

The international space station (ISS) is an orbital outpost circling high above out heads. Sometimes it’s overhead, but when? It depends on your location. Given a location on Earth (latitude, longitude, and altitude) this API will compute the next n number of times that the ISS will be overhead.

Overhead is defined as 10° in elevation for the observer. The times are computed in UTC and the length of time that the ISS is above 10° is in seconds.

This gives you enough information to compute pass times for up to several weeks, but beware! times are less and less accurate as you go into the future. This is because the orbit of the ISS decays unpredictably over time and because station controllers periodically move the station to higher and lower orbits for docking, re-boost, and debris avoidance.

Overview

The API returns a list of upcoming ISS passes for a particular location formatted as JSON.

As input it expects a latitude/longitude pair, altitude and how many results to return. All fields are required.

As output you get the same inputs back (for checking) and a time stamp when the API ran in addition to a success or failure message and a list of passes. Each pass has a duration in seconds and a rise time as a unix time stamp.

Inputs

Parameters are given to the api through the query string like this

iss/?n=10&alt=1352

Here is the list of parameters, they are all mandatory. See examples for an example.

Field Type Range Description
lat float −90.0 … 90.0 Latitude — The latidute in decimal degrees on the Earth for the observer
lon float −180.0 … 180.0 Longitude — The longitude in decimal degrees on the Earth for the observer
alt int 0 … 10000 Altitude — The altitude above sea level in meters of the point on the Earth for the observer
n int 1 … 100 The number of future passes to return

Output

Output will be JSON encoded. The main object contains a success or failure message, a timestamp and an echo of the observer it tried to use, and a list of passes.

Returned object:
Key Possible Values Description
message “success” or “failure” A message that the API completed successfully
request a request object Contains an echo of the parameters and a timestamp
response a response object Contains a list of passes
Request object:
Key Possible Values Description
datetime 62 bit int unix time stamp when the API was run
latitude −90.0 … 90.0 The latitude the API used as an observer
longitude −180.0 … 180.0 The longitude the API used as an observer
altitude 0 … 10000 The altitude the API used as an observer
passes 0 … 100 The number of passes found and returned
Pass object:
Key Possible Values Description
risetime 62 bit int unix time stamp when the ISS will be above 10°
duration int Number of seconds the pass will last

Examples

This url:

Returns something like:

{
    "message": "success"
  , "request": 
     {
          "latitude": 45.473610000000001
        , "passes": 3
        , "altitude": 100
        , "longitude": -122.64931
        , "datetime": 1319434674
     }
  , "response": 
     [
       {
           "duration": 618
         , "risetime": 1319436686
       }
     , {
          "duration": 472
        , "risetime": 1319442488
       }
     , {
          "duration": 497
        , "risetime": 1319496581
       }
    ]
}

Which is a list of the 3 upcoming ISS passes as seen from Portland, OR.

International Space Station Current Location

http://api.open-notify.org/iss-now/

The International Space Station is moving at close to 17,500 miles per hour so it’s location changes really fast!

Overview

This is a simple api to return the current location of the ISS. When fetched it returns the current latitude and longitude of the space station with a unix timestamp that it was valid for. There are no parameters to the API

Output

The output is JSON. It has a message object that should say success unless something went wrong on my end. There is a timestamp which is in unix time and iss_position which has a latitude longitude pair.

{
    "timestamp": %a unix time stamp%
  , "message": "success"
  , "iss_position": 
      {
          "latitude": %The latitude in decimal degress%
        , "longitude": %The longitude in decimal degress%
      }
}

Examples

Going to http://api.open-notify.org/iss-now/ should give you output like this:

{"timestamp": 1319433348, "message": "success", "iss_position": {"latitude": -43.201602198490967, "longitude": -11.952223160686183}}

Interplanetary Spacecraft

http://api.open-notify.org/solarview/

A current top down view of the solar system with interplanetary spacecraft positions.

Overview

A graphical representation of the solar system is drawn every few hours with the current location of active spacecraft in deep space. The “API” here is just a link to the current image. There is a timestamp on each image.

Current inner solar system:


http://api.open-notify.org/solarview/inner.png

Inner Solar system now

Key

Sun, Mercury, Venus, Earth, Mars