Python Examples

A pre-requisite for exchanging requests with the Delivery API endpoints is to have a valid authentication token and contract_id, see Authentication API. In the examples below, the headers in the requests have placeholders for token and contract_id.

For further reference on usage of task management steps in this example, refer to the Tasking API / Python examples.

import requests
import json


# 0. Complete the following section with your contract_id and access token
#contract_id = ""
#ACCESS_TOKEN = ""


# 1. Get the published captures for a task

ALEPH_API_URL = "https://api.satellogic.com"
tasks_uri = "/tasking/tasks/"
captures_uri = "/captures/"
task_id = 268095

response = requests.get(
    f"{ALEPH_API_URL}{tasks_uri}{task_id}{captures_uri}", 
    headers={
        'AuthorizationToken': f'Bearer {ACCESS_TOKEN}',
        'X-Satellogic-Contract-Id': contract_id,
    },
)

# Raise an error if the request failed
response.raise_for_status()

# Convert response so JSON
captures = response.json()

# Keep only captures that are in status published
published_capture_ids = [
    capture["capture_id"] 
    for capture in captures["results"] 
    if capture["status"] == "published"
]
print(published_capture_ids)

Sample output:

['a0ab38b2-8cca-4f27-8c18-4c79c6f91cbe',
 '6b4901f0-530b-4527-9e31-8624d8d7864b', 
 '23fa3ed3-08e8-4dfe-a9a3-c5da817599be', 
 '75492c98-9d9e-412a-bdd3-208bc2d7a5f3']

# 2. Obtain the scene IDs for the first published capture
# Note: sceneset_id is the same as capture_id in this context
# Note: scenes are the deliverables for a capture

sceneset_id = published_capture_ids[0]

scenes_delivery_uri = "/telluric/scenes/"

response = requests.get(
    f"{ALEPH_API_URL}{scenes_delivery_uri}?sceneset_id={sceneset_id}", 
    headers={
        'AuthorizationToken': f'Bearer {ACCESS_TOKEN}',
        'X-Satellogic-Contract-Id': contract_id,
    },
)

# Raise an error if the request failed
response.raise_for_status()

# Convert response to JSON
scenes = response.json()

# Extract all scene IDs from the scenes response
scene_ids = [scene["scene_id"] for scene in scenes["results"]]

# Print the list of scene IDs
print(f"Found {len(scene_ids)} scenes (deliverables), their IDs are:")
for i, scene_id in enumerate(scene_ids, 1):
    print(f"{i}. {scene_id}")

Sample output:

Found 2 scenes (deliverables), their IDs are:
1. 20241206_081221_SN49_L1C_MS_268095
2. 20241206_081220_SN49_L1D_MS_268095

# 3. Obtain a download link for the first scene (deliverable)
scene_id = scene_ids[0]

download_link_uri = "/attachments/delivery_zip/download/?redirect=false"

response = requests.get(
    f"{ALEPH_API_URL}{scenes_delivery_uri}{scene_id}{download_link_uri}", 
    headers={
        'AuthorizationToken': f'Bearer {ACCESS_TOKEN}',
        'X-Satellogic-Contract-Id': contract_id,
    },
)
# Raise an error if the request failed
response.raise_for_status()

# Convert response to JSON
download_link = response.json()
print("Download link for the first scene (deliverable):")
print(json.dumps(download_link, indent=4, sort_keys=True))

Sample output:

Download link for the first scene (deliverable):
{
    "url": "https://satellogic-production-eo-backend-package.s3.amazonaws.com/l1c-benchmark/a0ab38b2-8cca-4f27-8c18-4c79c6f91cbe/..."
}

# 4. Filter scenes by task_id (using metadata__task_id__icontains)
# Replace 268095 with your desired task_id

task_id_filter = 268095
scenes_delivery_uri = "/telluric/scenes/"

response = requests.get(
    f"{ALEPH_API_URL}{scenes_delivery_uri}?metadata__task_id__icontains={task_id_filter}",
    headers={
        'AuthorizationToken': f'Bearer {ACCESS_TOKEN}',
        'X-Satellogic-Contract-Id': contract_id,
    },
)
response.raise_for_status()
scenes_by_task = response.json()
print(f"Scenes for task_id {task_id_filter}:")
for scene in scenes_by_task["results"]:
    print(scene["scene_id"])

Sample output:

Scenes for task_id 268095:
20250116_065717_SN33_L1C_MS_268095
20250107_115234_SN31_L1D_MS_268095
20250107_115231_SN31_L1C_MS_268095
20241230_080514_SN48_L1D_MS_268095
20241230_080512_SN48_L1C_MS_268095
20241229_070134_SN34_L1C_MS_268095
20241226_070242_SN33_L1C_MS_268095
20241218_111527_SN28_L1C_MS_268095
20241218_111527_SN28_L1D_MS_268095
20241216_080131_SN49_L1C_MS_268095
20241206_081221_SN49_L1C_MS_268095
20241206_081220_SN49_L1D_MS_268095

# 5. Filter scenes by timestamp_after and timestamp_before
# Example: Get scenes between 2025-02-01 and 2024-06-30

timestamp_after = "2025-02-01T00:00:00Z"
timestamp_before = "2025-06-30T23:59:59Z"

response = requests.get(
    f"{ALEPH_API_URL}{scenes_delivery_uri}?timestamp_after={timestamp_after}&timestamp_before={timestamp_before}",
    headers={
        'AuthorizationToken': f'Bearer {ACCESS_TOKEN}',
        'X-Satellogic-Contract-Id': contract_id,
    },
)
response.raise_for_status()
scenes_by_time = response.json()
print(f"Scenes between {timestamp_after} and {timestamp_before}:")
for scene in scenes_by_time["results"]:
    print(scene["scene_id"])

Sample output:

Scenes between 2025-02-01T00:00:00Z and 2025-06-30T23:59:59Z:
20250318_080730_SN49_L1C_MS_289168
20250317_112101_SN28_L1C_MS_289168
20250317_100916_SN36_L1C_MS_289708
20250317_100915_SN36_L1D_SR_MS_289708
20250316_102734_SN50_L1C_MS_289165
20250316_102635_SN50_L1C_MS_289708
20250315_103253_SN49_L1C_MS_289708