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

`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 Pléiades and SPOT streaming vs. download blocks.

Example

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

`augmentation_factor`

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

Example

`bbox`

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

Example

Use only one of the 3 geometric filters: bbox, contains, intersects.

`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
         ]
       ]
     ]
   }

Use only one of the 3 geometric filters: bbox, contains, intersects.

`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

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

The geometric filter (bbox/contains/intersects) needs to be defined. However, the job run will consider the geometry from the URL and will ignore the geometric filter.

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.

If this parameter is used without a geometric filter, the full scene is retrieved and this can consume a large amount of credits. If this parameter is used with a geometric filter, the image subset of the full scene is retrieved.

The number of ids needs to correspond with the number defined by limit.

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
         ]
       ]
     ]
   }

Use only one of the 3 geometric filters: bbox, contains, intersects.

`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. To set the maximum number of images to a value higher than 5000, please contact the customer support.

Usage in combination with other JSON parameters:

limit needs to correspond to the number of ids.
limit needs to correspond to the number of time ranges specified in a time series.

Example

`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

`maxsize`

The maximum size of detected ships (meters).

Example

`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

`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

`n_iterations`

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

Example

`n_sieve_pixels`

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

Example

`nclasses`

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

Example

`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`

Objects	Description
`Scenes`	The outline of each satellite scene used to generate the data.
`Ships_Rigs`	All ships and rigs identified on a satellite scene (point feature class).
`Slick_Points`	The predicted oil slick source point (point feature class).
`Slick_Outlines`	The outline of the oil slick on the satellite scene.

Example

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

`observer_height_meters`

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

Example

`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

`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

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

Information 1

If set to true, make sure to also adjust the limit to 500, in order to extend the stereo image search across the archive.

Information 2

It is recommended to perform a test query, in order to check the availability of (tri-)stereo images without consuming credits during data retrieval.

Warning 1

Due to the nature of non-rectified images, clipping them with the clip_to_aoi can cause a substantial shift in the position of the image segment after orthorectification. UP42 provides a mechanism to overcome this issue, but there is a side-effect: the output AOI will be an approximation of the input AOI, because it includes a buffer region.

Warning 2

The output image is clipped to the AOI bounding box, so the image gaps will be padded with zeros until the bounding box is covered. Depending on the AOI shape and irregularity, the final output image might be larger and the credit consumption will slightly increase.

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

`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

`time_series`

RFC 3339 DateTime format that searches for datasets according to an array of time ranges. When specifying this parameter, make sure to set time to null. Using both time parameters in a job will result in an error.

Warning 1

If the time ranges overlap, some datasets will be retrieved two times.

Warning 2

The number of time ranges specified in a time series needs to correspond with the number defined by limit.

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