Spectator API docs

Welcome to Spectator API docs! Our API allows you to interact with Spectator programmatically using its functionalities and data directly. You can search for data, request images in high resolution, track satellite passes and more. To use the API, you'll need a key that is automatically generated for every account at https://app.spectator.earth and can be found in the profile panel.

If there is any functionality that you would like to see in this API, don't hesitate to contact us at api@spectator.earth

License and usage limits

The free API access is for individual, non-commercial use only. For professional plans and usage limits, please visit our pricing page.

Output data types

Unless specified otherwise, the default formats and conventions are listed below.

General

The default output from all the endpoints is JSON.

Geographic data

the default output format is GeoJSON
when defining coordinates the convention used is longitude, latitude
the default reference coordinate system is WGS84(EPSG:4326)

Dates

All dates are provided in UTC using ISO 8601 format.

Acquisition plan

For some satellites, Spectator uses KML files provided by ESA and USGS in order to determine if the overpassing satellite will acquire image over an area of interest. In the app, you can view acquisition plans for Sentinel-2, Landsat-8, Landsat-9 and Sentinel-1 here. This end-point serves raw data converted to a GeoJSON format.

Query Parameters

Name	Description	Format	Required/Optional
`satellites`	list of satellite names	string	optional(default all)
`datetime`	date	string	optional (default today's date)

Output description

The output will vary, depending on the satellite. For more information check out acquisition plan file descriptions for Sentinel-1, Sentinel-2, Landsat-8

GET

/acquisition-plan/

$ curl https://api.spectator.earth/acquisition-plan/?api_key=YOUR_API_KEY

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              157.52060705321486,
              7.591169002363054
            ],
            [
              156.2451078116898,
              7.871921228836858
            ],
            [
              155.78705786603518,
              5.785692392466027
            ],
            [
              157.05736567642157,
              5.504778540100358
            ],
            [
              158.32641183205322,
              5.221190665901193
            ],
            [
              158.79435324996862,
              7.306721023218564
            ],
            [
              157.52060705321486,
              7.591169002363054
            ]
          ]
        ]
      },
      "properties": {
        "id": "40825-4",
        "scenes": "10",
        "station": "SGS_",
        "timeliness": "NOMINAL",
        "orbit_absolute": "40825",
        "orbit_relative": "73",
        "observation_duration": "36080",
        "begin_time": "2023-04-17T00:04:32Z",
        "end_time": "2023-04-17T00:05:08Z",
        "satellite": "Sentinel-2A"
      }
    }
  ]
}

Satellites

You can list all available satellites, or optionally, query particular one by ID.

Query Parameters

Name	Description	Format	Required/Optional
`id`	satellite ID	integer	required

Output description

Key	Description	Format
`id`	satellite ID	integer
`geometry`	current satellite position	GeoJSON Point
`norad_id`	satellite catalog number	integer
`sensors`	sensors available on the satellite (SAR or Optical)	string
`avg_footprint_width`	average swath width of the sensors on board of the satellite	string
`open`	whether the data produced by the satellite is freely accessible	boolean

GET

/satellite/{id}/

$ curl https://api.spectator.earth/satellite/1/?api_key=YOUR_API_KEY

{
  "id": 1,
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -85.26938616457066,
      56.52063558777416,
      704902.0625
    ]
  },
  "properties": {
    "name": "Sentinel-1A",
    "norad_id": 39634,
    "modes": [
      {
        "name": "IW",
        "swath": 250000,
        "sensor_type": "SAR"
      }
    ],
    "open": true,
    "platform": "Sentinel-1A",
    "is_data_connected": false
  }
}

Trajectories

A trajectory is a set of points, that describe the orbit of the satellite. The trajectory is calculated with a 60-seconds interval. This endpoint returns the trajectory for one full orbit.

Query parameters

Name	Description	Format	Required/Optional
`id`	satellite ID	integer	required

Output description

Key	Description	Format
`geometry`	trajectory geometry for current full orbit	GeoJSON LineString
`norad_id`	satellite catalog number	integer
`update_interval`	the time interval in seconds, between consequent points in the geometry	integer

GET

/satellite/{id}/trajectory/

$ curl https://api.spectator.earth/satellite/1/trajectory/?api_key=YOUR_API_KEY

{
  "id": 1,
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [...]
  },
  "properties": {
    "norad_id": 39634,
    "update_interval": 60.0
  }
}

Searching for images

The API allows you to query all images available thorugh Spectator. You can search by bounding box or more complex geometry. You can also filter by date, satellite, cloud coverage and product type.

Note: At the moment the commercial imagery is only available through the app

Query Parameters

Name	Description	Format	Required/Optional
`api_key`	your API key	string	required
`bbox`	area of interest bounding box	list of coords (lon, lat, lon, lat)	required if geometry parameter not present
`geometry`	area of interest geometry	GeoJSON or WKT	required if bbox parameter not present
`date_from`	earliest image date	yyyy-mm-dd	optional
`date_to`	latest image date	yyyy-mm-dd	optional
`satellites`	which satellites to include	string (Sentinel-1A, Sentinel-1A, Sentinel-2A, Sentinel-2B, Sentinel-3A, Landsat-8)	optional
`cc`	cloud coverage on the image	float	optional
`cc_more_than`	cloud coverage on the image	float	optional
`cc_less_than`	cloud coverage on the image	float	optional
`product_type`	type of product	string	optional
`page`	page	int	optional

GET

/imagery/

$ curl https://api.spectator.earth/imagery/?bbox=19.59,49.90,20.33,50.21&api_key=YOUR_API_KEY

{
  "page": 1,
  "total_pages": 5,
  "next": "https://api.spectator.earth/imagery/?bbox=19.59,49.90,20.33,50.21&api_key=YOUR_API_KEY",
  "previous": null,
  "results": [
    {
      "id": 1,
      "uuid": "e00175f5-c05c-43fc-aedd-15789d64611e",
      "identifier": "S2A_MSIL1C_20180910T095031_N0206_R079_T34UDA_20180910T135526",
      "ingestion_date": "2018-09-10T17:26:05.649000Z",
      "begin_position_date": "2018-09-10T09:50:31.024000Z",
      "end_position_date": "2018-09-10T09:50:31.024000Z",
      "download_url": "https://api.spectator.earth/imagery/1/files/",
      "size": "657.46 MB",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              21.020836834433233,
              50.551570884414545
            ],
            [
              19.588086136628576,
              50.54373233188457
            ],
            [
              19.616762732856103,
              49.55648784343155
            ],
            [
              20.534975843268384,
              49.561440226336195
            ],
            [
              20.53972899782644,
              49.57134302004747
            ],
            [
              20.60946588948272,
              49.71588332371029
            ],
            [
              20.67990158730716,
              49.8603553771008
            ],
            [
              20.75074048958287,
              50.004805561228125
            ],
            [
              20.821890130174616,
              50.14927412809048
            ],
            [
              20.89320850940868,
              50.29366845966536
            ],
            [
              20.964533641882408,
              50.43801074083652
            ],
            [
              21.020836834433233,
              50.551570884414545
            ]
          ]
        ]
      },
      "satellite": "Sentinel-2A",
      "scene_id": "S2A_tile_20180910_34UDA_0",
      "cloud_cover_percentage": "4.97",
      "product_type": "S2MSI1C"
    }
  ]
}

Imagery files

Satellite imagery is stored in separate files for each band. You can download these files for given image directly from the API.

Query parameters

Name	Description	Format
`api_key`	your API key	string
`id`	imagery id	int

GET

/imagery/{id}/files/

$ curl https://api.spectator.earth/imagery/1/files/?api_key=YOUR_API_KEY

 [
  {
    "name": "B01.jp2",
    "path": "B01.jp2",
    "size": 3753753,
    "url": "https://api.spectator.earth/imagery/1/files/B01.jp2/"
  },
  {
    "name": "B02.jp2",
    "path": "B02.jp2",
    "size": 105748580,
    "url": "https://api.spectator.earth/imagery/1/files/BB02.jp2/"
  }
]

Map tiles

Images can be requested as map tiles using Slippy Map Tilenames. You can define the tile size and the bands to use in the formula. Depending on which satellite you are using, please have a look at the notes and example below the parameters table.

Query parameters

Name	Description	Format	Required/Optional
api_key	your API key	string	required
id	image id	int	required
bands_formula	bands formula to use	string	required
tilesize	tile size	int	optional (default=512)
rescale	range of values to rescale single band image(e.g. NDVI)	int,int	required only for indices(e.g. NDVI)

Note 1: Sentinel-2 band names are zero padded. E.g. bands_formula=b04,b03,b02. For Landsat-8 the same band combination would be bands_formula=b4,b3,b2.

Note 2: The rescale parameter has to be used only when bands_formula results in single-band image, like in the case of NDVI. When using NDVI through the app the default value is -1,1

If you're looking for an example on how to use this end-point, check our short tutorial, which shows how to display Sentinel-2 image using LeafletJS.

GET

api.spectator.earth/imagery/{id}/tiles/{z}/{x}/{y}/?bands_formula=b04,b03,b02&api_key=YOUR_API_KEY

High-resolution image

If you don't want to download the whole image which can be time consuming, the API can provide you with a high-resolution image for the area within the acquisition boundaries,

Query parameters

Name	Description	Format	Required/Optional
`api_key`	your API key	string	required
`id`	image id	int	required
`bands`	bands	int, int, int	required
`bbox`	area of interest bounding box	list of coords (lon, lat, lon, lat)	optional
`width`	Image width	int	optional
`height`	Image height	int	optional

Example URL for Sentinel-2 image of spectator.earth office in Kraków, Poland:

https://api.spectator.earth/imagery/18613048/preview?bands=4,3,2&bbox=19.871177673339847,50.009200785980795,19.
91430759429932,50.0312047240888162&height=798&width=1005&api_key=YOUR_API_KEY

preview

GET

api.spectator.earth/imagery/{id}/preview/?api_key=YOUR_API_KEY

Satellite overpasses

You can query for overpasses of chosen satellite over defined area of interest. The output provides you with a satellite sensor footprint for the nearest overpass, overpass frequency in seconds and (if available) information about planned acquisition during given overpass.

Note:

By default the overpasses are retrieved for 7 days starting with the current date. You can manipulate this time span with days_before and days_after parameters.
The maximum number of days (days_after) is defined by plan limit

Query parameters

Name	Description	Format	Required/Optional
`api_key`	your API key	string	required
`bbox`	area of interest bounding box	list of coords (lon, lat, lon, lat)	required if geometry parameter not present
`geometry`	area of interest geometry	GeoJSON or WKT	required if bbox parameter not present
`satellites`	which satellites to include	string (Sentinel-1A, Sentinel-1A, Sentinel-2A, Sentinel-2B, Sentinel-3A, Landsat-8)	optional
`days_before`	a number of days before the current date for which overpasses should be computed	integer	optional, default=0
`days_after`	a number of days after the current date for which overpasses should be computed	integer	optional, default=7, max=defined by plan

Output description

Key	Description	Format
`frequency`	the frequency of overpasses per day w.r.t. input parameters	float
`overpasses`	list of overpasses	list
`date`	overpass date	date
`visibility_footprint`	the area on earth from which the satellite is visible	Polygon
`geometry`	GeoJSON Point describing the position of the satellite	Point
`footprints`	list of sensor footprints(the area on earth that the sensor can image)	FeatureCollection
`acquisition`	whether the image will be acquired(null if the acquisition plan for the satellite isn't available)	boolean or null

GET

/overpass/

$ curl https://api.spectator.earth/overpass/?bbox=19.59,49.90,20.33,50.21&satellites=Sentinel-2A&api_key=YOUR_API_KEY

{
  "frequency": 0.89,
  "overpasses": [
    {
      "id": 3579609,
      "date": "2023-04-17T20:29:19.928324Z",
      "visibility_footprint": {
        "type": "Polygon",
        "coordinates": [
          ...
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          20.93649348547546,
          47.41106601159571,
          795606.5625
        ]
      },
      "satellite": "Sentinel-2B",
      "footprints": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    22.87062053752537,
                    47.394747548147194
                  ],
                  [
                    19.00236643342555,
                    47.394747548147194
                  ],
                  [
                    17.370808257052193,
                    50.87677772043564
                  ],
                  [
                    21.52005665056863,
                    50.87677772043564
                  ],
                  [
                    22.87062053752537,
                    47.394747548147194
                  ]
                ]
              ]
            },
            "properties": {
              "mode": {
                "name": "MSI",
                "swath": 292000,
                "sensor_type": "OPTICAL"
              },
              "acquisition": false
            }
          }
        ]
      }
    }
  ]
}