Introduction
The UP42 API queries data sources based on the SpatioTemporal Asset Catalog (STAC) specification. STAC provides a common language to describe a range of geospatial information. The UP42 API does not strictly integrate the STAC specification and the implementation slightly differs from STAC filters, because we provide a REST API and not a WFS compliant interface.
Data block types
Depending on the data block, 2 types of output can be generated: AOI clipped and full scene.
Supported filters
UP42 provides access to numerous blocks that support various filters. Please note that the data block implementation determines if a block supports a certain filter or not.
limit
The number of images to be returned (default = 1). By default, the maximum number of images is 5. If you have a payment method associated with your account, you can set the maximum number of images to 20. For more information, please refer to Projects. If you want to set the maximum number of images to a value higher than 20, please contact the customer support.
bbox
Searches for datasets according to a specified AOI as a GeoJSON bounding box geometry that intersects the AOI.
intersects
Searches for datasets according to a specified AOI as a GeoJSON polygon geometry that intersects this AOI.
contains
Searches for datasets according to a specified AOI as a GeoJSON geometry that fully covers this AOI.
time
Searches for datasets according to a single date and time or range formatted according to RFC 3339 section 5.6. The date and time format is %Y-%m-%dT%H:%M:%S+00:00. To specify a range, use the format "2019-02-01T00:00:00+00:00/2019-03-01T00:00:00+00:00".
time_series
Searches for datasets according to an array of time ranges that contains individual time ranges. The limit parameter is used for each of the time ranges. If the time ranges overlap, some datasets will be retrieved two times.
For example, to select an image acquired each February from 2017 till 2019, use the following array of time ranges:
["2019-02-01T00:00:00+00:00/2019-03-01T00:00:00+00:00",
"2018-02-01T00:00:00+00:00/2018-03-01T00:00:00+00:00",
"2017-02-01T00:00:00+00:00/2017-03-01T00:00:00+00:00"]When using time_series, set time to null. Using both time query parameters in a job will result in an error.
ids
Array of unique identifiers (IDs) for a certain dataset acquired by a specific satellite sensor.
The naming convention of the ID will depend on the data provider.
IDs for full scene
The ID for full scenes is usually given as a string containing information about the acquisition.
A Pléiades image will have the following naming convention:
| Parameter | Description | Example |
|---|---|---|
DS_PHR | satellite sensor | DS_PHR |
<nn> | satellite number | 1A, 1B |
<YYYYMMDDHHMMSSS> | UTC strip source acquisition start time | 201006181052297 |
<RRR> | initial archiving center acronym | FR1 |
<PP> | acquisition spectral mode | PA, XS, PX |
<XxxxYyy> | closest square degree of the strip center with: X = {W,E}, West or East, xxx longitude degree (000 to 180) Y = {N,S}, North or South, yy latitude degree (00 to 90) | E001N43 |
<KKLL> | closest cell in the Pléiades Grid of the strip center with: KK = step number in longitude LL = step number in latitude | 0612 |
<TTTTT> | Number of source frames PA (or XS if spectral mode is XS) | 06488 |
Example: DS_PHR1A_201006181052297_FR1_PX_E001N43_0612_06488.
IDs for AOI clipped
The ID for AOI clipped can be a universally unique identifier for a derived product, e.g. with reflectance correction.
Example for a Pléiades Display (Streaming) block: e4dcc664-89c6-4df4-85b9-ecf1bc998bcb.
max_cloud_cover
Integer that defines the maximum percentage of cloud cover and it ranges from 0 to 100%.
This parameter is only applicable to optical imagery (e.g. Pléiades, SPOT, Sentinel-2).
Implemented filters
| Data block | limit | bbox | intersects | contains | time | time_series | ids | max_cloud_cover |
|---|---|---|---|---|---|---|---|---|
| Pleiades Display (Streaming) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Pleiades Display (Download) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Pleiades Reflectance (Download) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| SPOT Display (Streaming) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| SPOT Display (Download) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| SPOT Reflectance (Download) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Pleiades Primary | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Hexagon 15cm Aerial | ✔︎ | ✔︎ | ||||||
| Hexagon 30cm Aerial | ✔︎ | ✔︎ | ||||||
| Sentinel-1 L1 GRD (SAFE) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | |
| Sentinel-1 L1 SLC (SAFE) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | |
| Sentinel-2 L1C (SAFE) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Sentinel-2 L2A (SAFE) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| Sentinel-2 L1C (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| ESA Sentinel-2 L2A (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | |
| ESA Sentinel-2 L2A Analytic (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | |
| Sentinel-2 Level 2 (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||
| ESA Sentinel-5P L3 (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| Landsat-8 Level 1 (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||
| MODIS (GeoTIFF) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | |||
| Weather/Ocean data and forecasts | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| Weather Data for Agriculture | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| Weather Data for Energy and Power | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| Weather Data for Marine and Ocean | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| Meteomatics - Weather/Ocean Data and Forecasts Map | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||||
| NEXTMap One Elevation Data Suite | ✔︎ | ✔︎ | ||||||
| NEXTMap 5 Elevation Data Suite | ✔︎ | ✔︎ | ||||||
| NEXTMap 10 Elevation Data Suite | ✔︎ | ✔︎ | ||||||
| Landsat-8 Level 1 (GeoTIFF-Bundle) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ |
| OpenStreetMap Extraction | ✔︎ | ✔︎ | ✔︎ | |||||
| MODIS (GeoTIFF-Bundle) | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ||
| Airbus Basemap (Tile) | ✔︎ | ✔︎ | ||||||
| OneAtlas WorldDEM Full Resolution | ✔︎ | ✔︎ |