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

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

URL parameter Description Format Required/Optional
satellites list of satellite names string optional
datetime list of satellite names string optional (default today 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

URL parameter 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

URL parameter 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

Property 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
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

Property Description Format
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

URL parameter Description Format Required/Optional
key your API key string required
id image id int required
bands bands int, int, int required
tile_size Tile size int optional (default 256)
cutoff - int optional (default 2)
GET
api.spectator.earth/imagery/{id}/tiles/{z}/{x}/{y}/?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.

URL parameter Description Format Required/Optional
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

URL parameter Description Format Required/Optional
key your API key string
required
bbox area of interest bounding box list of coords (lon, lat, lon, lat)
required
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: