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 overpasses and more. To use most of the endpoints, you'll need a key that is automatically generated for every account at https://app.spectator.earth.

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

License

The free API access is for individual, non-commercial use only. If you're interested in research or commercial plans, please contact us at api@spectator.earth

Usage limits

The usage limits for a free account are as follows:

  • total number of requests - 10000 per day
  • imagery and overpasses - 50 per second
  • other - 100 per second

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

Spectator uses KML files provided by ESA and USGS in order to determine if the overpassing satellite will aquire image. In the app, you can view acquisition plans for Sentinel-2, Landsat-8 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
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/
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [23.41016, 65.92093],
            [17.85194, 56.26917],
            [11.21702, 56.9874],
            [14.37274, 66.76553],
            [23.41016, 65.92093]
          ]
        ]
      },
      "properties": {
        "mode": "EW",
        "swath": null,
        "datatake_id": "28900",
        "polarisation": "DH",
        "orbit_absolute": "21369",
        "orbit_relative": "168",
        "begin_time": "2020-04-30T05:20:59Z",
        "end_time": "2020-04-30T05:23:43Z",
        "satellite": "Sentinel-1B"
      }
    }
    ...
  ]
}

Satellites

You can list all satellites available in the database, 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/
{
  "id": 1,
  "type": "Feature",
  "geometry": {"type": "Point", "coordinates": [-26.872113191808623, 81.60216398554945]},
  "properties": {
    "name": "Sentinel-1A",
    "norad_id": 39634,
    "sensors": [{"type": "SAR", "avg_footprint_width": "2.00"}],
    "open": true,
    "platform": "Sentinel-1A"
  }
}

Trajectories

Each satellite in the database has a trajectory computed based on its orbital data. You can access the trajectory for every satellite.

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
{
  "id": 1,
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [163.2641973913492, -80.94058302334582],
      ...
   ]
  },
  "properties": {"norad_id": 39634, "update_interval": 60}
}

Searching for images

Spectator database stores information about data for multiple different satellites including Sentinel constellation and Landsat 8.

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/?api_key=KEY&bbox=19.59,49.90,20.33,50.21
{
  "page": 1,
  "total_pages": 5,
  "next": "https://api.spectator.earth/imagery/?api_key=KEY&bbox=19.59,49.90,20.33,50.21&page=2",
  "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

You can download separate band 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=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 from satellites such as Sentinel-2 and Landsat 8 can be requested as map tiles using Slippy Map Tilenames

Query parameters

Name Description Format Required/Optional
api_key your API key string required
id image id int required
bands_formula satellite bands 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 app.spectator.earth 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=KEY

High resolution image

The API can provide you with a high resolution image for the area within the acquisition boundaries, if you're not interested in downloading the whole image.

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) required
width Image width int required
height Image height int required
cutoff - int optional (default=2)
GET
api.spectator.earth/imagery/{id}/preview/?api_key=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:

  1. By default the overpasses are computed for 7 days starting with the current date. You can manipulate this time span with days_before and days_after parameters.

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
GET
/overpass/
$ curl https://api.spectator.earth/overpass/?api_key=KEY&bbox=19.59,49.90,20.33,50.21&satellites=Sentinel-2A
{
  "frequency": 10836,
  "overpasses": [
    {
      "geometry": {
        "type": "Point",
        "coordinates": [
          18.23460896114911,
          48.96885000910966
        ]
      },
      "satellite": "Sentinel-2A",
      "date": "2019-09-15T09:57:00.954582Z",
      "acquisition": true,
      "footprint": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              20.9763522050022,
              50.31828988843672
            ],
            [
              17.044414480297707,
              51.06678412949347
            ],
            [
              15.668580315420332,
              47.54121882033102
            ],
            [
              19.369050751431633,
              46.87290373813614
            ],
            [
              20.9763522050022,
              50.31828988843672
            ]
          ]
        ]
      }
    }
  ]
}
Show examples in: