Data search

Build request body

View search parameters

The request body should contain one of the following parameters described in the table below.

Parameter name	Parameter	Definition
Area of interest	`bbox`/`contains`/`intersects`	The geographic coordinates of the area and the geometric filter that directly relates to it (intersects, contains, bounding box)
Cloud cover	`cloudCoverage`	The amount of clouds covering the full scene (%).
Collections	`collections`	The dataset collections depending on sensor type (spaceborne platforms or aircraft sensors).
Data block	`dataBlock`	UP42 data block associated with the dataset.
Search interval	`datetime`	The image acquisition interval.
Delivery time	`deliveryTime`	The duration until an image gets delivered to storage (10 minutes or up to 24 hours)
Image unique identifier	`ids`	The image unique identifier that defines the image segment of the full scene that overlaps the AOI.
Number of images	`limit`	The number of images retrieved by the search query.
Processing level	`processingLevel`	The archive type of the dataset collection (Album defines the long-term archive, Sensor defines the online archive)
Spatial resolution	`resolution`	The pixel size of the dataset.
Scene identifier	`sceneIds`	The identifier of the full scene (full image footprint that is captured by the light beam of the sensor).
Usage type	`up42:usageType`	The image usage type (Data or Analytics).

Learn more

To view examples for each parameter, please refer to the API reference.

Select search parameters

Create a request body with the search interval, AOI coordinates and maximum number of images to be retrieved (search_request.json):

In the steps below, we search for geospatial datasets provided by the following hosts: OneAtlas and Near Space Labs. OneAtlas provides access to very high-resolution and high-resolution satellite images (Pléiades and SPOT 6/7). Near Space Labs provides access to very high-resolution images captured by the stratospheric balloons called Swifty.

OneAtlas

Select the host name where you want to get the data from:

host_name = oneatlas

Perform the search and save the results in a file OneAtlas_search_results.json:

curl -s -L -X POST -H "Authorization: Bearer $PTOKEN" \
-H 'Content-Type: application/json' \
https://api.up42.com/catalog/hosts/$host_name/stac/search \
-d @search_request.json | jq '.' > OneAtlas_search_results.json

Near Space Labs

Select the host name where you want to get the data from:

host_name=nearspacelabs

Perform the search and save the results in a file NearSpaceLabs_search_results.json:

curl -s -L -X POST -H "Authorization: Bearer $PTOKEN" \
-H 'Content-Type: application/json' \
https://api.up42.com/catalog/hosts/$host_name/stac/search \
-d @search_request.json | jq '.' > NearSpaceLabs_search_results.json

View search results

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

UP42 properties	Description
`id`	The image unique identifier that defines the image segment of the full scene that overlaps the AOI.
`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 with the selected 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 the provider website. Example: OneAtlas.
`sceneId`	Image full scene identifier.
`resolution`	Spatial resolution (pixel size).
`deliveryTime`	The duration until an image is delivered (HOURS or MINUTES).
`producer`	Data producer (Airbus).

Filter by scene identifiers

Check the scene IDs retrieved from the search results:

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

Example:

DS_PHR1B_202112221724381_FR1_PX_W098N30_0507_01787
DS_PHR1B_202112101717063_FR1_PX_W098N30_0506_01048

View the number of images

Extract the number of images retrieved from the search results (40 results displayed):

jq '.features | length' OneAtlas_search_results.json

Example:

Query by archive type

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' OneAtlas_search_results.json
> archived_images.csv

Extract image unique identifiers

Extract all scene IDs and their corresponding image IDs and save them in a comma separated value file:

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

Paginate search results

Get token

The limit of returned images was set to 40 and our search operation displayed 40 results, which means that there might be more results to be displayed. In order to view the entire list of results, you can move to the next page by using the continuation token. This token can be found in the response body of your search results:

"links": [{"rel": "self",
           "href": "https://api.up42.com/catalog/hosts/oneatlas/stac/search?next=GIYDAOBNGEYS2MBWKQYDAORQGA5D"
          },
          {"rel": "next",
           "href": "https://api.up42.com/catalog/hosts/oneatlas/stac/search?next=GIYDAOBNGEYS2MBWKQYDAORQGA5D"
         }]

Extract the token associated with the next query parameter:

curl -L -s -X POST https://api.up42.com/catalog/hosts/$host_name/stac/search \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $PTOKEN" -d @OneAtlas_search_results.json \
| jq -r '.links[] | select( .rel == "next") | .href ' |  cut -f 2 -d '='

The token will be displayed:

GIYDAOBNGEYS2MBWKQYDAORQGA5D

Get next page

Use the token and search for results on the next page. Save the results in a file next_search_results.json:

token=GIYDAOBNGEYS2MBWKQYDAORQGA5D

curl -L -s -X POST https://api.up42.com/catalog/hosts/$host_name/stac/search?next=$token \
-H 'Content-Type: application/json' -H "Authorization: Bearer $PTOKEN" \
-d @search_request.json | jq '.' > next_search_results.json

Extract the number of images retrieved from the search results (1 results displayed). Since the search results displayed on the next page are less than 40, this means that our set of search results is now complete.

jq '.features | length' next_search_results.json

To proceed, go to Download quicklooks.