Ragnar API (Search and Get Imagery)

Ragnar API is a system that could be used for searching and requesting satellite and aerial imagery.

Available Satellite Imagery Providers

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

Digital Globe GBDX Platform

  • Identifier: gbdx
  • Resolution: High
  • Datasets:
    • preview - low-resolution previews of all available imagery.
    • idaho - search and serve imagery that is already cached in IDAHO sub-platform. All imagery is served within minutes.
    • idaho-pansharpened - pan-sharpened images from idaho dataset.
  • Links: GBDX Platform Info, GBDX Developer Docs

Planet

  • Identifier: pl
  • Resolution: Medium
  • Links: Planet docs
  • Datasets:
    • PSOrthoTile - PlanetScope satellites
    • REOrthoTile - RapidEye satellites

Urthecast

  • Identifier: uc
  • Resolution: Medium
  • Datasets: theia, deimos-2
  • Links: Urthecast docs

Airbus

  • Identifier: ab
  • Resolution: High
  • Datasets: spot, pleiades
  • Links: Airbus docs

Earth Engine

Image Metadata

Image metadata is a JSON object returned as part of replies to Search Scenes and Get Image endpoints, they also appear in meta.json in Spaceknow Image (SKI) files created by Ragnar API. 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.
  • 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; may be available only after imagery is requested.
  • footprint - geo-footprint of the photographed scene; always available, but may be updated to a better precision after imagery is requested.
  • offNadir - satellite off nadir angle in degrees; may be unavailable.
  • sunElevation, sunAzimuth - sun positioning angles in degrees; may be unavailable.
  • cloudCover - Ratio of scene area covered by clouds. Values 0 to 1.
  • bands - list of captured bands; length of the list is either zero (bands are not known yet) or the length does not change:
    • bands[i].names - array of name aliases of the given band; always present.
    • bands[i].bitDepth - band bit depth; may be available only after imagery is requested.
    • bands[i].gsd - ground sampling distance in meters; may be available only after imagery is requested.
    • bands[i].pixelSizeX, bands[i].pixelSizeY - amount of CRS units per band pixel, \(s_x\) and \(s_y\) in (1); may be available only after imagery is requested. If scaling is requested this value corresponds to scaled image and will be different from the value returned by Search Scenes endpoint.
    • 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; may be available only after imagery is requested.
    • 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. This calculations are done on geometries projected into CRS of tested scene.

Scenes search API is asynchronous and paginated.

POST /imagery/search/initiate

Initiates imagery search pipeline.

  • Search area (extent) should not for any provider exceed:
    • Max area: 10 000 km2
    • Max aspect ratio: 10:1. For example 5*7 km is OK, but 0.5*6.5 km has too big ratio.
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.

Example request:

{
    "cursor": "waSiuTUsxjPboJWCr0yE",
    "provider": "ab",
    "dataset": "pleiades",
    "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.

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": "pleiades",
            "datetime": "2015-11-13 02:34:12",
            "offNadir": 23.135675,
            "provider": "ab",
            "satellite": "WV02",
            "sceneId": "ab-pleiades:3f83d1c54e0e2e0a9deaaac728b2b83a",
            "sunAzimuth": 59.614758,
            "sunElevation": 65.935,
            "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
                    ]
                ]]]
            }
        }
    ]
}

Order Scene

Order Scene API is asynchronous.

Ragnar API order is a beta version endpoint and MAY CHANGE WITHOUT NOTICE. Currently supports only ordering of gbdx preview imagery. The user has to have special permission imagery.order. The initial request requires only one parameter previewSceneId, which is identical to sceneId for gbdx preview search response. The results appear in the end in the gbdx idaho catalogue (thus search and imagery).

POST /imagery/order/initiate
Request JSON Object:
 
  • previewSceneId (string) – required; ID of a preview of a scene which should be ordered. Preview IDs are returned by imagery search for provider gbdx and data preview.

Example request:

{
    "previewSceneId": "GuoBFqt3SA6Qu5UzlZQ0HER4dD8Y4fAd0-Ux4qI"
}

Example response:

See pipeline initiation.

POST /imagery/order/retrieve

It returns scene ordering info: original previewSceneId, providerOrderId, and current status of scene ordering. The providerOrderId is an identificator specific to the provider and dataset that corresponds to previewSceneId. The status corresponds to GBDX: SUBMITTED, ORDERING, PLACED, DELIVERED, FAILED.

Example request:

See pipeline retrieve.

Example response:

{
    "previewSceneId": "GuoBFqt3SA6Qu5UzlZQ0HER4dD8Y4fAd0-Ux4qI",
    "providerOrderId": "650fd5fa-c275-4105-bc1f-ea3588219b94",
    "status": "SUBMITTED"
}

Get Image

Get Image API is asynchronous.

Ragnar API get-image returns a rectangular SKI (see Spaceknow Image (SKI)) with imagery data from a location given by a bounding rectangle of the requested extent (see Extent). All area based geometries in the extent are drawn within a mask. The image is a cut-off from a single scene.

Meta of the returned SKI is the same JSON as the JSON which is returned from the retrieve endpoint of the API except property url.

The maximum size of an image retrieved is 3MPx. When a specific scale (resolution) is given both original and scaled images have to be smaller than 3MPx.

Retrieving an image from an imagery provider is a very complex process and may take some time. The time needed to download an image depends on several factors, such as whether SpaceKnow cached the image in the past, how fast provider’s systems work and how big is the image.

Note

Algorithm that determines the exact area covered by the image is as follows:

  1. All vertices of requested extent GeoJSON are projected into coordinate system (CRS) of the scene.
  2. Vertices in the scene’s CRS are further projected to pixel coordinates. This step is done with the help of pixel size and CRS origin metadata.
  3. Minimum bounding rectangle (MBR) of pixel coordinates is calculated and its values are rounded to integers.
  4. The image is a raster image that consists of pixels based on the calculated MBR.
POST /imagery/get-image/initiate
Request JSON Object:
 
  • sceneId (string) – required; ID of the scene from which to construct an image. Scene IDs are returned by imagery search.
  • extent (object) – required; area of interest, see Extent
  • resolution (float) – optional; If given the image is re-scaled so its ground sampling distance approximately corresponds to the value. Units of this parameter are meters. All bands are scaled to the given resolution regardless their original sizes.

Example request:

{
    "sceneId": "ab-pleiades:3f83d1c54e0e2e0a9deaaac728b2b83a",
    "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.

POST /imagery/get-image/retrieve

It returns a single image with its metadata.

Example request:

See pipeline retrieve.

Response JSON Object:
 
  • url (string) – URL of SKI file of the region.
  • meta (object) – a single image metadata.
  • extent (object) – a GeoJSON of the area covered by the returned image.

Example response:

{
    "url": "https://storage.googleapis.com/results.devel.gs.spaceknow.com/pwoEeIq824CUO8ksDfgFRuGCS.ski?Expires=1516207694&GoogleAccessId=ragnar-api%40spaceknow-devel-imagery.iam.gserviceaccount.com&Signature=jFNVlrdqoeyW6ijNM7O2E4ddin%2FgNR4xStGT%2FilqVpnivAQFDFHtpXgmcmMm9Cj7scI%2F2UFmtzOhHACQJY42Coi57JrebjnVsaxUMBEs9hnKNm3XBT53gQ6KCRftUYQUEaDTqsF0A%2B%2FwOUE3whBYlk7u%2F3D1vVr2xuW3LYSGYwmzE%2BZJvrf0rODILETSHuNkIf5rPNtV2zySxP1sQBGbSHxoficIJuDGb7NI04D5%2F7MGeANvymSp0Fa3%2FhFdmMCpZ4fHpACkP42ZqwFuQu196WV%2BMnhkIh7PzLSzevde16g3ShBp7bejoHeeVETMpZO26WEAHBt9SCAJtnO2dQyU8g%3D%3D",
    "meta": {
        "bands": [
            {
                "bitDepth": 8,
                "gsd": 0.5,
                "names": [
                    "r",
                    "red"
                ],
                "approximateResolutionX": 0.49749514251808363,
                "approximateResolutionY": 0.49955903407407787,
                "pixelSizeX": 5.13212977069823e-06,
                "pixelSizeY": -4.511257496082e-06,
                "crsOriginX": -7.4877062,
                "crsOriginY": 0.0002883
            },
            {
                "bitDepth": 8,
                "gsd": 0.5,
                "names": [
                    "g",
                    "green"
                ],
                "approximateResolutionX": 0.49749514251808363,
                "approximateResolutionY": 0.49955903407407787,
                "pixelSizeX": 5.13212977069823e-06,
                "pixelSizeY": -4.511257496082e-06,
                "crsOriginX": -7.4877062,
                "crsOriginY": 0.0002883
            },
            {
                "bitDepth": 8,
                "gsd": 0.5,
                "names": [
                    "b",
                    "blue"
                ],
                "approximateResolutionX": 0.49749514251808363,
                "approximateResolutionY": 0.49955903407407787,
                "pixelSizeX": 5.13212977069823e-06,
                "pixelSizeY": -4.511257496082e-06,
                "crsOriginX": -7.4877062,
                "crsOriginY": 0.0002883
            }
        ],
        "crsEpsg": 4326,
        "dataset": "pleiades",
        "datetime": "2015-11-13 02:34:12",
        "offNadir": 23.135675,
        "provider": "ab",
        "satellite": "WV02",
        "sceneId": "ab-pleiades:3f83d1c54e0e2e0a9deaaac728b2b83a",
        "sunAzimuth": 59.614758,
        "sunElevation": 65.935,
        "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
                ]
            ]]]
        }
    },
    "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
                        ]
                    ]
                ]
            }
        ]
    }
}

Get Provider and Dataset Info

Use this endpoint to retrieve approximate information about maximum extent dimensions and aspect ratio for which imagery could be requested. Width and height of an extent is calculated as distance along a circle of latitude between easternmost and westernmost points and distance along a meridian between northernmost and southernmost points respectively.

POST /size-info
Request JSON Object:
 

Example request:

{
    "provider": "ab",
    "dataset": "pleiades"
}
Response JSON Object:
 
  • maxDim (float) – maximum horizontal and vertical size of an extent in meters.
  • maxArea (float) – maximum area in square meters of extent’s bounding rectangle.
  • maxRatio (float) – maximum disproportion in width and height of extent. Bigger side has to be smaller or equal to max_ratio multiple of smaller side.

Example response:

{
    "maxDim": 2000,
    "maxArea": 1000000,
    "maxRatio": 10
}