Tracking 19245 objects as of 21-Aug-2018
HD Live streaming from Space Station
objects crossing your sky now

N2YO.COM REST API v1

The purpose of the API is to provide data for software/web developers to build satellite tracking or prediction applications.

As of March 19, 2018, the older API, based on SOAP Web Services is going to be phased out, and no new licenses are going to be issued. Existing users are asked to transition to the current API, based on RESTful, web services (REST).

The REST API v1 is free but it is transaction limited. The current limit is 1000 transactions/hour. If you need more traffic, contact us. Users are requested not to abuse the system, and not use multiple license keys to get around the hourly transation limit. Traffic is monitored and logged. When the API is used in improper ways, user access will be limited or blocked.

For each transaction, the caller must be identified and authorized by a license key (API key). To generate a unique license key, users are requested first to register an account at n2yo.com. After login, please visit the profile page and scroll down to access the button that generates the API key. The new API key will be accessible in the profile and cannot be changed. If you need a new key, please contact us and provide an explanation. The keys issued for the SOAP Web Services API are not valid for REST API.

As a general concept, satellites are identified by their NORAD catalog number which is an integer ranging from 1 to 43235 and counting. The numbers are assigned by United States Space Command (USSPACECOM) to all Earth orbiting satellites in order of identification. If you are looking to find the id of your favorite satellite, browse categories or search the n2yo.com database until you arrive at the satellite details page, and extract the NORAD ID for your application. For instance, Space Station (ISS) is NORAD ID 25544.

For all request, method used is GET.
Base URL: https://www.n2yo.com/rest/v1/satellite/
API key: The API key (apiKey) must be appended at the end of the URL as &apiKey={your API key}

The following functions are currently available:


Get TLE

Retrieve the Two Line Elements (TLE) for a satellite identified by NORAD id.

Request: /tle/{id}

ParameterTypeRequiredComments
idintegerYesNORAD id

Response:

ParameterTypeComments
satidintegerNORAD id used in input
satnamestringSatellite name
transactionscountintegerCount of transactions performed with this API key in last 60 minutes
tlestringTLE on single line string. Split the line in two by \r\n to get original two lines

Example

Request: https://www.n2yo.com/rest/v1/satellite/tle/25544&apiKey=589P8Q-SDRYX8-L842ZD-5Z9
JSON Response:
{
    "info": {
        "satid": 25544,
        "satname": "SPACE STATION",
        "transactionscount": 4
    },
    "tle": "1 25544U 98067A   18077.09047010  .00001878  00000-0  35621-4 0  9999\r\n2 25544  51.6412 112.8495 0001928 208.4187 178.9720 15.54106440104358"
}


Get satellite positions

Retrieve the future positions of any satellite as footprints (latitude, longitude) to display orbits on maps. Also return the satellite's azimuth and elevation with respect to the observer location. Each element in the response array is one second of calculation. First element is calculated for current UTC time.

Request: /positions/{id}/{observer_lat}/{observer_lng}/{observer_alt}/{seconds}

ParameterTypeRequiredComments
idintegerYesNORAD id
observer_latfloatYesObserver's latitide (decimal degrees format)
observer_lngfloatYesObserver's longitude (decimal degrees format)
observer_altfloatYesObserver's altitude above sea level in meters
secondsintegerYesNumber of future positions to return. Each second is a position. Limit 300 seconds

Response:

ParameterTypeComments
satidintegerNORAD id used in input
satnamestringSatellite name
transactionscountintegerCount of transactions performed with this API key in last 60 minutes
satlatitudefloatSatellite footprint latitude (decimal degrees format)
satlongitudefloatSatellite footprint longitude (decimal degrees format)
azimuthfloatSatellite azimuth with respect to observer's location (degrees)
elevationfloatSatellite elevation with respect to observer's location (degrees)
rafloatSatellite right angle (degrees)
decfloatSatellite declination (degrees)
timestampintegerUnix time for this position (seconds). You should convert this UTC value to observer's time zone

Example - retrieve Space Station (25544) positions for next 2 seconds. Observer is located at lat: 41.702, lng: -76.014, alt: 0

Request: https://www.n2yo.com/rest/v1/satellite/positions/25544/41.702/-76.014/0/2/&apiKey=589P8Q-SDRYX8-L842ZD-5Z9
JSON Response:
{
  "info": {
    "satname": "SPACE STATION",
    "satid": 25544,
    "transactionscount": 5
  },
  "positions": [
    {
      "satlatitude": -39.90318514,
      "satlongitude": 158.28897924,
      "sataltitude": 417.85,
      "azimuth": 254.31,
      "elevation": -69.09,
      "ra": 44.77078138,
      "dec": -43.99279118,
      "timestamp": 1521354418
    },
    {
      "satlatitude": -39.86493451,
      "satlongitude": 158.35261287,
      "sataltitude": 417.84,
      "azimuth": 254.33,
      "elevation": -69.06,
      "ra": 44.81676119,
      "dec": -43.98086419,
      "timestamp": 1521354419
    }
  ]
}


Get visual passes

Get predicted visual passes for any satellite relative to a location on Earth. A "visual pass" is a pass that should be optically visible on the entire (or partial) duration of crossing the sky. For that to happen, the satellite must be above the horizon, illumintaed by Sun (not in Earth shadow), and the sky dark enough to allow visual satellite observation.

Request: /visualpasses/{id}/{observer_lat}/{observer_lng}/{observer_alt}/{days}/{min_visibility}

ParameterTypeRequiredComments
idintegerYesNORAD id
observer_latfloatYesObserver's latitide (decimal degrees format)
observer_lngfloatYesObserver's longitude (decimal degrees format)
observer_altfloatYesObserver's altitude above sea level in meters
daysintegerYesNumber of days of prediction (max 10)
min_visibilityintegerYesMinimum number of seconds the satellite should be considered optically visible during the pass to be returned as result

Response:

ParameterTypeComments
satidintegerNORAD id used in input
satnamestringSatellite name
transactionscountintegerCount of transactions performed with this API key in last 60 minutes
passescountintegerCount of passes returned
startAzfloatSatellite azimuth for the start of this pass (relative to the observer, in degrees)
startAzCompassstringSatellite azimuth for the start of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
startElfloatSatellite elevation for the start of this pass (relative to the observer, in degrees)
startUTCintegerUnix time for the start of this pass. You should convert this UTC value to observer's time zone
maxAzfloatSatellite azimuth for the max elevation of this pass (relative to the observer, in degrees)
maxAzCompassstringSatellite azimuth for the max elevation of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
maxElfloatSatellite max elevation for this pass (relative to the observer, in degrees)
maxUTCintegerUnix time for the max elevation of this pass. You should convert this UTC value to observer's time zone
endAzfloatSatellite azimuth for the end of this pass (relative to the observer, in degrees)
endAzCompassstringSatellite azimuth for the end of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
endElfloatSatellite elevation for the end of this pass (relative to the observer, in degrees)
endUTCintegerUnix time for the end of this pass. You should convert this UTC value to observer's time zone
magfloatMax visual magnitude of the pass, same scale as star brightness. If magnitude cannot be determined, the value is 100000
durationintegerTotal visible duration of this pass (in seconds)

Example - retrieve Space Station (25544) passes optically visible at least 300 seconds for next 2 days. Observer is located at lat: 41.702, lng: -76.014, alt: 0

Request: http://www.n2yo.com/rest/v1/satellite/visualpasses/25544/41.702/-76.014/0/2/300/&apiKey=589P8Q-SDRYX8-L842ZD-5Z9
JSON Response:
{
  "info": {
    "satid": 25544,
    "satname": "SPACE STATION",
    "transactionscount": 4,
    "passescount": 3
  },
  "passes": [
    {
      "startAz": 307.21,
      "startAzCompass": "NW",
      "startEl": 13.08,
      "startUTC": 1521368025,
      "maxAz": 225.45,
      "maxAzCompass": "SW",
      "maxEl": 78.27,
      "maxUTC": 1521368345,
      "endAz": 132.82,
      "endAzCompass": "SE",
      "endEl": 0,
      "endUTC": 1521368660,
      "mag": -2.4,
      "duration": 485
    },
    {
      "startAz": 311.56,
      "startAzCompass": "NW",
      "startEl": 50.94,
      "startUTC": 1521451295,
      "maxAz": 37.91,
      "maxAzCompass": "NE",
      "maxEl": 52.21,
      "maxUTC": 1521451615,
      "endAz": 118.61,
      "endAzCompass": "ESE",
      "endEl": 0,
      "endUTC": 1521451925,
      "mag": -2,
      "duration": 325
    },
    {
      "startAz": 291.06,
      "startAzCompass": "WNW",
      "startEl": 3.47,
      "startUTC": 1521457105,
      "maxAz": 231.58,
      "maxAzCompass": "SW",
      "maxEl": 14.75,
      "maxUTC": 1521457380,
      "endAz": 170.63,
      "endAzCompass": "S",
      "endEl": 0,
      "endUTC": 1521457650,
      "mag": -0.1,
      "duration": 485
    }
  ]
}


Get radio passes

The "radio passes" are similar to "visual passes", the only difference being the requirement for the objects to be optically visible for observers. This function is useful mainly for predicting satellite passes to be used for radio communications. The quality of the pass depends essentially on the highest elevation value during the pass, which is one of the input parameters.

Request: /radiopasses/{id}/{observer_lat}/{observer_lng}/{observer_alt}/{days}/{min_elevation}

ParameterTypeRequiredComments
idintegerYesNORAD id
observer_latfloatYesObserver's latitide (decimal degrees format)
observer_lngfloatYesObserver's longitude (decimal degrees format)
observer_altfloatYesObserver's altitude above sea level in meters
daysintegerYesNumber of days of prediction (max 10)
min_elevationintegerYesThe minimum elevation acceptable for the highest altitude point of the pass (degrees)

Response:

ParameterTypeComments
satidintegerNORAD id used in input
satnamestringSatellite name
transactionscountintegerCount of transactions performed with this API key in last 60 minutes
passescountintegerCount of passes returned
startAzfloatSatellite azimuth for the start of this pass (relative to the observer, in degrees)
startAzCompassstringSatellite azimuth for the start of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
startUTCintegerUnix time for the start of this pass. You should convert this UTC value to observer's time zone
maxAzfloatSatellite azimuth for the max elevation of this pass (relative to the observer, in degrees)
maxAzCompassstringSatellite azimuth for the max elevation of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
maxElfloatSatellite max elevation for this pass (relative to the observer, in degrees)
maxUTCintegerUnix time for the max elevation of this pass. You should convert this UTC value to observer's time zone
endAzfloatSatellite azimuth for the end of this pass (relative to the observer, in degrees)
endAzCompassstringSatellite azimuth for the end of this pass (relative to the observer). Possible values: N, NE, E, SE, S, SW, W, NW
endUTCintegerUnix time for the end of this pass. You should convert this UTC value to observer's time zone

Example - retrieve Space Station (25544) radio passes above 40 degrees of elevation for next 2 days. Observer is located at lat: 41.702, lng: -76.014, alt: 0

Request: https://www.n2yo.com/rest/v1/satellite/radiopasses/25544/41.702/-76.014/0/2/40/&apiKey=589P8Q-SDRYX8-L842ZD-5Z9
JSON Response:
{
  "info": {
    "satid": 25544,
    "satname": "SPACE STATION",
    "transactionscount": 2,
    "passescount": 2
  },
  "passes": [
    {
      "startAz": 311.57,
      "startAzCompass": "NW",
      "startUTC": 1521451295,
      "maxAz": 37.98,
      "maxAzCompass": "NE",
      "maxEl": 52.19,
      "maxUTC": 1521451615,
      "endAz": 118.6,
      "endAzCompass": "ESE",
      "endUTC": 1521451925
    },
    {
      "startAz": 242.34,
      "startAzCompass": "WSW",
      "startUTC": 1521600275,
      "maxAz": 328.03,
      "maxAzCompass": "NW",
      "maxEl": 49.59,
      "maxUTC": 1521600595,
      "endAz": 47.97,
      "endAzCompass": "NE",
      "endUTC": 1521600905
    }
  ]
}


What's up?

The "above" function will return all objects within a given search radius above observer's location. The radius (θ), expressed in degrees, is measured relative to the point in the sky directly above an observer (azimuth). This image may offer a better explanation:
The 'above' function

The search radius range is 0 to 90 degrees, nearly 0 meaning to show only satellites passing exactly above the observer location, while 90 degrees to return all satellites above the horizon. Since there are many satellites and debris in the sky at any point in time, the result could be filtered by satellite category (integer). The following categories are currently available at n2yo.com:
Catgoryid
Amateur radio18
Beidou Navigation System35
Brightest1
Celestis45
CubeSats32
Disaster monitoring8
Earth resources6
Education29
Engineering28
Experimental19
Flock48
Galileo22
Geodetic27
Geostationary10
Global Positioning System (GPS) Constellation50
Global Positioning System (GPS) Operational20
Globalstar17
Glonass Operational21
GOES5
Gonets40
Gorizont12
Intelsat11
Iridium15
IRNSS46
ISS2
Catgoryid
Lemur49
Military30
Molniya14
Navy Navigation Satellite System24
NOAA4
O3B Networks43
Orbcomm16
Parus38
QZSS47
Radar Calibration31
Raduga13
Russian LEO Navigation25
Satellite-Based Augmentation System23
Search & rescue7
Space & Earth Science26
Strela39
Tracking and Data Relay Satellite System9
Tselina44
Tsikada42
Tsiklon41
TV34
Weather3
Westford Needles37
XM and Sirius33
Yaogan36

Please use this function responsably as there is a lot of CPU needed in order to calculate exact positions for all satellites in the sky. The function will return altitude, latitude and longitude of satellites footprints to be displayed on a map, and some minimal information to identify the object.

Request: /above/{observer_lat}/{observer_lng}/{observer_alt}/{search_radius}/{category_id}

ParameterTypeRequiredComments
observer_latfloatYesObserver's latitide (decimal degrees format)
observer_lngfloatYesObserver's longitude (decimal degrees format)
observer_altfloatYesObserver's altitude above sea level in meters
search_radiusintegerYesSearch radius (0-90)
category_idintegerYesCategory id (see table). Use 0 for all categories

Response:

ParameterTypeComments
categorystringCategory name (ANY if category id requested was 0)
transactionscountintegerCount of transactions performed with this API key in last 60 minutes
satcountintegerCount of satellites returned
startAzfloatSatellite azimuth for the start of this pass (relative to the observer, in degrees)
satidintegerSatellite NORAD id
intDesignatorstringSatellite international designator
satnamestringSatellite name
launchDatestringSatellite launch date (YYYY-MM-DD)
satlatfloatSatellite footprint latitude (decimal degrees format)
satlatfloatSatellite footprint longitude (decimal degrees format)
satlatfloatSatellite altitude (km)

Example - retrieve Amateur Radio satellites (categ id 18) located within a search radius of 70 degrees. Observer is located at lat: 41.702, lng: -76.014, alt: 0

Request: https://www.n2yo.com/rest/v1/satellite/above/41.702/-76.014/0/70/18/&apiKey=589P8Q-SDRYX8-L842ZD-5Z9
JSON Response:
{
  "info": {
    "category": "Amateur radio",
    "transactionscount": 17,
    "satcount": 3
  },
  "above": [
    {
      "satid": 20480,
      "satname": "JAS 1B (FUJI 2)",
      "intDesignator": "1990-013C",
      "launchDate": "1990-02-07",
      "satlat": 49.5744,
      "satlng": -96.7081,
      "satalt": 1227.9326
    },
    {
      "satid": 26609,
      "satname": "AMSAT OSCAR 40",
      "intDesignator": "2000-072B",
      "launchDate": "2000-11-16",
      "satlat": 5.5105,
      "satlng": -21.4478,
      "satalt": 49678.6389
    },
    {
      "satid": 40719,
      "satname": "DEORBITSAIL",
      "intDesignator": "2015-032E",
      "launchDate": "2015-07-10",
      "satlat": 43.8106,
      "satlng": -90.3944,
      "satalt": 657.5516
    }
  ]
}