JSON Parameters

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.

Supported JSON parameters

UP42 provides access to numerous blocks that support a wide variety of parameters defined in JSON syntax.

acquisition_mode

String parameter that specifies a certain acquisition mode. For Sentinel-1, please refer to Acquisition Modes. For TerraSAR-X, please refer to the DLR Technical Guide.

Example

"IW"
"ST"
"SM"

aoi_bbox

Geometric filter that processes all datasets intersecting a GeoJSON bounding box.

Example

[
 18.454101,
 49.678334,
 18.749333,
 49.80803
]

aoi_geojson

Geometric filter that processes all datasets intersecting a GeoJSON polygon.

Example

{
     "type": "Polygon",
     "coordinates": [
       [
         [
           16.888593,
           47.933821
         ],
         [
           16.939385,
           47.933821
         ],
         [
           16.940758,
           47.89148
         ],
         [
           16.881729,
           47.885034
         ],
         [
           16.888593,
           47.933821
         ]
       ]
     ]
}

asset_ids

An array of asset identifiers specifying items from your UP42 Storage. For more information, please refer to Download and Streaming Data.

Example

["1b0d090f-315b-4ee5-88a1-50dcf6078297"]

augmentation_factor

Factor used to create additional tiles by applying a pixel offset (defaults to 1).

Example

1

bbox

Geometric filter that searches for all datasets intersecting a GeoJSON bounding box.

Example

[
 16.881729,
 47.885034,
 16.940758,
 47.933821
]

blue

The placeholder band to be used for calculating values in the blue channel. Please note that the band names depend on the satellite sensor (e.g. Landsat-8, Sentinel-2, Pléiades etc.)

Example

"R"
"B01"

bucket_name

The name of the Google Cloud Storage or Amazon Web Services storage bucket.

Example

"sample_bucket_name"

calibration_band

SAR calibration is used to generate images in which the pixel values can be directly related to the radar backscatter of the scene. Converts a dimensionless Digital Number (DN) to one of the following:

• Gamma = measurement of emitted and returned energy, useful for calibrating the antenna and determining its patterns.
• Beta nought = radar brightness coefficient, computed as the ratio between the power transmitted and received by the antenna. The coefficient is measured per unit area in slant range and is dimensionless.
• Sigma nought = scattering coefficient that measures the strength of radar signals reflected by a distributed scatterer, usually expressed in dB. It is a normalised dimensionless number, comparing the strength observed to that expected from a unit area on the ground, in ground range. This coefficient enables the comparison of multiple radar images (e.g. time series analysis).

Example

["beta"]
["gamma"]
["sigma"]

clip_to_aoi

Specifies if the dataset is clipped to the geometric filter. If set to false, the full scene is retrieved. If this parameter is displayed in a processing block, setting it to true will clip and process the dataset for the AOI specified in the previous data block.

Example

true
false

cloud_provider

The cloud storage provider of the bucket (Google Cloud Storage, Amazon Web Services).

Example

"gcs"
"aws"

colormap

The colormap used for rendering. Examples: RdYlGn, viridis, PRGn, jet, binary, qz_ndvi.

Example

"RdYlGn"
"Binary"
"qz_ndvi"

colormap_style

A color scheme to be used when visualizing the data.

Example

"JET"

contains

Geometric filter that searches for all datasets fully covering a GeoJSON polygon.

Example

{
     "type": "Polygon",
     "coordinates": [
       [
         [
           16.888593,
           47.933821
         ],
         [
           16.939385,
           47.933821
         ],
         [
           16.940758,
           47.89148
         ],
         [
           16.881729,
           47.885034
         ],
         [
           16.888593,
           47.933821
         ]
       ]
     ]
   }

copy_original_bands

If set to true, the original 10m resolution band will also be included in the output image.

Example

true
false

data_layers

String parameter that specifies the RealSAT dataset. This layer provides monthly surface area variations for 540 000 water bodies across the globe between 1984-2015.

Example

["ReaLSAT_waterbody_monthly"]

discard_empty_tiles

If set to true, it discards tiles that only consist of pixels with NoData values (as defined by an alpha band or a pre-defined NoData value).

Example

true
false

edge_sharpen_factor

Parameter of the SFIM pan-sharpening method that controls the blurred edges of the pan-sharpened image.

Example

1.7

eeid

exactEarth proprietary identifier provided by the exactEarth services to vessels based on their underlying characteristics.

Example

[
"0945377234823382332", 
"82137382388238372"
]

end_azimuth_degrees

The last value of the azimuth angle.

Example

360

fail_on_missing

A boolean flag that determines whether to fail or continue in case images are not available for some dates.

Example

true
false

filenames

An array of filenames, including file extension. This parameter overrides all other filters (e.g., intersects, limit and/or time).

Example

[“powerlines_USA.geojson”]
[“multispectral_image_USA.tif”]

filter_method

Method used for the sharpening process (Unsharp Masking Algorithm), based on a kernel or convolution matrix.

Example

"kernel"

geojson_url

A URL pointing to a GeoJSON geometry file that is placed on a web server. Must be accessible via simple HTTP call.

Example

"https://gist.githubusercontent.com/up42-epicycles/f6b72e3b98b2ca890e3e79e246e8e731/raw/2e3173c82226285ae3ab9349e4486b1dadb8d634/first_workflow_aoi.geojson"

green

The placeholder band to be used for calculating values in the green channel. Please note that the band names depend on the satellite sensor (e.g. Landsat-8, Sentinel-2, Pléiades etc.)

Example

"G"
"B02"

ids

Array of unique identifiers (IDs) specifying a certain image acquired by a specific satellite sensor. The file extension is omitted. This parameter overrides other filters (e.g. time, max_cloud_cover). The naming convention of the ID will depend on the data provider.

Pléiades example

["DS_PHR1A_201006181052297_FR1_PX_E001N43_0612_06488"]

Sentinel-1 example

["S1A_IW_SLC__1SDV_20210407T052740_20210407T052807_037340_04665D_0CA9"]

imagery_layer

String parameter that specifies the layer that is provided by Sentinel-3 or Sentinel-5P. This parameter must be one of the layer names described in the article Sentinel-3 (NetCDF) or Sentinel-5P (NetCDF).

Example

"SL_1_RBT___"
"L2__CH4___"

imagery_layers

MODIS - An array of layer identifiers available from Global Imagery Browse Services.

Getmapping - An array of layer identifiers (not adjustable).

MODIS example

["MODIS_Terra_CorrectedReflectance_Bands367"]

Getmapping example

["BestAvailable_UK_125mm"]
["composite_best_UK_250mm"]

include_ancillary_bands

Includes ancillary bands such as: solar_azimuth_angle, solar_zenith_angle, sensor_azimuth_angle, sensor_zenith_angle, sensor_altitude etc.

Example

true
false

include_pan

The panchromatic band is included in the pan-sharpened image.

Example

true
false

intersects

Geometric filter that searches for all datasets intersecting a GeoJSON polygon.

Example

{
     "type": "Polygon",
     "coordinates": [
       [
         [
           16.888593,
           47.933821
         ],
         [
           16.939385,
           47.933821
         ],
         [
           16.940758,
           47.89148
         ],
         [
           16.881729,
           47.885034
         ],
         [
           16.888593,
           47.933821
         ]
       ]
     ]
   }

L

Soil adjustment factor that ranges from -0.9 to 1.6.

Example

0.5

layer

String parameter that specifies the layer that is provided by Sentinel-5P. This parameter must be one of the layer names described in the article ESA Sentinel-5P L3 (GeoTIFF).

Example

"L3__SO2___"

limit

The number of images to be returned. If you have no payment method associated with your account, the maximum number of images is 20. If you have a payment method associated with your account, you can set the maximum number of images to 5000. For more information, please refer to Projects.

When specifying this job parameter, make sure to set the correct values for the following job parameters: ids and time_series (see table below).

Example

1
20
500
5000

linear_to_db

Converts the backscatter coefficient σ° to decibels (dB) with the formula 10*log₁₀σ°.

Example

true
false

mask

Applies a mask for either the land or sea surface. Only one mask type can be used.

Example

["land"]
["sea"]

match_extents

If set to true, the tile extents of all input layers will perfectly match.

Example

true
false

max_cloud_cover

Integer that defines the maximum percentage of cloud cover. Values range from 0% (no cloud cover) to 100% (full cloud cover). This parameter is only applicable for optical images (e.g. Pléiades, SPOT, Sentinel-2).

Example

0
20
100

max_distance_meters

The maximum distance for the viewshed calculation (meters).

Example

500

maxsize

The maximum size of detected ships (meters).

Example

500

method

Pan-sharpening method. Users can select one of the following methods: Smoothing Filter-based Intensity Modulation, Brovey and Esri.

Example

"SFIM"
"Brovey"
"Esri"

Statistical method to be applied on a stack of raster inputs and perform a time series statistics.

Example

"mean"
"min"
"max"
"std"
"median"
"sum"

min_quality_threshold

Minimum pixel quality, ranges between 0 and 100%.

Example

10
50
100

minsize

The minimum size of detected ships (meters).

Example

30

minutes

Amount of minutes between the satellite image acquisition date and the AIS data (the minutes are calculated before and after the image acquisition date and time). Default: 15 Maximum: 720

Example

15
60

mission_code

String parameter that specifies the mission code for each satellite: Sentinel-1A and Sentinel-1B. Setting this parameter to `null searches for both missions.

Example

"S1A"
"S1B"

mmsi

IDs of Maritime Mobile Service Identity

Example

[
"832732821", "948212991"
]

model

The model used to perform an image super-resolution: SRCNN (default), AESR or RedNet. Choosing the deeper model architectures (AESR and RedNet) will significantly impact the time required to super-resolve the image.

Example

SRCNN
AESR
RedNet

ms

Parameter that specifies the conversion of multispectral bands.

Example

true
false

n_clusters

Parameter that specifies the number of clusters used in the k-means classification.

Example

6

n_iterations

Parameter that specifies the number of iterations used in the k-means classification.

Example

10

n_sieve_pixels

Minimum number of pixels in each group generated by an algorithm (e.g. k-means classification, NDVI threshold, vectorization).

Example

64

nclasses

Parameter that specifies the number of classes used in the land cover classification.

Example

5

nodata

NoData pixel value for each raster band. If not set, it defaults to the NoData value of the input image.

Example

null
0

object_types

Example

[
 "Scenes",
 "Ships_Rigs",
 "Slick_Points",
 "Slick_Outlines"
]

observer_height_meters

The observer elevation from which the viewshed is computed (meters).

Example

100

observer_latitude

The observer latitude from which the viewshed is computed.

Example

37.7506068649

observer_longitude

The observer longitude from which the viewshed is computed.

Example

14.9924352729

osm_tags

An array of tags for filtering data. A single tag consists of a key and value. For a complete list of OSM tags, please refer to Map features.

Example

"highway=*"
"highway=motorway"
"landuse=*"
"natural=water"
"building=*"

orbit_direction

String parameter that specifies the satellite orbit direction, which can be ascending or descending. Setting this parameter to `null searches for both orbit directions.

Example

"DESCENDING"
"ASCENDING"

orbit_relative_number

Number that specifies the relative orbit number. This relative orbit number can be derived from the absolute orbit number. For more information, please refer to the Copernicus Open Access Hub.

Example

165

output_epsg_code

EPSG code that defines the coordinate reference system of the output. By default, the UTM zone of the image location is set.

Example

null
4326
3857

output_original_raster

Outputs the original reflectance dataset, along with the NDVI map.

Example

true
false

output_prefix

Prefix of tile names (defaults to the filename of the input image).

Example

"my_area_"

pan

Parameter that specifies the conversion of the panchromatic band.

Example

true
false

panchromatic_band

Specifies if the panchromatic band is appended to the output.

Example

true
false

polarisations

Sentinel-1 is a SAR system that can transmit a signal in either horizontal (H) or vertical (V) polarisation, and then receive in both H and V polarisations.

Example

["VV", "VH"]
["HH", "HV"]
["VV"]
["VH"]
["HV"]
["HH"]

prefix

A file structure prefix that limits the dataset search to a specific subdirectory. Conforms to the Google Cloud Storage and Amazon Web Services prefix structure, which excludes the bucket name.

Example

"folder1/folder2"

qa_mask

String parameter that specifies which quantile mask to use. This enables filtering out pixel values based on quantile.

Example

['nomask', 'mask50', 'mask75']

red

The placeholder band to be used for calculating values in the red channel. Please note that the band names depend on the satellite sensor (e.g. Landsat-8, Sentinel-2, Pléiades etc.)

Example

"B"
"B03"

resampling_method

Parameter specifying which resampling method to be used when reprojecting an image. Methods: cubic (suitable for continuous data or images) and nearest (suitable for categorical data such as the k-means clustering outputs).

Example

"cubic"
"nearest"

resolution

The pixel resolution of the re-gridded Level-3 product measured in arcseconds. The minimum supported value is 0.07.

Example

0.1
0.08

satellite

This parameter indicates the satellite sensor of the data block.

Example

"Sentinel-2 Level 2 (BOA) AOI clipped"
"Landsat-8 Level 1 (TOA) AOI clipped"

speckle_filter

Applies a Lee Sigma filter to remove speckle noise from the image.

Example

true
false

start_azimuth_degrees

The first value of the azimuth angle.

Example

0

stats

One or more of the following variables: min, max, mean, sum, std, median, majority, minority, unique, range, nodata, percentile_[0-100], count.

Example

["min"]
["max"]
["mean"]
["min","max","mean"]

stereo_images_only

Returns all possible (tri-)stereo images for a specific AOI and time. If (tri-)stereo images are available, they are usually acquired with a time difference of less than a minute and have an almost identical spatial coverage.

Example

true
false

strength

Strength of the RetinaNet model or the image sharpening operation: light, medium and strong.

Example

light
medium
strong

target_height_meters

The target elevation at which the viewshed is computed (meters).

Example

0

tcorrection

Applies a Range Doppler Terrain Correction based on a suitable DEM.

Example

true
false

threshold_values

A list specifying the vegetation types and their corresponding values.

Example

[
   {
     "no_vegetation": 0.2,
     "dense_vegetation": 0.9,
     "sparse_vegetation": 0.4,
     "moderate_vegetation": 0.6
   }
 ]

tile_height

The height of the image tile (measured in pixels).

Example

1232
768
512

tile_width

The width of the image tile (measured in pixels).

Example

1232
768
512

time

RFC 3339 DateTime format that searches for datasets acquired during a specified date and time range. Structure: %Y-%m-%dT%H:%M:%S+00:00

Example

"2019-02-01T00:00:00+00:00/2019-03-01T00:00:00+00:00"

time_interval

The number of hours between the measurement start and end.

Example

6

time_series

RFC 3339 DateTime format that searches for datasets according to an array of time ranges. When specifying this job parameter, make sure to set the correct values for the following job parameters: time and limit (see table below).

Example

["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"]

weight

Parameter of the Brovey pan-sharpening method that ranges from 0 to 1.

Example

0.2

weights

Parameter of the Esri pan-sharpening method that indicates the weights of each multispectral band. The weights depend on the overlap of the spectral sensitivity curves of the multispectral bands with the panchromatic band.The values range from 0 to 1.

Example

[0.2, 0.34, 0.34, 0.23]

y

This parameter defines the coefficient derived from the components of atmospheric reflectance in the blue and red channel.

Example

0.1

zones

Array of Polygon features that delineate the zones where statistics is computed. Defaults to an empty array, which means that the entire geometry is computed as one zone. Each zone can have a unique identifier by adding the parameter `zone_id. If this parameter is not set, the default value will be an integer starting with 0 (first feature). CRS of geometry needs to be WGS84 (EPSG=4326).

Example

[
{"type": 
"Feature", "geometry": {"type": "Polygon", "coordinates": [[
[-1.5439867973327637, 46.41073012821116], 
[-1.5437829494476318, 46.41010134899927], 
[-1.5435147285461426, 46.40955393531244], 
[-1.5426886081695557, 46.409872027718066],
[-1.5433108806610107, 46.410781909705555],
[-1.5439867973327637, 46.41073012821116]]]}, "properties": 
{"zone_id": "zone_left"}}, 
{"type":
"Feature", "geometry": {"type": "Polygon", "coordinates": [[
[-1.5447914600372314, 46.41083369115079], 
[-1.5449309349060059, 46.410345464142345],
[-1.545274257659912,  46.40988682266853], 
[-1.5440940856933592, 46.40956873034918], 
[-1.5438902378082275, 46.409738872983304],
[-1.544201374053955,  46.41080410175952], 
[-1.5447914600372314, 46.41083369115079]]]}, "properties": 
{"zone_id": "zone_right" }}
]

zones_attribute_id

Unique identifier for each feature geometry from a FeatureCollection. Defaults to stats_id. If stats_id is replaced with null, an integer (starting with 0) is used for each feature.

Example

stats_id
null

zoom_level

This parameter applies to streamed images. The zoom level is an integer defining the web mercator zoom level. The bigger the zoom level, the smaller the image tile and the higher the spatial resolution.

Example

17
18
19
20