Catalog tutorial
Read this tutorial if you are looking for a step-by-step guide on how to search the data catalog, create a catalog order and get data delivered from start to finish using Python SDK.
In this guide, you will learn how to:
- Search for the catalog data
- Place an order
- Retrieve the data
Catalog search
The Python client can be used to send requests to our catalog search API which is itself built on top of the STAC specification. The example code below will search for catalog data collected over most of the UK and Ireland between 1st January and 1st October 2023:
from datetime import datetime
from os import getenv
# Set your contract ID in an environmental variable named CONTRACT_ID before running this
contract_id = getenv("CONTRACT_ID")
# Define the search parameters for the catalog_v1 search function
search_params = {
"date_from": datetime(2023, 1, 1, 0, 0, 0), # Start date of the search period
"date_to": datetime(2023, 10, 1, 0, 0, 0), # End date of the search period
# GeoJSON Geometry object definition of the area of interest
"intersects": {
"coordinates": [
[
[-8.60621344, 60.63920763],
[-14.213293594, 45.95851155],
[10.621928171, 52.72769978],
[-8.60621344, 60.63920763]
]
],
"type": "Polygon"
},
"limit": 1, # Limit the number of search results to 1
"contract_id": contract_id # The contract ID
}
# Perform the search using the specified parameters in catalog_v1
response = client.catalog_v1.search(**search_params)The response is a GeoJSON FeatureCollection in which each feature represents a single scene. Here is an example:
from pprint import pprint
pprint(response.json()["features"][0]){
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
[
[-2.7420802430281057, 53.30151312071542],
[-2.742071712549939, 53.302928869338615],
[-2.7446253310960036, 53.306269279842574],
[-2.752248426010808, 53.3141507152659],
[-2.770439299980308, 53.331176240096276],
[-2.772953110794155, 53.33284849923299],
[-2.795657406636968, 53.333015383939724],
[-2.7957456157510925, 53.31454772705072],
[-2.792984845563798, 53.30966645071987],
[-2.775312258620936, 53.29396666288351],
[-2.7719049854732445, 53.29285904282315],
[-2.7420802430281057, 53.30151312071542]
]
],
"type": "Polygon"
},
"properties": {
"created": "2023-05-11T10:50:27.899924+00:00",
"updated": "2023-05-11T10:50:27.899924+00:00",
"platform": "<Platform>",
"gsd": 3.5,
"datetime": "2022-11-13T21:26:17+00:00",
"eo:cloud_cover": 0,
"proj:shape": [1280, 1024],
"view:azimuth": 82.8,
"proj:epsg": 32630,
"proj:bbox": [513606.0, 5904858.0, 517190.0, 5909338.0],
"view:off_nadir": 3.8,
"proj:geometry": {
"type": "Polygon",
"coordinates": [
[
[517188.25, 5905843.25],
[517188.25, 5906000.75],
[517016.75, 5906371.75],
[516505.75, 5907246.75],
[515287.75, 5909136.75],
[515119.75, 5909322.25],
[513607.75, 5909336.25],
[513607.75, 5907281.75],
[513793.25, 5906739.25],
[514976.25, 5904996.25],
[515203.75, 5904873.75],
[517188.25, 5905843.25]
]
]
},
"view:sun_elevation": -44.551152114305864,
"proj:transform": [3.5, 0.0, 513606.0, 0.0, -3.5, 5909338.0, 0.0, 0.0, 1.0],
"created_at": "2023-05-11T10:50:23Z",
"view:sun_azimuth": 306.1462111881958,
"price": {
"value": 40000,
"currency": "EUR"
}
},
"id": "<id>",
"bbox": [-2.7958758076207966, 53.29265676209475, -2.7418645127077825, 53.33303115945561],
"stac_version": "1.0.0",
"assets": {
"udm": {
"href": "s3://...",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["udm", "metadata"]
},
"overview": {
"href": "s3://...",
"type": "image/png",
"roles": ["overview"]
},
"thumbnail": {
"href": "https://...",
"type": "image/png",
"roles": ["thumbnail"]
},
"visual": {
"href": "s3://...",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["visual", "data"],
"raster:bands": [
{
"scale": 1.0,
"nodata": 0.0,
"offset": 0.0,
"sampling": "area",
"data_type": "float32",
"statistics": {
"mean": 280.4705043101197,
"stddev": 0.8242943304357567,
"maximum": 282.7051086425781,
"minimum": 278.80511474609375,
"valid_percent": 59.89173889160156
}
}
]
}
},
"links": [
{
"href": "https://...",
"rel": "self",
"type": "application/geo+json"
},
{
"href": "https://...",
"rel": "parent",
"type": "application/json"
},
{
"href": "https://...",
"rel": "collection",
"type": "application/json"
},
{
"href": "https://api.satellitevu.com/catalog/v1/",
"rel": "root",
"type": "application/json"
}
],
"stac_extensions": [
"https://stac-extensions.github.io/projection/v1.0.0/schema.json",
"https://stac-extensions.github.io/raster/v1.1.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json",
"https://stac-extensions.github.io/eo/v1.0.0/schema.json"
],
"collection": "basic"
}
],
"links": [
{
"rel": "next",
"type": "application/geo+json",
"href": "https://api.satellitevu.com/catalog/v1/search",
"method": "POST",
"body": {
"token": "0LttsQ3G"
},
"merge": true
}
],
"context": {
"returned": 1,
"limit": 1,
"matched": 500
}
}We provide extensive metadata for every scene. To proceed with the ordering flow, two main parameters are worth looking at:
pricedescribes the price of each catalog scene in centsidvalue is the unique scene identifier that you will need in the order placement step
The FeatureCollection object has links list that includes the link to the next search results page. You need to use the token in your following request to retrieve results from the next page.
Placing a catalog order
To place an order using the Python SDK, you just need to provide a set of scene IDs you wish to get access to. With a single request, you can request up to 100 scenes.
# Obtaining the ID of the catalog scene from the response
item_id = response.json()["features"][0]["id"]
# Submitting the order with item_id and contract_id
response = client.orders_v2.submit(item_ids=[item_id], contract_id=contract_id)
order = response.json()Download data
To download the data, you can use the download_order function providing the ID of the order:
from pathlib import Path
client.orders_v2.download_order(order_id=order["id"], destdir=Path(), contract_id=contract_id)