DEA logo
v1.0.0
< Back to App

About SatPaths API

On this page

What the API offers
Applications
Common uses
Detailed Instructions

What this API Offers

SatPaths API service calculates date-specific, predicted schedules for flyovers over Australia for 19 of the most popular public good satellites used by researchers in academia, and by public and private sector organisations. Information is delivered in GeoJSON or CSV (tabular) formats for use in third party online applications and GIS tools.

Applications

The information helps to answer three basic questions:

  • what satellites are flying over Australia on a particular day, where and at what time?
  • which of those satellites will potentially acquire data over the area of specific interest?; and
  • which ground stations in the ANGSTT network those satellites are visible from, hence which of those stations could potentially downlink the data?

Common Uses

Full day schedule of satellite passes over Australia

API GET call (default):

https://satpathapi.dea.ga.gov.au/passes

Response description (default):

Start and end times (in UTC) for each satellite overpass over Australia, from midnight to midnight Australian Eastern Standard Time (including satellite ground track and footprint representing the portion of the ground visible by the sensor on board that satellite).

Additional options & filters available:

  1. Filter by start – end time limits (could be hours or days apart)

    https://satpathapi.dea.ga.gov.au/passes?start=2021-08-19T00:00:00&end=2021-08-19T23:59:00

    Note: results more than 10 days into the future will be indicative only as there are no parameters available to predict satellite position accurately; dates in the past will use historical parameters for accurate calculations.

  2. Reduce list to selected satellites only:

    https://satpathapi.dea.ga.gov.au/passes?format=json&satellites=25994&satellites=27424

  3. Reduce list to satellites whose footprints cross Area of Interest (AOI) location (defined as either a point or a polygon in WKT format):

    https://satpathapi.dea.ga.gov.au/passes?geometry=Point%20(151.071035%20-33.865966)

  4. Clip output to AOI polygon extents:

    https://satpathapi.dea.ga.gov.au/passes?geometry=POLYGON%20((143.701171875%20-11.867350911459294,%20142.20703125%20-9.79567758282973,%20127.39746093749999%20-11.092165893501988,%20148.271484375%20-43.89789239125796,%20154.51171875%20-28.14950321154457,%20152.578125%20-20.715015145512087,%20143.701171875%20-11.867350911459294))&format=json&satellites=40697&clip=1

  5. Limit number of passes per satellite to include in the output:

    https://satpathapi.dea.ga.gov.au/passes?json&satellites=25994&limit=2

  6. Output as comma delimited text file ("csv") or GeoJSON ("json"):

    https://satpathapi.dea.ga.gov.au/passes?format=json

  7. Sort results according to time "asc" / "desc":

    https://satpathapi.dea.ga.gov.au/passes?order=desc

Next pass over Australia

API GET call (default):

https://satpathapi.dea.ga.gov.au/next-pass

Response description (default):

For each satellite on the list, start and end times (in UTC) of the next overpass over Australia that will happen between now and 24hrs from now (including satellite ground track and footprint representing portion of the ground visible by the sensor on board of that satellite).

Additional options available:

  1. End time (could be hours or days later than the current time)
  2. List to selected satellites only
  3. Reduce list to satellites whose footprints cross Area of Interest (AOI) location (defined as either a point or polygon)
  4. Output as comma text delimited file ("csv") or GeoJSON ("json")

Example: next Landsat 8 overpass over AOI (Sydney) with date 16 days into the future:

https://satpathapi.dea.ga.gov.au/next-pass?satellites=39084&end=2021-11-16T23:59:00&geometry=Point%20(151.205597%20-33.880198)&format=json

Last pass over Australia

API GET call (default):

https://satpathapi.dea.ga.gov.au/last-pass

Response description (default):

For each satellite on the list, start and end times (in UTC) of the latest overpass over Australia that happened between now and 24hrs ago (including satellite ground track and footprint representing portion of the ground visible by the sensor on board of that satellite).

Additional options available:

  1. Start time (could be hours or days earlier than the current time)
  2. List to selected satellites only
  3. Reduce list to satellites whose footprints cross Area of Interest (AOI) location (defined as either a point or polygon)
  4. Output as comma text delimited file ("csv") or GeoJSON ("json")

Example: last TERRA overpass over AOI (Sydney):

https://satpathapi.dea.ga.gov.au/last-pass?satellites=25994&geometry=Point%20(151.205597%20-33.880198)

Satellite ground position

API GET call (default):

https://satpathapi.dea.ga.gov.au/satellite-position/{satellite_meta}

Response description (default):

For a single satellite (specified by a NORAD ID number), time (in UTC) and location the satellite is at that time (as a point on satellite ground track and path segment representing portion of the ground visible by the sensor on board of that satellite); default interval between ground track locations is 60 seconds.

Additional options available:

  1. Start and end time (could be hours or days apart)
  2. Limit number of passes per satellite to include in the output
  3. Output as comma text delimited file ("csv") or GeoJSON ("json")
  4. Sort results according to time "asc" / "desc"
  5. Resolution representing time interval between points on the ground track (any number between 1 and 60 seconds)

Example: Landsat-8 overpass ground tracks in 10 sec intervals:

https://satpathapi.dea.ga.gov.au/satellite-position/39084?format=json&resolution=10

Satellite precise time for AOI

API GET call (default):

http://sat-path-api.spectator.world/time-at-location?geometry=Point%20(133.88%20-23.75)

*geometry parameter is required

Response description (default):

Time (in UTC) satellite will reach specified location (for data capture); if location is a polygon, it will be time for the centre of the polygon.

Additional options available:

  1. Start and end time (could be hours or days apart)
  2. List of selected satellites only
  3. Limit number of passes per satellite to include in the output
  4. Output as comma text delimited file ("csv") or GeoJSON ("json")
  5. Sort results according to time "asc" / "desc"

Example: Get Landsat 8 predicted scene centre time:

https://satpathapi.dea.ga.gov.au/time-at-location?geometry=POLYGON%20((148.62527487231429%20-35.161079450604035,149.05%20-33.7149,149.05027533228073%20-33.7149399987292,151.01768553603569%20-34.000754316439327,151.018%20-34.0008,151.00505403284856%20-34.048715943616187,150.99782439193615%20-34.075474474846175,150.61%20-35.5109,150.60933454721101%20-35.510803273345857,148.608%20-35.2199,148.62527487231429%20-35.161079450604035))&satellites=39084

Satellite visibility from location

API GET call (default):

https://satpathapi.dea.ga.gov.au/visibility?elevation=5

*elevation parameter is required

Response description (default):

Start and end times (in UTC) for each satellite overpass over Australia, from midnight to midnight Australian Eastern Standard Time (including satellite ground track and footprint representing portion of the ground visible by the sensor on board of that satellite) where the satellite is visible by any of the seven ANGSTT stations (default).

Additional options available:

  1. Start and end time (could be hours or days apart)
  2. List of selected satellites only
  3. Limit number of passes per satellite to include in the output
  4. Output as comma text delimited file ("csv") or GeoJSON ("json")
  5. Sort results according to time "asc" / "desc"
  6. Single location representing observation point – as WKT with longitude, latitude, and Z coordinates
  7. Elevation representing viewing angle over the horizon (in degrees)

Example: Visibility of Landsat-8 from a given point (Sydney) at 50m above sea level and 3 degrees elevation over the horizon:

https://satpathapi.dea.ga.gov.au/visibility?location=Point%20(151.071035%20-33.865966%2050)&elevation=3&satellites=39084&format=json

Detailed Instructions

1. Introduction

SatPaths API was developed to allow users access to information regarding overpasses of a set of predefined Earth observation satellites over the territory of Australia.

This part of the User Guide extends the API documentation available in the home path of the API located at https://satpathapi.dea.ga.gov.au/.

The following paragraphs provide an overview of the API functionality and the algorithms used to produce the outputs.

2. Constants

There are several values used by the API that are set in the source code. In most cases these cannot be altered using input parameters. This section presents these values.

2.1 Satellites and Sensors

The API is configured to generate overpass information for the 19 public good satellites.

Below is an excerpt from the constants file defining each satellite's NORAD id, sensor name and sensor swath width in meters.

AQUA = (27424, 'MODIS', 2_330_000)
LANDSAT_7 = (25682, 'ETM+', 185_000)
LANDSAT_8 = (39084, 'OLI', 185_000)
LANDSAT_9 = (49260, 'OLI', 185_000)
METOP_A = (29499, 'AVHRR', 2_900_000)
METOP_B = (38771, 'AVHRR', 2_900_000)
METOP_C = (43689, 'AVHRR', 2_900_000)
NOAA_15 = (25338, 'AVHRR', 2_940_000)
NOAA_18 = (28654, 'AVHRR', 2_940_000)
NOAA_19 = (33591, 'AVHRR', 2_940_000)
NOAA_20 = (43013, 'VIIRS', 2_940_000)
NPP = (37849, 'VIIRS', 3_040_000)
SENTINEL_1A = (39634, 'C-SAR', 250_000, SENTINEL_1_CHARACTERISTICS)
SENTINEL_1B = (41456, 'C-SAR', 250_000, SENTINEL_1_CHARACTERISTICS)
SENTINEL_2A = (40697, 'MSI', 290_000)
SENTINEL_2B = (42063, 'MSI', 290_000)
SENTINEL_3A = (41335, 'SLSTR', 1_270_000)
SENTINEL_3B = (43437, 'SLSTR', 1_270_000)
TERRA = (25994, 'MODIS', 2_350_000)

2.2 Ground Stations

For all endpoints (with the exception of visibility) a predefined set of ground stations is used to determine an initial set of visible satellites. This is the entry point for all functionality, therefore if a satellite is not visible by at least one of the stations, it will not be included in the output.

Below is an excerpt from the constants file defining each station code, name and coordinates (longitude, latitude, altitude).

ALS = ('ALS', 'Alice Springs', 133.88, -23.75, 575)
CFQ = ('CFQ', 'Cleveland Bay', 147.05542, -19.2676, 2)
CPT = ('CPT', 'Cribb Point', 145.174482, -38.363939, 5)
HBT = ('HBT', 'Hobart', 147.3386, -42.8874, 15)
LMO = ('LMO', 'Learmonth', 114.084747, -22.22952, 5)
MUR = ('MUR', 'Murdoch', 115.836, -31.06625, 6)
DAR = ('DAR', 'Shoal Bay', 130.984, -12.364, 56)

Default ground stations set.

2.3 Geometry

For all endpoints (with the exception of visibility) the default geometry to perform satellite sensor footprint intersection calculations is an approximate boundary of Australia mainland. The default geometry defined in the code is presented below.

Default geometry used for intersection with satellite sensor footprints.

2.4 Time Zone

The default date and time values for all endpoints are set in the Australian Eastern Standard Time (GMT+10) zone format.

Date and time zone parameters can be modified. All input date parameters use ISO 8601 standard, where time zone has to be specified or it defaults to UTC. In the response, all dates are represented in UTC.

Examples: https://satpathapi.dea.ga.gov.au/passes will compute passes for all satellites for the current day, midnight to midnight in AEST (GMT+10). By modifying start and end parameters, any past and future date can be set by the user, including specific time zone:

https://satpathapi.dea.ga.gov.au/passes?start=2021-06-24T00:00:00&end=2021-06-24T23:59:59

The time range will be 24.06.2021, 00:00:00 UTC to 23:59:59 UTC

3. API Response

This section outlines important aspects the API responses.

3.1 Response format

The response can be obtained in two formats: CSV (format=csv) and GeoJSON (format=json), with CSV being the default for all endpoints.

3.2 Time

All dates presented in the API responses use Coordinated Universal Time (UTC).

3.3 TLE service

Two-line elements (TLEs) are retrieved for each satellite from https://www.space-track.org/. To ensure maximum location accuracy, the API takes the TLE closest to a given input date and time.

Example: The user requests all passes for a given day and satellite. There are 2 passes on that day over Australia:

  • pass 1 starting at 8:00
  • pass 2 starting at 12:00

Space Track publishes a TLE for each satellite every 1 hour, starting at 00:00. So, to compute satellite coordinates at pass 1, the API will use the TLE from 8:00 and for pass 2, TLE from 12:00.

Every TLE file is downloaded only once and then cached on the server. This results in response times being slightly longer when users request a new period for the first time. The cache for TLE files expires after 30 days.

3.4 Satellite trajectory

Satellite trajectory coordinates are computed using the most relevant TLE based on the SGP4 model. The default time resolution used for generating points on the trajectory is 60 seconds. This means that the time interval between each consecutive point is 60 seconds = 1 minute.

In the case of the satellite-position endpoint, this time interval can be controlled by the user with “resolution=” parameter and by specifying an integer value between 1 and 60 seconds.

3.5 Satellite sensor footprints

Satellite footprints are computed along the trajectory based on coordinates in the trajectory and the sensor swath width. Except for Sentinel-1, all satellites are imaging at the nadir (i.e. looking down directly below the satellite). In the case of Sentinel-1 the acquisitions are performed at an angle which requires the sensor footprint to be offset by 25° off nadir.

Example:

Sentinel-1 trajectory and sensor footprint.


Sentinel-2 trajectory and sensor footprint.

4. API Endpoints

This section describes endpoints available in the API. For the up to date list of all available parameters, please refer to API docs available at satpathapi.dea.ga.gov.au/ .

4.1 Visibility

Visibility endpoint returns all satellites visible either from:

  • default list of ground stations
  • input location

The steps performed to provide output for the user are as follows:

  1. For given input parameters, retrieve required set of satellite TLEs (from cache or Space Track)
  2. Compute position of all satellites
  3. Filter out all satellites that fall below required input elevation angle taking into consideration all default ground stations if input point is not defined.
  4. Compute trajectories and sensor footprints
  5. For each satellite, merge results into a single trajectory and sensor footprint if the satellite is visible from more than one ground station
  6. Convert to requested format and send back the response to the user

Example:

https://satpathapi.dea.ga.gov.au/visibility?elevation=10&satellites=39634

Example output for visibility endpoint with elevation angle=10 and only Sentinel-1A satellite.

4.2 Passes

The steps performed are the same as the visibility endpoint but the set of results is additionally filtered by performing an intersection of input geometry (i.e. Australia polygon by default) with satellite sensor footprints geometry. If there is no intersection, the overpass is excluded for the final result returned to the user.

Example:

https://satpathapi.dea.ga.gov.au/passes?satellites=39634

Passes query performed at the same time as for the visibility endpoint.

4.3 Satellite position

This endpoint returns as a list of points representing satellite position on the trajectory and respective satellite sensor footprints as segments corresponding to each point.

The steps performed in calculating the end result are the same as the visibility endpoint, except that the system does not compute a single geometry for trajectory and satellite sensor footprint, instead producing a list of separate geometries for each time point which is included in the response.

Example:

https://satpathapi.dea.ga.gov.au/satellite-position/39634/

Output produced by satellite position endpoint for Sentinel-1 using default values.

4.4 Time at location

This endpoint computes the times at which a given input geometry is within reach of the specified satellite sensor footprint. If the input is a polygon a centroid of this polygon will be taken for computation. The goal of this endpoint is to provide the user with an exact time at which an image acquisition will happen.

The steps performed to compute the output are the same as the passes endpoint. Then the final step is performed to compute the times when the satellites are at the specified point, using the trajectory nearest to the input geometry.

Example:

Using Alice Springs ground station location the URL will be as follows

https://satpathapi.dea.ga.gov.au/time-at-location?geometry=Point%20(133.88 -23.75)

Example output for default parameters and Alice Springs location.

4.5 Next pass and last pass

Next and last pass endpoints serve as a shortcut to obtain the most recent and upcoming overpass of each satellite. The steps performed by the system are the same as in the case of passes and then for each satellite the system picks the overpass nearest to current date and time.

Example:

https://satpathapi.dea.ga.gov.au/next-pass?satellites=39634

Next pass query performed at the same time as for the visibility endpoint.


https://satpathapi.dea.ga.gov.au/last-pass?satellites=39634

Last pass query performed at the same time as for the visibility endpoint.