Ragnar API (Search Imagery)

Ragnar API is a system that can be used for searching and ordering satellite imagery.

Available Satellite Imagery Providers

Ragnar API is an entry point for images from several satellite providers:

Digital Globe GBDX

  • Identifier: gbdx
  • Resolution: High
  • Datasets:
Cold Storage (Full Archive) Full-Resolution (IDAHO) Satellites
preview-multispectral ~16 m/px idaho-pansharpened 0.3–1 m/px GE01, QB02, WV02, WV03_VNIR, WV04
preview-swir ~16 m/px idaho-swir 7.5–11 m/px WV03_SWIR
preview-panchromatic ~16 m/px idaho-panchromatic 0.3–1 m/px WV01

GBDX provider is deprecated and offline. Data were ingested as Level 1B product with values as raw Digital Numbers (DN) with no compensation.

MAXAR ARD

  • Identifier: maxar
  • Resolution: High
  • Datasets:
Full-Resolution (IDAHO) Satellites
ard 0.3–1 m/px GE01, WV02, WV03_VNIR, WV04

Data are ingested as ortorectified imagery with atmospheric compensation. ARD endpoint returns panchromatic and multispectral imagery which we pansharpen on platform to get high res multiband imagery. ARD imagery is tiled in ~25km2 tiles that we treat as a scenes.

Planet

  • Identifier: pl
  • Resolution: Medium - High
  • Links: Planet docs, Planet bundles
  • Datasets:
    • PSOrthoTile - composites of PlanetScope satellites 4 band imagery
    • PSOrthoTile_tile - tiled version of PSOrthotile
    • PSScene3Band - PlanetScope 3 Band
    • PSScene3Band_tile - tiled version of PSScene3Band
    • PSScene4Band - PlanetScope 4 Band
    • PSScene4Band_tile - tiled version of PSScene4Band
    • SkySatScene - Single SkySat scene as a scene provider.
    • SkySatCollect - Collection of SkySat scenes as tile provider.
    • SkySatCollect_pansharpened - 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.

We use Planet’s product level ortho_analytic for tile providers via analytic bundle, except SkySatCollect_pansharpened which uses ortho_pansharpened via pansharpened bundle

Iceye

  • Identifier: iceye
  • Resolution: High
  • Datasets:
    • Spotlight_SLC - 1 m/px
    • SpotlightHigh_SLC - 1 m/px
    • Stripmap_SLC - 3 m/px
    • StripmapHigh_SLC - 3 m/px
    • Spotlight_GRD - 0.5 m/px
    • SpotlightHigh_GRD - 0.5 m/px
    • Stripmap_GRD - 2.5 m/px
    • StripmapHigh_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 [1]
    • COPERNICUS/S2
    • COPERNICUS/S2_SR - Surface reflectance version of S2 dataset
    • JAXA/GPM_L3/GSMaP/v6/operational
    • LANDSAT/LC08/C01/T1
    • LANDSAT/LE07/C01/T1
    • MODIS/006/MOD08_M3
    • MODIS/006/MYD08_M3
  • Links: Earth Engine Docs, Landsat Spectral Bands
[1]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.
[2]Following bands are currently not available: Aerosol_PSML003_Ocean_Mean_Mean, Aerosol_PSML003_Ocean_Std_Deviation_Mean, Aerosol_PSML003_Ocean_QA_Mean_Mean, Aerosol_PSML003_Ocean_QA_Std_Deviation_Mean. Note that original Earth Engine bands are represented as individual scenes.

ESA

  • Identifier: esa
  • Resolution: Low
  • Datasets:
    • COPERNICUS/S1_SLC

Data are downloaded with priority from Alaska Satellite Facility (https://asf.alaska.edu/, API endpoint https://api.daac.asf.alaska.edu) if they are not located there they are downloaded from https://scihub.copernicus.eu/.

NOAA

  • Identifier: noaa
  • Resolution: Low
  • Datasets:
    • VIIRS/Daily – are daily mosaics of night-time data. Only cached data and data from current and previous month are available.
    • (Deprecated) VIIRS/Monthly – are monthly composites of night-time data.
  • Links: NOAA VIIRS Daily Docs, NOAA VIIRS Montly Docs

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 scene; always present.
  • foreignId - ID of a scene on imagery provider side; always present.
  • provider - provider identifier; always present.
  • dataset - dataset identifier; always present.
  • satellite - satellite (sensor) name; always present.
  • datetime - scene acquisition date and time in YYYY-MM-DD HH:MM:SS format and UTC timezone; always present.
  • crsEpsg - EPSG code of coordinate reference system; always present.
  • footprint - geo-footprint of the photographed scene; always present.
  • offNadir - satellite off nadir angle in degrees; may be unavailable.
  • sunElevation, sunAzimuth - sun positioning angles in degrees. Sun elevation is negative for night time images; may be unavailable.
  • satelliteAzimuth - satellite position angle in degrees; may be unavailable.
  • cloudCover - Ratio of scene area covered by clouds. Values 0 to 1; may be unavailable.
  • anomalousRatio - Ratio of pixels that have image quality issues. Values 0 to 1; may be unavailable.
  • mode - satellite acquisition mode; may be unavailable.
  • orbitPass - this has value ascending if the satellite was moving northwards, descending otherwise; may be unavailable.
  • sensorQualityFlag - boolean flag, true if the scene passed sensor quality checks defined by the provider; may be unavailable.
  • groundControlFlag - boolean flag, true if the scene has proper ground control; may be unavailable.
  • bands - list of captured bands;
    • bands[i].names - array of name aliases of the given band; always present.
    • bands[i].bitDepth - band bit depth; always present.
    • bands[i].gsd - ground sampling distance in meters; always present.
    • bands[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 endpoint; always present.
    • bands[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 image; always present.
    • bands[i].radianceMult, bands[i].radianceAdd are radiance parameters for the band; may be unavailable.
    • bands[i].reflectanceMult, bands[i].reflectanceAdd are reflectance parameters for the band; may be unavailable.

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:

(1)\[x_p = \frac{x_c - o_x}{s_x},\]\[y_p = \frac{y_c - o_y}{s_y},\]

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.

../_images/sun.png

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.

../_images/satellite.png

Radiance and Reflectance:

Use this equation to calculate spectral radiance of a pixel

\[L_{\lambda} = M_{radiance} \cdot P_{int} + A_{radiance},\]

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

\[\rho^\prime_{\lambda} = M_{reflectance} \cdot P_{int} + A_{reflectance},\]

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:

\[\rho^\prime_{\lambda} = \frac{\pi \cdot L_{\lambda} \cdot d^2}{ESUN_{\lambda}},\]

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:

\[\rho_{\lambda} = \frac{\rho^\prime_{\lambda}}{sin(\theta_s)},\]

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.

\[r = \frac{area(E \cap S)}{area(E)},\]

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 200 x 200 km, except for ee MODIS/* and noaa VIIRS/* datasets which allow searching the whole world.
Request JSON Object:
 
  • provider (string) – required; imagery provider identifier, see Available Satellite Imagery Providers.
  • 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.
  • 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.

Example request:

{
    "cursor": "waSiuTUsxjPboJWCr0yE",
    "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.

Response JSON Object:
 
  • results (list) – list of found scenes
  • results[i] (object) – image metadata

Example response:

{
    "cursor": null,
    "results": [
        {
            "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

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