API Catalog Search

Introduction

The catalog is used to search for Pléiades and SPOT images that are available in the long-term archive and online archive. For more information, please refer to Catalog Search.

Check for available images

The endpoint for performing a catalog search is defined under the variable search_url:

search_url=https://api.up42.com/catalog/stac/search

Build request body

The request body must contain one of the following parameters:

AOI: the area coordinates using a geometric filter (intersects, contains, bounding box)

"bbox":[
   24.613498,
   45.601352,
   24.619497,
   45.605178
   ]

limit: the number of images returned by the search query

"limit": 100

cloudCoverage: the amount of clouds covering the full scene (%)

"cloudCoverage": {
     "lt": 20
 }

processingLevel: image collection archive type (Album for long-term archive, Sensor for online archive)

"processingLevel": {
     "IN": ["ALBUM"]
 }

dataBlock: UP42 data block associated with the dataset

"dataBlock": {
     "in": ["oneatlas-pleiades-aoiclipped"]
 }

datetime: search interval

"datetime": "2019-01-01T00:00:00Z/2019-01-15T23:59:59Z"

collections: satellite sensor

"collections": ["SPOT"]

Request body sample (saved in a separate file search_params.json):

{
  "datetime": "2019-01-01T00:00:00Z/2020-09-15T23:59:59Z",
  "intersects": {
    "type": "Polygon",
    "coordinates": [
        [
          [
            24.613639,
            45.605178
          ],
          [
            24.619497,
            45.605163
          ],
          [
            24.61921,
            45.601352
          ],
          [
            24.613498,
            45.601427
          ],
          [
            24.613639,
            45.605178
          ]
        ]
      ]
  },
    "limit": 2,
    "collections":["PHR"],
    "query": {
    "cloudCoverage": {
      "lt": 25
    },
    "processingLevel": {
      "IN": [
        "ALBUM",
        "SENSOR"
      ]
    }
  }
}

Perform search

Perform a catalog search using the request body and save the results in a file search_results.json:

curl -L -s -X POST $search_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" -d @search_params.json | jq '.' > search_results.json

The properties of the response body are explained in the table below.

UP42 Properties	Description
`id`	Image unique identifier in the OneAtlas catalog
`acquisitionDate`	Acquisition time of an image
`constellation`	Satellite constellation (`SPOT` or `PHR`)
`collection`	Satellite image collection (`SPOT` or `PHR`)
`providerName`	Data provider platform (`oneatlas`)
`blockNames`	UP42 data blocks that are associated to these datasets
`cloudCoverage`	Percentage of cloud cover per image full scene
`up42:usageType`	Dataset usage: purchase (`DATA`) or processing (`ANALYTICS`)
`providerProperties`	For provider-specific image properties, please refer to OneAtlas Data Results
`sceneId`	Image full scene ID
`resolution`	Spatial resolution (pixel size)
`deliveryTime`	The duration until an image is made available for delivery (`HOURS` or `MINUTES`)
`producer`	Data producer (Airbus)

Check the scene IDs retrieved from the search results:

jq -r '.features[] | .properties | .sceneId' search_results.json

Extract the number of images retrieved from the search results:

jq '.features | length' search_results.json

Extract all scene IDs and their corresponding image IDs and save them in a comma separated value file. The image IDs are universally unique identifiers that correspond to the segment of the scene ID that overlaps the AOI geometry.

jq -r '.features[].properties as $img | $img.sceneId + ","+ $img.id' search_results.json > all_images.csv

Extract the scene IDs from the long-term archive and their corresponding image IDs and save them in a comma separated value file:

jq -r '.features[].properties as $img | if $img.providerProperties.productionStatus=="ARCHIVED" then $img.sceneId + ","+ $img.id else empty end' search_results.json > archived_images.csv

Download the image quicklooks

Save the image IDs in a new file image_ids.json:

cat search_results.json | jq -r '.features[] | .properties | .id' | uniq > image_ids.json

Download the quicklook for each image ID saved in the previous file:

while read -r image_id; do curl -s -L https://api.up42.com/catalog/oneatlas/image/$image_id/quicklook -H "Authorization: Bearer $PTOKEN" -H 'Accept: image/webp; q=0.9, image/png; q=0.8, image/jpeg; q=0.7' -o quicklook_$image_id.jpg; done < image_ids.json

Estimate order

Before ordering a satellite image, you can view the price for each order that you will place. First define the workspace ID as a variable. For more information, please refer to Workspaces.

workspace_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The endpoint for estimating an order is defined under the variable estimate_order_url:

estimate_order_url=https://api.up42.com/workspaces/$workspace_id/orders/estimate

Build request body

The request body must contain the following parameters:

Name of data provider (in this case, OneAtlas)
Order parameters (image ID and AOI geometry). The image IDs can be extracted from the catalog search results.

Request body sample (saved in a separate file order_request.json):

{
  "dataProviderName": "oneatlas",
  "orderParams": {
    "id": "d2e467e8-abde-45bb-8fb9-312bf032bd48",
    "aoi": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            24.613639,
            45.605178
          ],
          [
            24.619497,
            45.605163
          ],
          [
            24.61921,
            45.601352
          ],
          [
            24.613498,
            45.601427
          ],
          [
            24.613639,
            45.605178
          ]
        ]
      ]
    }
  }
}

Perform estimation

Estimate the order associated with an image ID that was previously saved in image_ids.json and subsequently included in the request body order_request.json:

curl -L -s -X POST $estimate_order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" -d @order_request.json | jq '.'

Place order

The endpoint for placing an order is defined under the variable order_url:

order_url=https://api.up42.com/workspaces/$workspace_id/orders

Place the order for an image ID that was included in the request body order_request.json:

curl -L -s -X POST $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" -d @order_request.json | jq '.'

If the order is successfully placed, the response body provides a new order ID that will appear in the user storage.

Get orders

Get the information for all placed and fulfilled orders:

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq '.'

Get only the order IDs:

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq -r '.data.orders[].id'

Download data

In UP42 terminology, data can be downloaded as assets.

Get assets

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq -r '.data.orders[].assets[]'

Get assets associated to each order

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq -r '.data.orders[] | .id + " : " + .assets[]'

Get assets associated to each order and check the delivery status

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq -r '.data.orders[] | .id + " : " + .assets[] + " : " + .status'

Download assets

The endpoint for viewing an asset is defined under the variable asset_url:

asset_url=https://api.up42.com/workspaces/$workspace_id/assets

View information of a single asset:

asset=a5ab8110-ffdb-4549-bbba-ee628aaeb31c

curl -s -L GET https://api.up42.com/workspaces/$workspace_id/assets/$asset -H "Authorization: Bearer $PTOKEN" | jq '.'

Save all the assets into a new file

curl -L -s -X GET $order_url -H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" | jq -r '.data.orders[].assets[]' > asset_ids.json

View information of all assets:

while read -r asset_id; do curl -s -L https://api.up42.com/workspaces/$workspace_id/assets/$asset_id -H "Authorization: Bearer $PTOKEN"; done < asset_ids.json | jq '.'

Download a single asset:

curl -s -L GET https://api.up42.com/workspaces/$workspace_id/assets/$asset/downloadUrl -H "Authorization: Bearer $PTOKEN" | jq '.data'

Download all the assets:

while read -r asset_id; do curl -s -L https://api.up42.com/workspaces/$workspace_id/assets/$asset_id/downloadUrl -H "Authorization: Bearer $PTOKEN"; done < asset_ids.json | jq '.data'