# N2YO

> Track satellites with N2YO: where the International Space Station (or any of the 35,000 catalogued objects) is right now, when it will next be visible from your back garden, when it will be high enough to work by radio, what is passing overhead at this moment, and the orbital elements tracking software needs.

App · Weather & Space · 7 actions. Web page: https://docs.lodol.com/docs/integrations/n2yo

## Actions

### Get a satellite's ground track

Follow a satellite second by second from now: one position per second, up to 300 of them, each with the point on Earth below it and where to look for it from your location. This is the path to draw on a map, or to point an antenna along.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.
- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Seconds to track (`seconds`, number): How many seconds of track to return, one position per second, starting now. N2YO allows up to 300 (five minutes) per call. From 1 to 300. Default: `60`.
- Time zone (`timezone`, text): Optional. A time-zone database name such as 'America/New_York'. Every time in the result is also reported as local wall-clock time in this zone, which is what a person reading 'the ISS passes over at...' needs. Leave empty to get UTC only.

**Outputs**

- `count` (number): How many positions were returned.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `positions` (list): One position per second, earliest first, starting with right now.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `seconds` (number): How many seconds of track were asked for.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "count": 2,
  "name": "SPACE STATION",
  "positions": [
    {
      "altitude_km": 417.85,
      "azimuth": 254.31,
      "azimuth_compass": "WSW",
      "declination": -43.99279118,
      "elevation": -69.09,
      "is_above_horizon": false,
      "latitude": -39.90318514,
      "local_time": "2018-03-18 02:26:58 EDT",
      "longitude": 158.28897924,
      "right_ascension": 44.77078138,
      "time": "2018-03-18T06:26:58Z",
      "timestamp": 1521354418
    },
    {
      "altitude_km": 417.84,
      "azimuth": 254.33,
      "azimuth_compass": "WSW",
      "declination": -43.98086419,
      "elevation": -69.06,
      "is_above_horizon": false,
      "latitude": -39.86493451,
      "local_time": "2018-03-18 02:26:59 EDT",
      "longitude": 158.35261287,
      "right_ascension": 44.81676119,
      "time": "2018-03-18T06:26:59Z",
      "timestamp": 1521354419
    }
  ],
  "satellite_id": 25544,
  "seconds": 2,
  "transactions_used": 5
}
```

### Get a satellite's position now

Get where a satellite is at this moment, the point on Earth it is over, how high it is, and where to look for it from your location: the compass bearing, the angle above the horizon, and whether it is above the horizon at all.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.
- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Time zone (`timezone`, text): Optional. A time-zone database name such as 'America/New_York'. Every time in the result is also reported as local wall-clock time in this zone, which is what a person reading 'the ISS passes over at...' needs. Leave empty to get UTC only.

**Outputs**

- `altitude_km` (number): Height of the satellite above the ground, in kilometres.
- `azimuth` (number): Compass bearing to look along from the observer, in degrees clockwise from north.
- `azimuth_compass` (text): The same bearing as a compass point, e.g. 'WNW'. Worked out from the azimuth.
- `declination` (number): Declination of the satellite on the sky, in degrees.
- `elevation` (number): How high above the horizon to look, in degrees. 0 is the horizon, 90 is straight up; a negative value means the satellite is below the horizon.
- `is_above_horizon` (true/false): Whether the satellite is above the observer's horizon at this moment, i.e. whether the elevation is positive.
- `latitude` (number): Latitude of the point on the ground directly below the satellite, in degrees.
- `local_time` (text): The same instant as wall-clock time in the requested time zone, or empty when no time zone was given.
- `longitude` (number): Longitude of the point on the ground directly below the satellite, in degrees.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `right_ascension` (number): Right ascension of the satellite on the sky, in degrees.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `time` (text): The same instant as an ISO 8601 UTC date-time.
- `timestamp` (number): The instant this position is for, in Unix seconds.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "altitude_km": 417.85,
  "azimuth": 254.31,
  "azimuth_compass": "WSW",
  "declination": -43.99279118,
  "elevation": -69.09,
  "is_above_horizon": false,
  "latitude": -39.90318514,
  "local_time": "2018-03-18 02:26:58 EDT",
  "longitude": 158.28897924,
  "name": "SPACE STATION",
  "right_ascension": 44.77078138,
  "satellite_id": 25544,
  "time": "2018-03-18T06:26:58Z",
  "timestamp": 1521354418,
  "transactions_used": 5
}
```

### Get orbital elements (TLE)

Get a satellite's current two-line element set: the orbital data every tracking and prediction tool reads. Returns both lines separately and as the plain text block those tools expect. Reports 'found: false' when the catalog number has no current elements rather than failing the step.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.

**Outputs**

- `found` (true/false): Whether N2YO has current orbital elements for this catalog number.
- `line1` (text): First line of the two-line element set.
- `line2` (text): Second line of the two-line element set.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `text` (text): The satellite's name and both lines joined by newlines: the plain-text TLE block tracking libraries read.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "found": true,
  "line1": "1 25544U 98067A   18077.09047010  .00001878  00000-0  35621-4 0  9999",
  "line2": "2 25544  51.6412 112.8495 0001928 208.4187 178.9720 15.54106440104358",
  "name": "SPACE STATION",
  "satellite_id": 25544,
  "text": "SPACE STATION\n1 25544U 98067A   18077.09047010  .00001878  00000-0  35621-4 0  9999\n2 25544  51.6412 112.8495 0001928 208.4187 178.9720 15.54106440104358",
  "transactions_used": 4
}
```

### Get radio passes

Get the times a satellite will be high enough above your horizon to work by radio, whatever the light: when it appears, where to point, how high it climbs and how long the window lasts. Set the minimum peak elevation to keep only the passes worth calling on.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.
- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Days ahead (`days`, number): How many days of predictions to return, up to the 10 N2YO computes. From 1 to 10. Default: `10`.
- Minimum peak elevation (degrees) (`min_elevation`, number): Only return passes that climb at least this high above the horizon at their peak. The higher the peak, the stronger and longer the radio contact; 40 degrees is a good working pass. From 0 to 90. Default: `40`.
- Time zone (`timezone`, text): Optional. A time-zone database name such as 'America/New_York'. Every time in the result is also reported as local wall-clock time in this zone, which is what a person reading 'the ISS passes over at...' needs. Leave empty to get UTC only.

**Outputs**

- `count` (number): How many passes were returned.
- `days` (number): How many days ahead were searched.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `passes` (list): The radio passes, soonest first. The visual-only fields (start and end elevation, magnitude, visible seconds) are empty for these.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "count": 1,
  "days": 2,
  "name": "SPACE STATION",
  "passes": [
    {
      "above_horizon_seconds": 630,
      "end_azimuth": 118.6,
      "end_compass": "ESE",
      "end_elevation": null,
      "end_local_time": "2018-03-19 05:32:05 EDT",
      "end_time": "2018-03-19T09:32:05Z",
      "end_timestamp": 1521451925,
      "magnitude": null,
      "max_azimuth": 37.98,
      "max_compass": "NE",
      "max_elevation": 52.19,
      "max_local_time": "2018-03-19 05:26:55 EDT",
      "max_time": "2018-03-19T09:26:55Z",
      "max_timestamp": 1521451615,
      "start_azimuth": 311.57,
      "start_compass": "NW",
      "start_elevation": null,
      "start_local_time": "2018-03-19 05:21:35 EDT",
      "start_time": "2018-03-19T09:21:35Z",
      "start_timestamp": 1521451295,
      "visible_seconds": null
    }
  ],
  "satellite_id": 25544,
  "transactions_used": 2
}
```

### Get the next pass

Answer 'when can I next see it?' in one step: the soonest pass over your location, with how long until it starts, where it rises, how high it climbs and where it sets. Choose whether that means a pass you can see or one you can work by radio. Returns 'found: false' when nothing qualifies in the window rather than failing the step.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.
- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Kind of pass (`pass_type`, text): Whether to look for a pass you can see with the naked eye, or one high enough above the horizon to work by radio. One of: `visual` (Visual: passes you can see with the naked eye), `radio` (Radio: passes high enough to work by radio). Default: `visual`.
- Days ahead (`days`, number): How many days of predictions to return, up to the 10 N2YO computes. From 1 to 10. Default: `10`.
- Minimum visible seconds (`min_visibility`, number): Only return passes visible for at least this many seconds. 300 (five minutes) keeps the passes worth going outside for; lower it to about 60 to catch brief ones near the horizon. From 0 to 1200. Default: `300`.
- Minimum peak elevation (degrees) (`min_elevation`, number): Only return passes that climb at least this high above the horizon at their peak. The higher the peak, the stronger and longer the radio contact; 40 degrees is a good working pass. From 0 to 90. Default: `40`.
- Time zone (`timezone`, text): Optional. A time-zone database name such as 'America/New_York'. Every time in the result is also reported as local wall-clock time in this zone, which is what a person reading 'the ISS passes over at...' needs. Leave empty to get UTC only.

**Outputs**

- `above_horizon_seconds` (number): How long the whole pass lasts from appearing to disappearing, in seconds. Worked out from the start and end times, so it is reported for radio passes too.
- `days` (number): How many days ahead were searched.
- `end_azimuth` (number): Bearing the satellite disappears at, in degrees.
- `end_compass` (text): The bearing it disappears at, as a compass point.
- `end_elevation` (number): How high above the horizon it disappears, in degrees. Only reported for visual passes.
- `end_local_time` (text): When the pass ends, as wall-clock time in the requested time zone, or empty when no time zone was given.
- `end_time` (text): When the pass ends, as an ISO 8601 UTC date-time.
- `end_timestamp` (number): When the pass ends, in Unix seconds.
- `found` (true/false): Whether a pass was found in the window. When false, every field describing the pass is empty.
- `magnitude` (number): How bright the pass gets, on the same scale as star brightness: lower is brighter, and -2 is brighter than any star. Empty for a radio pass, and for a visual pass whose brightness N2YO cannot determine.
- `max_azimuth` (number): Bearing of the highest point, in degrees.
- `max_compass` (text): Bearing of the highest point as a compass point.
- `max_elevation` (number): How high the satellite climbs at its peak, in degrees above the horizon. This is the number that decides how good a pass is.
- `max_local_time` (text): When it peaks, as wall-clock time in the requested time zone, or empty when no time zone was given.
- `max_time` (text): When it peaks, as an ISO 8601 UTC date-time.
- `max_timestamp` (number): When the pass reaches its highest point, in Unix seconds.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `pass_type` (text): Which kind of pass was searched for: 'visual' or 'radio'.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `start_azimuth` (number): Bearing the satellite appears at, in degrees clockwise from north.
- `start_compass` (text): The same bearing as a compass point, e.g. 'NW'.
- `start_elevation` (number): How high above the horizon it appears, in degrees. Only reported for visual passes.
- `start_local_time` (text): When the pass begins, as wall-clock time in the requested time zone, or empty when no time zone was given.
- `start_time` (text): When the pass begins, as an ISO 8601 UTC date-time.
- `start_timestamp` (number): When the pass begins, in Unix seconds.
- `starts_in_seconds` (number): How long until the pass begins, in seconds from now. 0 if it has already begun.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.
- `visible_seconds` (number): How long the satellite is optically visible during the pass, in seconds. Only reported for visual passes.

**Example output**

```json
{
  "above_horizon_seconds": 635,
  "days": 10,
  "end_azimuth": 132.82,
  "end_compass": "SE",
  "end_elevation": 0,
  "end_local_time": "2018-03-18 06:24:20 EDT",
  "end_time": "2018-03-18T10:24:20Z",
  "end_timestamp": 1521368660,
  "found": true,
  "magnitude": -2.4,
  "max_azimuth": 225.45,
  "max_compass": "SW",
  "max_elevation": 78.27,
  "max_local_time": "2018-03-18 06:19:05 EDT",
  "max_time": "2018-03-18T10:19:05Z",
  "max_timestamp": 1521368345,
  "name": "SPACE STATION",
  "pass_type": "visual",
  "satellite_id": 25544,
  "start_azimuth": 307.21,
  "start_compass": "NW",
  "start_elevation": 13.08,
  "start_local_time": "2018-03-18 06:13:45 EDT",
  "start_time": "2018-03-18T10:13:45Z",
  "start_timestamp": 1521368025,
  "starts_in_seconds": 13607,
  "transactions_used": 4,
  "visible_seconds": 485
}
```

### Get visible passes

Get the times a satellite will be visible to the naked eye from your location: when it appears, where to look, how high it climbs, how bright it gets and how long it stays visible. A visible pass needs the satellite in sunlight over a dark sky, so this list is far shorter than the times it simply flies over.

**Inputs**

- Satellite (NORAD ID) (`satellite_id`, number): The satellite's NORAD catalog number. Defaults to 25544, the International Space Station. To find another object's number, search for it at https://www.n2yo.com and read the NORAD ID off its page. Use the catalog number (100057), not the Alpha-5 form a TLE shows (A0057). Default: `25544`.
- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Days ahead (`days`, number): How many days of predictions to return, up to the 10 N2YO computes. From 1 to 10. Default: `10`.
- Minimum visible seconds (`min_visibility`, number): Only return passes visible for at least this many seconds. 300 (five minutes) keeps the passes worth going outside for; lower it to about 60 to catch brief ones near the horizon. From 0 to 1200. Default: `300`.
- Time zone (`timezone`, text): Optional. A time-zone database name such as 'America/New_York'. Every time in the result is also reported as local wall-clock time in this zone, which is what a person reading 'the ISS passes over at...' needs. Leave empty to get UTC only.

**Outputs**

- `count` (number): How many passes were returned.
- `days` (number): How many days ahead were searched.
- `name` (text): The satellite's name, e.g. 'SPACE STATION'.
- `passes` (list): The visible passes, soonest first.
- `satellite_id` (number): NORAD catalog number of the satellite the answer is about.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "count": 1,
  "days": 2,
  "name": "SPACE STATION",
  "passes": [
    {
      "above_horizon_seconds": 635,
      "end_azimuth": 132.82,
      "end_compass": "SE",
      "end_elevation": 0,
      "end_local_time": "2018-03-18 06:24:20 EDT",
      "end_time": "2018-03-18T10:24:20Z",
      "end_timestamp": 1521368660,
      "magnitude": -2.4,
      "max_azimuth": 225.45,
      "max_compass": "SW",
      "max_elevation": 78.27,
      "max_local_time": "2018-03-18 06:19:05 EDT",
      "max_time": "2018-03-18T10:19:05Z",
      "max_timestamp": 1521368345,
      "start_azimuth": 307.21,
      "start_compass": "NW",
      "start_elevation": 13.08,
      "start_local_time": "2018-03-18 06:13:45 EDT",
      "start_time": "2018-03-18T10:13:45Z",
      "start_timestamp": 1521368025,
      "visible_seconds": 485
    }
  ],
  "satellite_id": 25544,
  "transactions_used": 4
}
```

### List satellites above you now

List everything N2YO is tracking in a patch of sky above your location right now, with each object's name, catalog number, launch date, height and the point on Earth it is over. Narrow the search to a category (Starlink, amateur radio, weather, the ISS) and set how wide a patch of sky to sweep.

**Inputs**

- Your latitude (`latitude`, number, required): Latitude of the place you are observing from, in decimal degrees (-90 to 90). Negative is south of the equator. From -90 to 90.
- Your longitude (`longitude`, number, required): Longitude of the place you are observing from, in decimal degrees (-180 to 180). Negative is west of Greenwich. From -180 to 180.
- Your altitude (metres) (`observer_altitude`, number): Height above sea level of the place you are observing from, in metres. Leave at 0 unless you are somewhere high; it barely moves the answer at everyday elevations. From -500.0 to 10000.0. Default: `0.0`.
- Search radius (degrees) (`search_radius`, number): How wide a patch of sky to sweep, measured out from straight overhead. A small number finds only what is almost directly above you; 90 returns everything above the horizon. From 0 to 90. Default: `70`.
- Category (`category_id`, text): Which kind of object to look for. Leave on 'All categories' to include everything in the sky, debris and rocket bodies included. One of: `0` (All categories), `18` (Amateur radio), `35` (Beidou Navigation System), `1` (Brightest), `45` (Celestis), `54` (Chinese Space Station), `32` (CubeSats), `8` (Disaster monitoring), `6` (Earth resources), `29` (Education), and 48 more. Default: `0`.

**Outputs**

- `category` (text): Name of the category that was searched, e.g. 'Amateur radio' or 'All categories'.
- `category_id` (number): N2YO's id for that category; 0 means every category.
- `count` (number): How many objects were returned.
- `satellites` (list): The objects found in that patch of sky.
- `search_radius` (number): How wide a patch of sky was swept, in degrees out from straight overhead.
- `transactions_used` (number): How many calls this API key has made in the last 60 minutes, as N2YO counts them. The free hourly limits are 1000 each for orbital elements and positions, and 100 each for visual passes, radio passes and 'what is above me'.

**Example output**

```json
{
  "category": "Amateur radio",
  "category_id": 18,
  "count": 2,
  "satellites": [
    {
      "altitude_km": 1227.9326,
      "international_designator": "1990-013C",
      "latitude": 49.5744,
      "launch_date": "1990-02-07",
      "longitude": -96.7081,
      "name": "JAS 1B (FUJI 2)",
      "satellite_id": 20480
    },
    {
      "altitude_km": 49678.6389,
      "international_designator": "2000-072B",
      "latitude": 5.5105,
      "launch_date": "2000-11-16",
      "longitude": -21.4478,
      "name": "AMSAT OSCAR 40",
      "satellite_id": 26609
    }
  ],
  "search_radius": 70,
  "transactions_used": 17
}
```