JSON parameters
View the available job parameters used to configure and run jobs.
Overview
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 Downloadable 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]
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 pansharpening method that controls the blurred edges of the pansharpened 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.
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_layers
MODIS - An array of layer identifiers available from Global Imagery Browse Services.
MODIS example
["MODIS_Terra_CorrectedReflectance_Bands367"]
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 pansharpened 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
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 support.
When specifying this job parameter, make sure to set the correct values for the following job parameters: ids
and time_series
(see table below).
Job parameter | Requirement |
---|---|
ids | The number of IDs must correspond with the number of images specified in limit . |
time_series | The number of time ranges specified in a time series must correspond with the number of images specified in limit . |
Example
1
20
500
5000
linear_to_db
Converts the backscatter coefficient σ° to decibels (dB) with the formula 10*log10σ°.
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
Pansharpening 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
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
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
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.
If set to true
, make sure to also adjust the limit to 500, in order to extend the stereo image search across the archive.
It is recommended to perform a test query, in order to check the availability of (tri-)stereo images without consuming credits during data retrieval.
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.
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
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).
Job parameter | Requirement |
---|---|
time | Set the value to null . Using both time parameters in a job will result in an error. |
limit | The number must correspond with the number of time ranges specified in a time series. |
If the time ranges overlap, some datasets will be retrieved two times.
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 pansharpening method that ranges from 0 to 1.
Example
0.2
weights
Parameter of the Esri pansharpening 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