Placing a tasking order and retrieve data
This integrated example lists the various requests and relevant responses needed to go from:
- Obtaining an Access Tokens
- List available contracts
- Placing a tasking order for new imagery for a specific contract
- Checking the status of the order
- Checking the status of planned captures
- Downloading available data of an order
Attention
If you are using Legacy API Credentials the step 2 is not required as contract selection is not available (see contracts selection section)
Attention
If you are using Legacy API Credentials you have to request your access token to https://login.satellogic.com/oauth/token (see Getting Started section)
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 Tokens
Tasking API Access Token
curl --location --request POST 'https://auth.platform.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": "<TASKING_API_ACCESS_TOKEN>",
"scope": "api:tasking api:delivery",
"expires_in": 86400,
"token_type": "Bearer"
}
Accounts Service API Access Token
curl --location --request POST 'https://auth.platform.satellogic.com/oauth/token' \
--header 'content-type: application/json' \
--data-raw '{
"client_id": "<API_CREDENTIAL_ID>",
"client_secret": "<API_CREDENTIAL_SECRET>",
"audience": "api",
"grant_type": "client_credentials"
}'
Response:
{
"access_token": "<ACCOUNTS_SERVICE_ACCESS_TOKEN>",
"scope": "accounts:principals:profile accounts:contracts:read",
"expires_in": 86400,
"token_type": "Bearer"
}
2. List available contracts
Attention
Notice the authentication header for the Accounts Service API is Authorization
and authorizationToken
for Tasking and Archive APIs
curl --location --request GET 'https://api.platform.satellogic.com/v2/my/contracts' \
--header 'Authorization: Bearer <ACCOUNTS_SERVICE_ACCESS_TOKEN>' \
Response example
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"contract_id": "cont.e8c1169a-e11a-48ac-ad4c-a69e76fd9b14",
"name": "First contract",
"account": "acct.64762159-1df5-4599-9916-79f9f78d8fb8",
"archive_configuration": {
"restrictions": [
"archive-restriction-1",
"archive-restriction-2"
],
"collections": [
"collection-1",
"collection-2"
]
},
"tasking_configuration": {
"has_credentials": true
}
"created_at": "2024-10-25T10:27:56.152557",
"updated_at": "2024-10-25T10:28:50.295054",
"status": "ACTIVE"
}, {
"contract_id": "cont.022dc3f5-1ccd-48bc-98cd-6e0d668ed50e",
"name": "Second contract",
"account": "acct.64762159-1df5-4599-9916-79f9f78d8fb8",
"archive_configuration": null,
"tasking_configuration": {
"has_credentials": true
}
"created_at": "2024-10-25T10:27:56.152557",
"updated_at": "2024-10-25T10:28:50.295054",
"status": "ACTIVE"
}
]
}
3. Placing a tasking order for new imagery
curl --location --request POST 'https://api.satellogic.com/tasking/tasks/' \
--header 'authorizationToken: Bearer <TASKING_API_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Satellogic-Contract-Id: cont.022dc3f5-1ccd-48bc-98cd-6e0d668ed50e' \
--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.
4. Checking the status of the order
curl --location --request GET 'https://api.satellogic.com/tasking/tasks/23272' \
--header 'authorizationToken: Bearer <TASKING_API_ACCESS_TOKEN>' \
--header 'X-Satellogic-Contract-Id: cont.022dc3f5-1ccd-48bc-98cd-6e0d668ed50e'
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"
}
5. Checking the status of planned captures
curl --location --request GET 'https://api.satellogic.com/tasking/tasks/23272/captures/' \
--header 'authorizationToken: Bearer <TASKING_API_ACCESS_TOKEN>' \
--header 'X-Satellogic-Contract-Id: cont.022dc3f5-1ccd-48bc-98cd-6e0d668ed50e'
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"
}
]
}
6. 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 <TASKING_API_ACCESS_TOKEN>' \
--header 'X-Satellogic-Contract-Id: cont.022dc3f5-1ccd-48bc-98cd-6e0d668ed50e'
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"
}
]
}