Ragnar API (Search Imagery)
Ragnar API is a system that can be used for searching and ordering satellite imagery.
Note
Although we commonly use provider
dataset
pair to identify
datasets, the dataset
names are unique by themselves.
Available Satellite Imagery Providers
Ragnar API is an entry point for images from several satellite providers:
Digital Globe GBDX
Identifier:
gbdx
Resolution: High
Datasets:
Full-Resolution (IDAHO) |
Satellites |
|
---|---|---|
|
0.3–1 m/px |
GE01, QB02, WV02, WV03_VNIR, WV04 |
GBDX provider is deprecated and offline. Data were ingested as Level 1B product with values as raw Digital Numbers (DN) with no compensation.
MAXAR
Identifier:
maxar
Resolution: High
Datasets:
Full-Resolution (IDAHO) |
Satellites |
|
---|---|---|
|
0.3–1 m/px |
GE01, WV02, WV03_VNIR, WV04 |
|
0.3–1 m/px |
GE01, WV02, WV03, WV04 |
|
0.3–0.6 m/px |
GE01, WV02, WV03, WV04 |
For MAXAR we provide ARD and SecureWatch data on platform.
ARD
ARD data are ingested as orthorectified imagery with atmospheric compensation. ARD endpoint returns panchromatic and multispectral imagery which we pansharpen on platform to get high res multiband imagery.
ard
dataset is tiled in ~25km2 tiles that we treat as a scenes.
ard_clipped
search returns full sized Maxar scenes. Allows only clipped imagery.
Securewatch
ortho_4ps
search returns full sized Maxar securewatch
scenes. This is
Map_Ready(Ortho) product with MAXAR processing level 3D. Contains standardized
orthorectified imagery. Allows only clipped imagery.
Clipped datasets
ard_clipped
and ortho_4ps
can be only requested as clipped imagery.
Clipped datasets download only a requested extent as clipped part of a whole
scene to save costs. This will generate new geometry cached scene ID.
Footprint of the clipped imagery can not be directly extended and needs to be
fully re-downloaded if required with different extent.
However it’s possible to run any subset extent on already ingested clipped
scene by re-running search only for downloaded imagery.
Links: ARD Platform Info, Securewatch Info
Planet
Identifier:
pl
Resolution: Medium - High
Links: Planet docs, Planet bundles
Datasets:
PSScene4Band
- TOA (ortho_analytic
) product level of PlanetScope 4 Band.PSScene4Band_tile
- tiled version ofPSScene4Band
PSScene
- TOA (ortho_analytic
) product level of PlanetScope that contains 8 band (ortho_analytic_8b
) asset. (Currently only scenes from thePSB.SD
instrument can provide full 8 bands).PSScene_tile
- tiled version ofPSScene
PSScene_analytic_4b_sr
- surface reflectance product level of PSScene with 4 bands.PSScene_analytic_4b_sr_tile
- tiled version ofPSScene_analytic_4b_sr
SkySatScene
- TOA (ortho_analytic
) product level of Single SkySat scene as a scene provider.SkySatCollect
- Collection of SkySat scenes as tile provider.SkySatCollect_pansharpened
-ortho_pansharpened
product level of SkySat satellites -pansharpened
bundle
We provide two versions of PlanetScope datasets. The ones with _tile
suffix
are ingested in tiles rather than ingesting whole scenes from Planet.
These are suitable for analyzing small regions to minimize usage of Planet
imagery.
The ones without _tile
suffix are suitable for analyzing regions similar in
size to scenes in the respective dataset. Ingesting whole scene is faster than
ingesting the same scene in tiles.
Iceye
Identifier:
iceye
Resolution: High
Datasets:
Spotlight_SLC
- 1 m/pxSpotlightHigh_SLC
- 1 m/pxStripmap_SLC
- 3 m/pxStripmapHigh_SLC
- 3 m/pxSpotlight_GRD
- 0.5 m/pxSpotlightHigh_GRD
- 0.5 m/pxStripmap_GRD
- 2.5 m/pxStripmapHigh_GRD
- 2.5 m/px
Currently an offline provider without direct access to catalog, however tasking of imagery and historical imagery can be requested.
Earth Engine
Identifier:
ee
Resolution: Low
Datasets:
COPERNICUS/S1_GRD
- backscatter is represented by 16 bit unsigned integers. Use this formula to get backscatter coefficient \(c = d \cdot 2^{-15}\) where \(d\) represents digital value.COPERNICUS/S2_HARMONIZED
- we useHARMONIZED
versions of S2 datasets to ensure compatibility of the data before and after 2022-01. In 2022-01 ESA changed processing method for the plainCOPERNICUS/S2
dataset, making it unusable for timeseries analysis.COPERNICUS/S2_SR_HARMONIZED
- surface reflectance data are compensated for the impact of atmosphere like weather and haze. Standard S2 data are TOA, top-of-atmosphere.GOOGLE/DYNAMICWORLD/V1
- Land Use/Land Cover (LULC) dataset over S2JAXA/GPM_L3/GSMaP/v6/operational
LANDSAT/LC08/C02/T1
LANDSAT/LE07/C02/T1
ESA
Identifier:
esa
Resolution: Low
Datasets:
COPERNICUS/S1_SLC
Data are downloaded from Alaska Satellite Facility (https://asf.alaska.edu/, API endpoint https://api.daac.asf.alaska.edu) or https://dataspace.copernicus.eu/.
NOAA
Identifier:
noaa
Resolution: Low
Datasets:
VIIRS/Monthly
– are monthly composites of night-time data.
Links: NOAA VIIRS Monthly Docs
Satellogic
Identifier:
satellogic
Resolution: High
Datasets:
newsat
– 1m/px imagery data with 4 bands (red, green, blue, near-IR) and are ortho-rectified and TOA corrected.newsat_sr
– 0.70m/px super-resolution version of newsat imagery with 4 bands (red, green, blue, near-IR). Is ortho-rectified and TOA corrected. Super-resolution is done with proprietary Satellogic algorithms.
Links: Satellogic NewSat data sheet
Airbus
Identifier:
ab
Resolution: High
Datasets:
Dataset |
Resolution |
Bands |
---|---|---|
|
1.5 m/px |
red, green, blue, NIR |
|
0.5 m/px |
red, green, blue, NIR |
|
0.3 m/px |
Red, Green, Blue, NIR, Red Edge, Deep Blue |
Data are ingested as pansharpened reflectance imagery.
Search returns full sized Airbus scenes. For download of the data imagery clipping must be used to save costs. This will generate new geometry cached scene ID. Footprint of the clipped imagery can not be directly extended and needs to be fully re-downloaded if required with different extent. However it’s possible to run any subset extent on already ingested clipped scene by re-running search only for downloaded imagery.
Data are downloaded through UP42.
Links: UP42 datasets
Capella
Identifier:
capella
Resolution: High
Datasets:
Dataset |
Resolution |
Bands |
---|---|---|
|
0.3 - 0.6 m/px |
HH |
|
0.7 - 1.5 m/px |
HH |
|
0.5 - 1.3 m/px |
HH |
High resolution SAR data.
Links: Capella open dataset
Umbra
Identifier:
umbra
Resolution: High
Datasets:
Dataset |
Resolution |
Bands |
---|---|---|
|
0.25 - 1 m/px |
VV |
High resolution SAR data. Archive access download is not available through API. GEC product provides Geocoded Ellipsoid Corrected imagery.
Links: Umbra help
Image Metadata
Image metadata is a JSON object returned as part of replies of Search Scenes endpoint. Some of the attributes are guaranteed to be always present, some may appear only after some imagery from a given scene is requested, some may be totally unavailable for a given scene.
Image Metadata Object:
sceneId
- ID of a sceneforeignId
- ID of a scene on imagery provider sideprovider
- provider identifierdataset
- dataset identifiersatellite
- satellite (sensor) namedatetime
- scene acquisition date and time inYYYY-MM-DD HH:MM:SS
format and UTC timezonecrsEpsg
- EPSG code of coordinate reference systemfootprint
- geo-footprint of the photographed sceneoffNadir
- satellite off nadir angle in degrees; optionalsunElevation
,sunAzimuth
- sun positioning angles in degrees. Sun elevation is negative for night time images; optionallocalTime
- local time of the scene acquisition; optionalcloudCover
- Ratio of scene area covered by clouds. Values 0 to 1; optionalsatelliteAzimuth
- satellite position angle in degrees; optionalanomalousRatio
- Ratio of pixels that have image quality issues. Values 0 to 1; optionalmode
- satellite acquisition mode; optionalorbitPass
- this has valueascending
if the satellite was moving northwards,descending
otherwise; optionalsensorQualityFlag
- boolean flag,true
if the scene passed sensor quality checks defined by the provider; optionalgroundControlFlag
- boolean flag,true
if the scene has proper ground control; optionallookSide
- look side of the satellite, eitherleft
orright
; SAR specific; optionalrelativeOrbitNumberStart
- relative orbit number at the start of the scene; SAR specific; optionalsliceNumber
- slice number of the scene; SAR specific; optionalrelativeOrbitNumberStop
- relative orbit number at the end of the scene; SAR specific; optionallooks
- number of looks used for SAR processing; SAR specific; optionalbands
- list of captured bandsbands[i].names
- array of name aliases of the given bandbands[i].bitDepth
- band bit depthbands[i].gsd
- ground sampling distance in metersbands[i].pixelSizeX
,bands[i].pixelSizeY
- amount of CRS units per band pixel, \(s_x\) and \(s_y\) in (1); If scaling is requested this value corresponds to scaled image and will be different from the value returned by Search Scenes endpointbands[i].crsOriginX
,bands[i].crsOriginY
- coordinates referring to the top-left pixel of i-th band in its CRS, \(o_x\) and \(o_y\) in (1)bands[i].approximateResolutionX
,bands[i].approximateResolutionY
- approximate pixel sizes in meters (width and height respectively) of the given band. If scaling is requested these values correspond to scaled imagebands[i].radianceMult
,bands[i].radianceAdd
are radiance parameters for the band; optionalbands[i].reflectanceMult
,bands[i].reflectanceAdd
are reflectance parameters for the band; optional
CRS EPSG:
EPSG is a code of a coordinate system for all bands from a scene. Following equations apply for each band from the scene:
where \(x_p\) and \(y_p\) are pixel coordinates within a band (e.g. 5, 10 is 6th pixel from the left and 11th pixel from the top), \(x_c\) and \(y_c\) are coordinates in the CRS given by the EPSG, \(s_x\) and \(s_y\) is pixel width and pixel height of a band (the size may differ from band to band), \(o_x\), \(o_y\) are coordinates of the top-left corner referring to the top-left pixel of a band image.
Gotchas:
All pixels from a single band are rectangles of equal size.
Bands from a single scene don’t necessarily have equal pixel sizes.
Pixel width or height may be negative (coordinates of an image pixel go in the opposite direction from coordinates of the CRS).
Pixels don’t have to be squares, but they are always rectangles.
An approximate pixel size in meters can be calculated but the size of each pixel within a band may ~vary~ depending on the CRS.
Two pixels from the same location and from two scenes with a different CRS but with equal pixel sizes (in units of CRS) may have different physical sizes (in meters).
Footprint:
Footprint is a GeoJSON MultiPolygon
in WGS84 coordinates that encloses an area on Earth,
which is photographed in the scene.
Sun Elevation and Sun Azimuth:
Frame of reference for sun elevation and sun azimuth is the location and time of the image.
Sun elevation (solar elevation angle) is the “altitude” of the sun, the angle between the horizon and the centre of the sun’s disc.
Sun azimuth angle defines direction of the sun.
Off Nadir, Satellite Elevation and Satellite Azimuth:
Off Nadir is the angle between Nadir and the direction of the satellite sensor. Satellite elevation is complementary to off Nadir angle, their sum is 90°.
Satellite azimuth is the direction of the satellite from the location of the image. It is the angle between north-heading meridian and surface projection of the line crossing satellite and the image.
Radiance and Reflectance:
Use this equation to calculate spectral radiance of a pixel
where \(M_{radiance}\) is radiance multiplicative correction factor
(radianceMult
), \(P_{int}\) is pixel value (see below) and
\(A_{radiance}\) is radiance additive correction factor (radianceAdd
).
Value of \(L_{\lambda}\) represents the flux power per unit of solid angle,
projected area and wavelength. Units are
\(W \cdot sr^{-1} \cdot m^{-2} \cdot \mu m^{-1}\).
This is formula to calculate TOA (top-of-atmosphere) reflectance of area in a pixel
where \(M_{reflectance}\) is reflectance multiplicative correction factor
(reflectanceMult
), \(P_{int}\) is pixel value (see below) and
\(A_{reflectance}\) is reflectance additive correction factor
(reflectanceAdd
). \(\rho^\prime_{\lambda}\) is not corrected with solar
angle. It is unitless.
Reflectance is defined by the following formula:
where \(L_{\lambda}\) is pixel radiance, \(d^2\) is square of distance between Earth and Sun in AU and \(ESUN_{\lambda}\) is mean solar exoatmospheric irradiance in \(W \cdot m^{-2} \cdot \mu m^{-1}\) (on the band frequency).
The following formula can be used to correct reflectance by solar angle:
where \(\theta_s\) corresponds to sun elevation angle (sunElevation
).
Pixel value (\(P_{int}\)) used in above formulas is a value between 0 and \(2^n\) where \(n\) is bit dept.
Note
Correction factors for radiance and reflectance may differ for each band.
Search Scenes
Ragnar API search returns all scenes that intersect with a requested extent and have an intersection ratio greater than or equal to a given threshold.
An intersection ratio is a fraction of the intersection area of the extent with scene and the total area of the extent. An extent area is a union of all area-based (Polygon and MultiPolygon) extent geometries.
where r
is the intersection ratio, E
is the area covered by the extent and
S
is the area covered by the scene.
Scenes search API is asynchronous and paginated.
Needed Permissions: imagery.availability.<provider>.<dataset>
- POST /imagery/search/initiate
Initiates imagery search pipeline.
Search area must be smaller than 400 x 400 km, except for
ee
COPERNICUS/S5P/OFFL/L3_CH4
,ee
JAXA/GPM_L3/GSMaP/v6/operational
andnoaa
VIIRS/Monthly
datasets which allow searching the whole world. With flagsceneCoverage
this area is increased to 4000 x 4000 km to allow getting scene coverage over larger area.
Warning
When searching multiple datasets at once
ee
COPERNICUS/S5P/OFFL/L3_CH4
andee
JAXA/GPM_L3/GSMaP/v6/operational
datasets must be searched separately from other datasets as their search is not compatible with the rest of the datasets.- Request JSON Object:
datasets (list) – required; list of dictionaries containing data about datasets to search for.
datasets[i].provider (string) – required; imagery provider identifier, see Available Satellite Imagery Providers.
datasets[i].dataset (string) – required; imagery dataset, see Available Satellite Imagery Providers.
extent (object) – required; area to be searched. See Extent.
startDatetime (string) – optional; UTC date-time filter in format
YYYY-MM-DD HH:MM:SS
endDatetime (string) – optional; UTC date-time filter in format
YYYY-MM-DD HH:MM:SS
minIntersection (float) – optional; a number between 0 and 1 (\(0 \leq i \leq 1\)). 0 means arbitrarily but still present intersection.
cursor (int) – optional; If cursor is set in
retrieve
response, you can retrieve more scenes by using the cursor value in the next initiate query.onlyDownloadable (boolean) – optional; set this flag to filter-out scenes which are searchable in the provider catalog but cannot be downloaded; useful for Planet datasets where this situation occurs.
onlyIngested (boolean) – optional; set this flag to filter-out scenes which are not fully downloaded in Phoenix. Useful for finding scenes directly usable by platform without any ingest from provider. For EE datasets it can happen that scene is not available in Phoenix but is still available in Kraken. These scenes are not found using onlyIngested flag.
sceneCoverage (boolean) – optional; set this flag to retrieve only simplified footprints of the scenes available over the selected area. Changes the default output in results to a list of footprints.
Example request:
{ "cursor": 123, "datasets": [ { "provider": "gbdx", "dataset": "idaho-pansharpened" } ], "startDatetime": "2014-09-05 08:55:40", "endDatetime": "2015-11-19 17:52:14", "extent": { "type": "GeometryCollection", "geometries": [ { "type": "Polygon", "coordinates": [ [ [ 115.84512233734131, -31.96024562403475 ], [ 115.84490776062012, -31.96559774488045 ], [ 115.84851264953612, -31.965452113067933 ], [ 115.84842681884766, -31.96053690394404 ], [ 115.84512233734131, -31.96024562403475 ] ] ] } ] } }
Example response:
See pipeline initiation.
Needed Permissions: imagery.availability
- POST /imagery/search/retrieve
Example request:
See pipeline retrieve.
- Request JSON Object:
cursor (int) – optional; If cursor is set then there are further results available. Call
initiate
endpoint again with the cursor to retrieve them.
- Response JSON Object:
results (list) – list of found scenes
results[i] (object) – image metadata
results[i].downloadable (boolean) – optional; indicates whether the image is available for download for current user
results[i].minArea (boolean) – optional; indicates whether image has minimum requested area in km2
results[i].clippedImagery (boolean) – optional; indicates whether image was clipped from bigger original scene
Example response:
{ "cursor": null, "results": [ { "downloadable": true, "clippedImagery": true, "minArea": 5.5, "bands": [ { "bitDepth": 8, "gsd": 0.5, "names": [ "r", "red" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 }, { "bitDepth": 8, "gsd": 0.5, "names": [ "g", "green" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 }, { "bitDepth": 8, "gsd": 0.5, "names": [ "b", "blue" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 } ], "crsEpsg": 4326, "dataset": "idaho-pansharpened", "datetime": "2015-11-13 02:34:12", "offNadir": 23.135675, "provider": "gbdx", "satellite": "WV02", "sceneId": "3f83d1c54e0e2e0a9deaaac728b2b83a", "sunAzimuth": 59.614758, "sunElevation": 65.935, "satelliteAzimuth": 104.794, "footprint": { "type": "MultiPolygon", "coordinates": [[[ [ 115.84490776062012, -31.95409212005078 ], [ 115.8401870727539, -31.96144714770573 ], [ 115.84301948547363, -31.967927822465327 ], [ 115.85010051727295, -31.966253085178234 ], [ 115.85125923156737, -31.962794291914896 ], [ 115.84829807281494, -31.954529068842437 ], [ 115.84490776062012, -31.95409212005078 ] ]]] } } ] }
Scene Info
This API endpoint returns metadata of a single scene.
Needed Permissions: imagery.scene-info
- POST /imagery/scene-info
Example request:
See pipeline retrieve.
- Response JSON Object:
sceneId (string) – ID of a scene
tiles (list) – optional; list of phoenix tiles. Returned scene footprint will contain intersect between scene and provided tiles.
forceOffline (bool) – optional; Returned scene footprint will contain only ingested area.
Example response:
{ "bands": [ { "bitDepth": 8, "gsd": 0.5, "names": [ "r", "red" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 }, { "bitDepth": 8, "gsd": 0.5, "names": [ "g", "green" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 }, { "bitDepth": 8, "gsd": 0.5, "names": [ "b", "blue" ], "pixelSizeX": 5.13212977069823e-06, "pixelSizeY": -4.511257496082e-06 } ], "crsEpsg": 4326, "dataset": "idaho-pansharpened", "datetime": "2015-11-13 02:34:12", "offNadir": 23.135675, "provider": "gbdx", "satellite": "WV02", "sceneId": "3f83d1c54e0e2e0a9deaaac728b2b83a", "sunAzimuth": 59.614758, "sunElevation": 65.935, "satelliteAzimuth": 104.794, "footprint": { "type": "MultiPolygon", "coordinates": [[[ [ 115.84490776062012, -31.95409212005078 ], [ 115.8401870727539, -31.96144714770573 ], [ 115.84301948547363, -31.967927822465327 ], [ 115.85010051727295, -31.966253085178234 ], [ 115.85125923156737, -31.962794291914896 ], [ 115.84829807281494, -31.954529068842437 ], [ 115.84490776062012, -31.95409212005078 ] ]]] } }
Imagery Providers
Use this endpoint to see which providers you can access. Useful to determine the name of the provider and dataset to search for.
Needed Permissions:
imagery.availability
- POST /imagery/datasets/list
Example request:
{}
Example response:
- Response JSON Array of Objects:
providerName (str) – full name of the provider
provider (str) – provider name used throughout the platform
datasetName (str) – full name of the dataset
dataset (str) – dataset name used throughout the platform
downloadable (bool) – is the specific provider dataset combination available to user
requiresSeparateSearch (bool) – signals whether the dataset can be combined with other datasets in single search
datasetType (str) – type of dataset; either
optical
,sar-grd
,sar-slc
,``probabilities``, orenvironmental
thumbnail (bool) – true if thumbnails are available for dataset.
exportable (bool) – true if dataset allows downloading rasterized raw imagery.
maxMbrSide (float) – maximum side of aoi’s minimum bounding rectangle(MBR) in meters.
attribution (str) – attribution of the dataset.
clip (str) –
required
if clipping required.disallowed
otherwisevisualizationBands (list) – optional, list of rgb band names used for visualization. Only for optical imagery.
[ { "providerName": "Earth Engine", "provider": "ee", "datasetName": "Copernicus Sentinel-1 GRD", "dataset": "COPERNICUS/S1_GRD", "downloadable": true, "resolution": [10.0, 40.0], "requiresSeparateSearch": false, "datasetType": "sar-grd", "thumbnail": false, "exportable": false, "maxMbrSide": 400000.0, "attribution": "Copernicus", "clipping": "disallowed" }, { "providerName": "Earth Engine", "provider": "ee", "datasetName": "Copernicus Sentinel-2 Harmonized", "dataset": "COPERNICUS/S2_HARMONIZED", "downloadable": false, "resolution": [10.0, 10.0], "requiresSeparateSearch": false, "datasetType": "optical", "thumbnail": true, "exportable": false, "maxMbrSide": 400000.0, "attribution": "Copernicus", "clipping": "disallowed" }, { "providerName": "Airbus", "provider": "ab", "datasetName": "Pleiades", "dataset": "pleiades", "downloadable": false, "resolution": [0.5, 0.5], "requiresSeparateSearch": false, "datasetType": "optical", "thumbnail": true, "exportable": true, "maxMbrSide": 400000.0, "attribution": "Airbus", "clip": "required", "visualizationBands": ["red", "green", "blue"] } ]
Precipitation data
This API endpoint returns precipitation in millimeters for requested AoI in time window specified by timestamp and number of hours to look back.
Needed Permissions: imagery.scene-info
- POST /imagery/weather/precipitation
- Response JSON Object:
geometry (dict) – geojson of AoI over which the mean precipitation will be calculated. Only Polygon geometry is accepted
endTime (str) – ISO format datetime signifying end of the time window over which the precipitation is calculated
windowSizeHours (int) – number of hours for which the precipitation is calculated
Example request:
{ "geometry": { "type": "Polygon", "coordinates": [[ [-70.99536895751953, 42.430552260619564], [-70.93460083007811, 42.430552260619564], [-70.93460083007811, 42.47817430242155], [-70.99536895751953, 42.47817430242155], [-70.99536895751953, 42.430552260619564]]] }, "endDatetime": "2021-11-12T14:44:40Z", "windowSizeHours": 24 }
Example response:
{ "precipitation": 12.34 }
Perpendicular baselines
This API endpoint returns matrix of perpendicular baselines for S1 SLC scenes. Null is returned if the baseline is not known for given pair.
Needed Permissions: imagery.scene-info
- POST /imagery/perpendicular-baselines
- Response JSON Object:
sceneIds (list) – scene ids for which the baselines will be computed
Example request:
{ "sceneIds": ["scene_id_0", "scene_id_1", "scene_id_2", "scene_id_3"] }
Example response:
{ "indexes": { "scene_id_0": 0, "scene_id_1": 1, "scene_id_2": 2, "scene_id_3": 3 }, "perpendicular_baselines": [[0, 69, 67, null], [69, 0, 136, null], [67, 136, 0, null], [null, null, null, null]] }