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 RESTful API.
In this guide, you will learn how to:
- Search for catalog data
- Place an order
- Retrieve the data
Catalog search
Our catalog search API is built on top of the STAC specification. You will find a few endpoints in the endpoint collection. The most used one is the POST Search endpoint. Here is an example search request for data collected in a given time frame and area of interest:
When searching the catalog, use the collections field in the body to search specific collections within the Catalog.
See Catalog Structure for more information on how the STAC catalog is structured.
export CONTRACT_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
export ACCESS_TOKEN="xxx…xxx"
curl -X POST "https://api.satellitevu.com/catalog/v3/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"datetime": "2023-06-01T00:00:00.000Z/2023-12-31T00:00:00.000Z",
"collections": ["acquisition"],
"intersects": {
"coordinates": [
[
[
12.512915276,
41.919453536
],
[
12.456270738,
41.913126082
],
[
12.463075077,
41.8793154
],
[
12.519559077,
41.885568975
],
[
12.512915276,
41.919453536
]
]
],
"type": "Polygon"
},
"limit": 1
}'
The response is a GeoJSON FeatureCollection where each feature represents a single item. Here is an example:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "<id>",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
12.512915276,
41.919453536
],
[
12.456270738,
41.913126082
],
[
12.463075077,
41.8793154
],
[
12.519559077,
41.885568975
],
[
12.512915276,
41.919453536
]
]
]
},
"bbox": [
12.455998363885145,
41.879176436466004,
12.519910363053187,
41.91965582447327
],
"properties": {
"created": "2026-02-24T15:33:58Z",
"datetime": "2023-06-23T00:00:45Z",
"eo:cloud_cover": 0,
"gsd": 3.5,
"platform": "<platform>",
"price:currency": "GBP",
"price:value": 50000,
"satvu:filter": "night",
"satvu:geometric_calibration": true,
"satvu:image_withheld": false,
"satvu:publicly_available": "\"2026-02-24T15:35:50.56601+00:00\"",
"updated": "2026-03-16T14:05:32.748953Z",
"view:azimuth": 73.92275521160794,
"view:off_nadir": 0.31961221532931816,
"view:sun_azimuth": 12.326662887849425,
"view:sun_elevation": -23.725292025762727
},
"collection": "acquisition",
"stac_version": "1.1.0",
"stac_extensions": [
"https://stac-extensions.github.io/view/v1.0.0/schema.json",
"https://stac-extensions.github.io/eo/v1.1.0/schema.json"
],
"links": [
{
"method": "",
"href": "https://...",
"rel": "satvu:surface-brightness-temperature",
"title": "Child product item derived from acquisition",
"type": "application/geo+json"
},
{
"method": "",
"href": "https://...",
"rel": "satvu:primary",
"title": "Child product item derived from acquisition",
"type": "application/geo+json"
},
{
"method": "GET",
"href": "https://...",
"rel": "root",
"type": "application/json"
},
{
"method": "POST",
"href": "https://...",
"rel": "self",
"type": "application/geo+json",
"body": {
"collections": [
"acquisition"
],
"datetime": "2023-06-01T00:00:00.000Z/2023-12-31T00:00:00.000Z",
"intersects": {
"coordinates": [
[
[
12.512915276,
41.919453536
],
[
12.456270738,
41.913126082
],
[
12.463075077,
41.8793154
],
[
12.519559077,
41.885568975
],
[
12.512915276,
41.919453536
]
]
],
"type": "Polygon"
},
"limit": 1
}
},
{
"method": "GET",
"href": "https://...",
"rel": "parent",
"type": "application/json"
},
{
"method": "GET",
"href": "https://...",
"rel": "collection",
"type": "application/json"
}
],
"assets": {
"full_resolution_thumbnail": {
"href": "s3://...",
"roles": [
"thumbnail"
],
"type": "image/png"
},
"thumbnail": {
"href": "s3://...",
"roles": [
"thumbnail"
],
"type": "image/png"
}
}
}
],
"links": [
{
"method": "POST",
"href": "https://...",
"rel": "next",
"type": "application/geo+json",
"body": {
"collections": [
"acquisition"
],
"datetime": "2023-06-01T00:00:00.000Z/2023-12-31T00:00:00.000Z",
"intersects": {
"coordinates": [
[
[
12.512915276,
41.919453536
],
[
12.456270738,
41.913126082
],
[
12.463075077,
41.8793154
],
[
12.519559077,
41.885568975
],
[
12.512915276,
41.919453536
]
]
],
"type": "Polygon"
},
"limit": 1,
"token": "xxxx"
}
}
],
"numberMatched": 2,
"numberReturned": 1
}
We provide extensive metadata for every item. To proceed with the ordering flow, two main parameters worth looking at:
pricedescribes the price of each catalog item in centsidvalue is the unique item identifier that you will need in the order placement step
Placing a catalog order
To place an order using API, you just need to provide a set of IDs of Acquisitions you wish to access. With a single
request, you can request up to 100 acquisitions.
When ordering, make sure to provide the ID of the item in the Acquisition collection associated to each image, rather
than Product specific item IDs (eg SBT or Primary).
See Catalog Structure for more information on how the STAC catalog is structured.
You must also provide the value field of a valid licence type to assign to the order. For more information on finding
the list of available licences, please see Contract Information.
An optional name for the order can also be provided using the name field.
curl -X POST "https://api.satellitevu.com/orders/v3/${CONTRACT_ID}/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"item_id": ["<id>", "<id>", "<id>"],
"licence_level" : "Evaluation Licence",
"name" : "<Order Name>"
}'
The response of that request includes the order ID (id) and the information about every single item you requested,
including their unique identifiers (item_id). You need both of them to retrieve data.
If you wish to view the total price of the order before placing the order, including the impact of any price uplifts,
you can do this using the POST /price endpoint
curl -X POST "https://api.satellitevu.com/orders/v3/${CONTRACT_ID}/price" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"item_id": ["<id>", "<id>", "<id>"],
"licence_level" : "Evaluation Licence"
}'
Please note that you don’t need to wait for data to be prepared - once the order is placed, you can access the data immediately.
Download data
We provide two endpoints for data download:
- Download the entire order as a single file. This requires only an Order ID.
- Download a specific item. This requires an Order ID and a unique item identifier (
item_id).
When run, the endpoints’ response is the link to the file. Follow the link and save data as a .zip archive. When the
entire order has many items, the request might require some extra time to process. This will be identified via the 202
response with the Retry-After HTTP header that indicates how long the user agent should wait before making a follow-up
request.
The following is an example of the entire order download:
export ORDER_ID="yyyyyyyy-yyyyyyyy-yyyyyyyy-yyyyyyyy"
curl -X GET "https://api.satellitevu.com/orders/v3/${CONTRACT_ID}/${ORDER_ID}/download" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
The following is an example of downloading a specific acquisition:
export ORDER_ID="yyyyyyyy-yyyyyyyy-yyyyyyyy-yyyyyyyy"
export ITEM_ID="zzzzzzzz-zzzzzzzz-zzzzzzzz-zzzzzzzz"
curl -X GET "https://api.satellitevu.com/orders/v3/${CONTRACT_ID}/${ORDER_ID}/${ITEM_ID}/download" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"