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:

export CONTRACT_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
export ACCESS_TOKEN="xxx…xxx"
curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" 
-H "Authorization: Bearer ${ACCESS_TOKEN}" 
-H "Content-Type: application/json" 
-d '{
  "datetime": "2022-01-01T00:00:00.000Z/2022-12-31T00:00:00.000Z",
  "intersects": {
    "coordinates": [
      [
        [
          -8.60621344099522,
          60.63920763634644
        ],
        [
          -14.213293594801314,
          45.95851155946286
        ],
        [
          10.621928171802324,
          52.72769978027327
        ],
        [
          -8.60621344099522,
          60.63920763634644
        ]
      ]
    ],
    "type": "Polygon"
  },
  "limit": 1
}'

The response is a GeoJSON FeatureCollection where each feature represents a single scene. Here is an example:

{
  "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": ["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": 5596
  }
}

We provide extensive metadata for every scene. To proceed with the ordering flow, two main parameters worth looking at:

price describes the price of each catalog scene in cents
id value is the unique scene 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 scene IDs you wish to access. With a single request, you can request up to 100 scenes.

curl -X POST "https://api.satellitevu.com/orders/v2/${CONTRACT_ID}/" 
-H "Authorization: Bearer ${ACCESS_TOKEN}" 
-H "Content-Type: application/json" 
-d '{
  "item_id": ["<id>", "<id>", "<id>"]
}'

The response of that request includes the order ID (id) and the information about every single scene you requested, including their unique identifiers (item_id). You need both of them to retrieve data.

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 scene. This requires an Order ID and a unique scene 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 scenes, 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/v2/${CONTRACT_ID}/${ORDER_ID}/download" 
-H "Authorization: Bearer ${ACCESS_TOKEN}"

The following is an example of downloading a specific scene:

export ORDER_ID="yyyyyyyy-yyyyyyyy-yyyyyyyy-yyyyyyyy"
export ITEM_ID="zzzzzzzz-zzzzzzzz-zzzzzzzz-zzzzzzzz"
curl -X GET "https://api.satellitevu.com/orders/v2/${CONTRACT_ID}/${ORDER_ID}/${ITEM_ID}/download" 
-H "Authorization: Bearer ${ACCESS_TOKEN}"