/

Data search (API)

Search for geospatial datasets and check for available data captured over your area of interest.


Build request body

View search parameters

  1. The request body should contain one of the following parameters described in the table below.
Parameter nameParameterDefinition
Area of interestbbox/contains/intersectsThe geographic coordinates of the area and the geometric filter that directly relates to it (intersects, contains, bounding box)
Cloud covercloudCoverageThe amount of clouds covering the full scene (%).
CollectionscollectionsThe dataset collections depending on sensor type (spaceborne platforms or aircraft sensors).
Data blockdataBlockUP42 data block associated with the dataset.
Search intervaldatetimeThe image acquisition interval.
Delivery timedeliveryTimeThe duration until an image gets delivered to storage (10 minutes or up to 24 hours)
Image unique identifieridsThe image unique identifier that defines the image segment of the full scene that overlaps the AOI.
Number of imageslimitThe number of images retrieved by the search query.
Processing levelprocessingLevelThe archive type of the dataset collection (Album defines the long-term archive, Sensor defines the online archive)
Spatial resolutionresolutionThe pixel size of the dataset.
Scene identifiersceneIdsThe identifier of the full scene (full image footprint that is captured by the light beam of the sensor).
Usage typeup42:usageTypeThe image usage type (Data or Analytics).
Learn more

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

Select search parameters

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

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

  1. Select the host name where you want to get the data from:
host_name = oneatlas
  1. 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

  1. Select the host name where you want to get the data from:
host_name=nearspacelabs
  1. 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

  1. The properties of the response body are explained in the table below:
UP42 propertiesDescription
idThe image unique identifier that defines the image segment of the full scene that overlaps the AOI.
acquisitionDateAcquisition time of an image.
constellationSatellite constellation (SPOT or PHR).
collectionSatellite image collection (SPOT or PHR).
providerNameData provider platform (OneAtlas).
blockNamesUP42 data blocks that are associated with the selected datasets.
cloudCoveragePercentage of cloud cover per image full scene.
up42:usageTypeDataset usage: purchase (DATA) or processing (ANALYTICS).
providerPropertiesFor provider-specific image properties, please refer to the provider website. Example: OneAtlas.
sceneIdImage full scene identifier.
resolutionSpatial resolution (pixel size).
deliveryTimeThe duration until an image is delivered (HOURS or MINUTES).
producerData producer (Airbus).

Filter by scene identifiers

  1. 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

  1. Extract the number of images retrieved from the search results (40 results displayed):
jq '.features | length' OneAtlas_search_results.json

Example:

40

Query by archive type

  1. 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

  1. 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

  1. 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"
         }]
  1. 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

  1. 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
  1. 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, please go to Download quicklooks (API).