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:

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:

cURL Python JS