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
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
The usage limits for a free account are as follows:
Unless specified otherwise the default formats and conventions are listed below.
General
The default output from all the endpoints is JSON.
Geographic data
longitude, latitude
Dates
All dates are provided in UTC using ISO 8601 format.
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
$ 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"
}
}
...
]
}
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 |
$ 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"
}
}
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 |
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 |
$ 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}
}
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 | |
bbox |
area of interest bounding box | list of coords (lon, lat, lon, lat) | |
geometry |
area of interest geometry | GeoJSON or WKT | |
date_from |
earliest image date | yyyy-mm-dd | |
date_to |
latest image date | yyyy-mm-dd | |
satellites |
which satellites to include | string (Sentinel-1A, Sentinel-1A, Sentinel-2A, Sentinel-2B, Sentinel-3A, Landsat-8) |
|
cc |
cloud coverage on the image | float | |
cc_more_than |
cloud coverage on the image | float | |
cc_less_than |
cloud coverage on the image | float | |
product_type |
type of product | string |
|
page |
page | int |
$ 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"
}
]
}
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 |
$ 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/"
}
...
]
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.
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) |
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:
days_before
and days_after
parameters.Query parameters
Name | Description | Format | Required/Optional |
---|---|---|---|
api_key |
your API key | string | |
bbox |
area of interest bounding box | list of coords (lon, lat, lon, lat) | |
geometry |
area of interest geometry | GeoJSON or WKT | |
satellites |
which satellites to include | string (Sentinel-1A, Sentinel-1A, Sentinel-2A, Sentinel-2B, Sentinel-3A, Landsat-8) |
|
days_before |
a number of days before the current date for which overpasses should be computed | integer | |
days_after |
a number of days after the current date for which overpasses should be computed | integer |
$ 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
]
]
]
}
}
]
}