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}×tamp_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