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
):
Loading...
Perform search
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:
40
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 the 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 the set of search results is now complete.
jq '.features | length' next_search_results.json
To proceed, go to Download quicklooks.