Placing a tasking order and retrieve data
This integrated example lists the various requests and relevant responses needed to go from:
- Obtaining an Access Token
- Placing a tasking order for new imagery
- Checking the status of the order
- Checking the status of planned captures
- Downloading available data of an order
In this example we create a task_id: 32082
and download one of the resulting captures (sceneset_id: 45aab05b-7190-4369-abd4-b11b1f4a3165
).
1. Obtaining an Access Token
Start by exchanging API Credentials for an Access Token, which will then be used to authorize subsequent requests.
Request:
curl --location --request POST 'https://login.satellogic.com/oauth/token' \
--header 'content-type: application/json' \
--data-raw '{
"client_id": "<API_CREDENTIAL_ID>",
"client_secret": "<API_CREDENTIAL_SECRET>",
"audience": "https://api.satellogic.com/",
"grant_type": "client_credentials"
}'
Response:
{
"access_token": "<ACCESS_TOKEN>",
"scope": "api:tasking api:delivery",
"expires_in": 86400,
"token_type": "Bearer"
}
2. Placing a tasking order for new imagery
curl --location --request POST 'https://api.satellogic.com/tasking/tasks/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"task_name": "My first task",
"project_name": "My first task project",
"product": 90,
"target": {
"type": "Point",
"coordinates": [
72.905273,
19.023001
]
},
"start": "2020-12-23T00:00:00+03:00",
"end": "2021-01-12T00:00:00+03:00",
}'
Response example
{
"task_id": 23272,
"task_name": "My first task",
"project_name": "My first task project",
"product": 90,
"start": "2020-12-22T21:00:00Z",
"end": "2021-01-11T21:00:00Z",
"priority": 13,
"client": "My first client",
"target": {
"type": "Point",
"coordinates": [
72.905273,
19.023001,
0.0
]
},
"created_time": "2020-12-23T22:13:52.943224Z",
"status": "received"
}
Attention
When in doubt of which product IDs are available for the account being used, the /products/ endpoint can be consulted. See this usage example.
3. Checking the status of the order
curl --location --request GET 'https://api.satellogic.com/tasking/tasks/23272' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'
Response example
{
"task_id": 23272,
"task_name": "My first task",
"project_name": "My first task project",
"product": 90,
"start": "2020-12-22T21:00:00Z",
"end": "2021-01-11T21:00:00Z",
"priority": 13,
"client": "Demo client",
"target": {
"type": "Point",
"coordinates": [
72.905273,
19.023001,
0.0
]
},
"created_time": "2020-12-23T22:13:52.943224Z",
"status": "in_progress"
}
4. Checking the status of planned captures
curl --location --request GET 'https://api.satellogic.com/tasking/tasks/23272/captures/' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'
Response example
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"capture_id": "45aab05b-7190-4369-abd4-b11b1f4a3165",
"start": "2021-07-14T07:40:41.845086Z",
"satellite_name": "newsat15",
"status": "published"
},
{
"capture_id": "d2bd2374-a6b5-422a-b020-ad016e9426f5",
"start": "2021-07-15T07:26:58.976391Z",
"satellite_name": "newsat9",
"status": "published"
}
]
}
5. Downloading available data of an order
Once the capture has been processed, it will be available in the archive for download. Currently, this delivery is done using the Telluric API and will eventually be translated to the STAC API. Please check the Telluric API section for the API specifications.
Requesting the details for a given capture results in 4 attachments the first of which is name: delivery_zip
which includes all the data, including rasters, metadata and footprint files. This attachment can be downloaded via url
. This url includes a token which is generated upon request. This token is ephemeral and regenerated upon subsequent requests.
Attention
The sceneset_id
expected for this endpoint is the value of capture_id
from the previous step.
curl --location --request GET 'https://api.satellogic.com/telluric/scenes/?sceneset_id=45aab05b-7190-4369-abd4-b11b1f4a3165' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'
Response example
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"scene_id": "20210714_074044_SN15_L1",
"sceneset_id": "dbaab05b-7190-4369-abd4-b11b1f4a3165",
"timestamp": "2021-07-14T07:40:44.792141Z",
"footprint": {
"type": "Polygon",
"coordinates": [
...
]
},
"metadata": {
...
},
"supplier": "Satellogic",
"satellite_class": "NewSat",
"satellite_name": "newsat15",
"productname": "L1 TOA Reflectance",
"rasters": [
{
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/token/{token}/raster/20210714_074044_SN15_L3_MS.tif",
"bands": [
"red",
"green",
"blue"
],
"file_name": "20210714_074044_SN15_L3_MS.tif",
"source": "internal",
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/"
},
{
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/token/{token}/raster/20210714_074044_SN15_L1_MS.tif",
"bands": [
"blue",
"green",
"red",
"nir"
],
"file_name": "20210714_074044_SN15_L1_MS.tif",
"source": "internal",
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/"
}
],
"bands": {
...
},
"attachments": [
{
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/",
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/delivery_zip/download/?token=...",
# this is the download url which includes a token will expire. For new token, make a new request.
"file_name": "20210714_074044_SN15_L1_MS_36941.zip",
"name": "delivery_zip",
"metadata": {},
"edit_url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/delivery_zip/"
},
{
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/",
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/footprint/download/?token=...",
"file_name": "20210714_074044_SN15_L1_MS_footprint.kml",
"name": "footprint",
"metadata": {},
"edit_url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/footprint/"
},
{
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/",
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/thumbnail/download/?token=...",
"file_name": "20210714_074044_SN15_L3_MS_thumbnail.png",
"name": "thumbnail",
"metadata": {},
"edit_url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/thumbnail/"
},
{
"scene": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/",
"url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/preview/download/?token=...",
"file_name": "20210714_074044_SN15_L3_MS_preview.png",
"name": "preview",
"metadata": {},
"edit_url": "https://catalog.telluric.satellogic.com/v2/scenes/20210714_074044_SN15_L1/attachments/preview/"
}
],
"last_modified": "2021-07-15T15:15:10.724978Z"
}
]
}