Skip to content

Placing a tasking order and retrieve data

This integrated example lists the various requests and relevant responses needed to go from:

  1. Obtaining an Access Tokens
  2. List available contracts
  3. Placing a tasking order for new imagery for a specific contract
  4. Checking the status of the order
  5. Checking the status of planned captures
  6. 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"
        }
    ]
}

Last update: 2024-11-01