.. Copyright (C) 2016-2025 SpaceKnow, Inc. .. _api.ragnar: *************************** Ragnar API (Search Imagery) *************************** Ragnar API is a system that can be used for searching and ordering satellite imagery. .. only:: not holygrail * URL: https://api.spaceknow.com/imagery .. only:: holygrail * URL: http://api.local/imagery .. note:: Although we commonly use ``provider`` ``dataset`` pair to identify datasets, the ``dataset`` names are unique by themselves. .. _api.ragnar.providers: Available Satellite Imagery Providers ===================================== At SpaceKnow we can download imagery three different ways: * Scened datasets download data as whole scenes. * Tile datasets download data in predefined tiles. Tiles are defined from the top left corner of the image. Thus each tile is dependent on the scene geometry. * Clipped datasets download only a requested extent as clipped part of a whole scene to save costs. This will generate new geometry cached 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. The way we download the imagery depends mainly on the capabilities of Provider API. Ragnar API is an entry point for images from several satellite providers: MAXAR ^^^^^ * Identifier: ``maxar`` * Resolution: High * Datasets: +---------------------------------------+----------------------------------------+ | Full-Resolution (IDAHO) | Satellites | +==========================+=====================+===============================+ | ``ard`` [Legacy] | 0.3--1 m/px | GE01, WV02, WV03_VNIR, WV04 | +--------------------------+---------------------+-------------------------------+ | ``ard_clipped`` [Legacy] | 0.3--1 m/px | GE01, WV02, WV03, WV04 | +--------------------------+---------------------+-------------------------------+ | ``ortho_4ps`` | 0.3--0.6 m/px | GE01, WV02, WV03, WV04 | +--------------------------+---------------------+-------------------------------+ For MAXAR we provide ARD and SecureWatch data on platform. ARD [Legacy] ------------ 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. * Links: `ARD Platform Info`_, `Securewatch Info`_ .. _ARD Platform Info: https://ard.maxar.com/docs/ .. _Securewatch Info: https://www.maxar.com/products/securewatch/ Planet ^^^^^^ * Identifier: ``pl`` * Resolution: Medium - High * Links: `Planet docs`_, `Planet bundles`_ * Datasets: * ``PSScene4Band`` - TOA (``ortho_analytic``) product level of PlanetScope 4 Band. * ``PSScene4Band_clipped`` - clipped version of ``PSScene4Band`` * ``PSScene`` - TOA (``ortho_analytic``) product level of PlanetScope that contains 8 band (``ortho_analytic_8b``) asset. (Currently only scenes from the ``PSB.SD`` instrument can provide full 8 bands). * ``PSScene_clipped`` - clipped version of ``PSScene`` * ``PSScene_analytic_4b_sr`` - surface reflectance product level of PSScene with 4 bands. * ``PSScene_analytic_4b_sr_clipped`` - clipped version of ``PSScene_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. Legacy dataset. * ``SkySatCollect_scene`` - Collection of SkySat scenes as scene provider. Legacy dataset. * ``SkySatCollect_clipped`` - Collection of SkySat scenes available for clipped imagery ingestion. * ``SkySatCollect_pansharpened`` - ``ortho_pansharpened`` product level of SkySat satellites - ``pansharpened`` bundle. Legacy dataset. We provide two versions of PlanetScope datasets. The ones with ``_clipped`` suffix are ingested only as the requested AOIs rather than ingesting whole scenes from Planet. These are suitable for analyzing small regions to minimize usage of Planet imagery. The ones without ``_clipped`` suffix are suitable for analyzing regions similar in size to scenes in the respective dataset. Ingesting whole scene is faster than ingesting the same clipped scene. .. _Planet docs: https://developers.planet.com/docs .. _Planet bundles: https://developers.planet.com/apis/orders/product-bundles-reference/ 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 * ``SpotlightFine_GRD`` - 0.25 m/px * ``SpotlightDwell_GRD`` - 0.5 m/px * ``SpotlightDwellFine_GRD`` - 0.25 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`` - backscatter is represented by 16 bit unsigned integers. Use this formula to get backscatter coefficient :math:`c = d \cdot 2^{-15}` where :math:`d` represents digital value. * ``COPERNICUS/S2_HARMONIZED`` - we use ``HARMONIZED`` versions of S2 datasets to ensure compatibility of the data before and after 2022-01. In 2022-01 ESA changed processing method for the plain ``COPERNICUS/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 S2 * ``JAXA/GPM_L3/GSMaP/v6/operational`` * ``LANDSAT/LC08/C02/T1`` * ``LANDSAT/LE07/C02/T1`` * Links: `Earth Engine Docs`_, `Landsat Spectral Bands`_ .. _Earth Engine Docs: https://developers.google.com/earth-engine/ .. _Earth Engine Datasets: https://code.earthengine.google.com/datasets/ .. _Landsat Spectral Bands: http://landsat.usgs.gov/band_designations_landsat_satellites.php 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`_ .. _NOAA VIIRS Monthly Docs: https://eogdata.mines.edu/download_dnb_composites.html Satellogic ^^^^^^^^^^ * Identifier: ``satellogic`` * Resolution: High * Datasets: * ``newsat`` -- 1m/px (MK4 imagery) or 0.7m/px (MK5 imagery) data with 4 bands (red, green, blue, near-IR) and are ortho-rectified and TOA corrected. Satellogic collection ``l1d``. * ``newsat_sr`` -- 0.70m/px (MK4 imagery) or 0.5 m/px (MK5 imagery) 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. Satellogic collection ``l1d-sr`` Archive data is downloaded from `Satellogic STAC`_ API. Be aware that footprint of the archive Satellogic imagery is only approximate and real footprint is slightly smaller. * Links: `Satellogic NewSat data sheet`_ .. _Satellogic NewSat data sheet: https://satellogic.com/documents/satellogic-multispectral-data.pdf .. _Satellogic STAC: https://developers.satellogic.com/archive-service/archive_api_spec.html Airbus ^^^^^^ * Identifier: ``ab`` * Resolution: High * Datasets: +-------------------+-------------+---------------------------------------------+ | Dataset | Resolution | Bands | +===================+=============+=============================================+ | ``spot`` | 1.5 m/px | red, green, blue, NIR | +-------------------+-------------+---------------------------------------------+ | ``pleiades`` | 0.5 m/px | red, green, blue, NIR | +-------------------+-------------+---------------------------------------------+ | ``pleiades-neo`` | 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`_ .. _UP42 datasets: https://docs.up42.com/data/archive/collections/ Capella ^^^^^^^ * Identifier: ``capella`` * Resolution: High * Datasets: +--------------------------+-------------------+--------+ | Dataset | Resolution | Bands | +==========================+===================+========+ | ``spotlight`` | 0.3 - 0.6 m/px | HH | +--------------------------+-------------------+--------+ | ``stripmap`` | 0.7 - 1.5 m/px | HH | +--------------------------+-------------------+--------+ | ``sliding_spotlight`` | 0.5 - 1.3 m/px | HH | +--------------------------+-------------------+--------+ High resolution SAR data. * Links: `Capella open dataset`_ .. _Capella open dataset: https://www.capellaspace.com/gallery/ Umbra ^^^^^ * Identifier: ``umbra`` * Resolution: High * Datasets: +--------------------------+-------------------+--------+ | Dataset | Resolution | Bands | +==========================+===================+========+ | ``spotlight_GEC`` | 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`_ .. _Umbra help: https://help.umbra.space/ Generic ^^^^^^^ * Identifier: ``generic`` * Resolution: Any * Datasets: +--------------------------+-------------------+--------+ | Dataset | Resolution | Bands | +==========================+===================+========+ | ``generic`` | 0.01 - 100 m/px | Any | +--------------------------+-------------------+--------+ Generic data provider used for ad-hoc and testing imagery. Accepts geotiff files with suffix ``tiff``, ``tif`` and ``geotiff`` and ingests it to platform. Scene date is taken from filename suffix after underscore in valid ISO format, eg. ``generic_scene_20240120T172839.tiff`` or ``generic_scene_2024-01-20T17:28:39.tiff``. If the GeoTIFF has less than 3 bands, the first band is used for visualization. If the GeoTIFF has 3 or more bands, the first three bands are used for visualization. Legacy Provider Digital Globe GBDX ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Identifier: ``gbdx`` * Resolution: High * Datasets: +---------------------------------------+-----------------------------------+ | Full-Resolution (IDAHO) | Satellites | +========================+==============+===================================+ | ``idaho-pansharpened`` | 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. * Links: `GBDX Platform Info`_, `GBDX Developer Docs`_ .. _GBDX Platform Info: https://www.digitalglobe.com/platforms/gbdx .. _GBDX Developer Docs: https://developer.digitalglobe.com/gbdx/ .. _api.ragnar.image-metadata: 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 * ``foreignId`` - ID of a scene on imagery provider side * ``provider`` - :ref:`provider identifier ` * ``dataset`` - :ref:`dataset identifier ` * ``satellite`` - satellite (sensor) name * ``datetime`` - scene acquisition date and time in ``YYYY-MM-DD HH:MM:SS`` format and UTC timezone * ``crsEpsg`` - :ref:`EPSG code of coordinate reference system ` * ``footprint`` - :ref:`geo-footprint of the photographed scene ` * ``offNadir`` - :ref:`satellite off nadir angle in degrees `; *optional* * ``sunElevation``, ``sunAzimuth`` - :ref:`sun positioning angles in degrees `. Sun elevation is negative for night time images; *optional* * ``localTime`` - local time of the scene acquisition; *optional* * ``cloudCover`` - Ratio of scene area covered by clouds. Values 0 to 1; *optional* * ``satelliteAzimuth`` - satellite position angle in degrees; *optional* * ``anomalousRatio`` - Ratio of pixels that have image quality issues. Values 0 to 1; *optional* * ``mode`` - satellite acquisition mode; *optional* * ``orbitPass`` - this has value ``ascending`` if the satellite was moving northwards, ``descending`` otherwise; *optional* * ``sensorQualityFlag`` - boolean flag, ``true`` if the scene passed sensor quality checks defined by the provider; *optional* * ``groundControlFlag`` - boolean flag, ``true`` if the scene has proper ground control; *optional* * ``lookSide`` - look side of the satellite, either ``left`` or ``right``; SAR specific; *optional* * ``relativeOrbitNumberStart`` - relative orbit number at the start of the scene; SAR specific; *optional* * ``sliceNumber`` - slice number of the scene; SAR specific; *optional* * ``relativeOrbitNumberStop`` - relative orbit number at the end of the scene; SAR specific; *optional* * ``looks`` - number of looks used for SAR processing; SAR specific; *optional* * ``bands`` - list of captured bands * ``bands[i].names`` - array of name aliases of the given band * ``bands[i].bitDepth`` - band bit depth * ``bands[i].gsd`` - ground sampling distance in meters * ``bands[i].pixelSizeX``, ``bands[i].pixelSizeY`` - amount of CRS units per band pixel, :math:`s_x` and :math:`s_y` in :eq:`crs_eq`; 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, :math:`o_x` and :math:`o_y` in :eq:`crs_eq` * ``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 * ``bands[i].radianceMult``, ``bands[i].radianceAdd`` :ref:`are radiance parameters for the band `; *optional* * ``bands[i].reflectanceMult``, ``bands[i].reflectanceAdd`` :ref:`are reflectance parameters for the band `; *optional* .. _api.ragnar.image-metadata.crs-epsg: **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: .. math:: :label: crs_eq x_p = \frac{x_c - o_x}{s_x}, y_p = \frac{y_c - o_y}{s_y}, where :math:`x_p` and :math:`y_p` are pixel coordinates within a band (e.g. 5, 10 is 6th pixel from the left and 11th pixel from the top), :math:`x_c` and :math:`y_c` are coordinates in the CRS given by the `EPSG`_, :math:`s_x` and :math:`s_y` is pixel width and pixel height of a band (the size may differ from band to band), :math:`o_x`, :math:`o_y` are coordinates of the top-left corner referring to the top-left pixel of a band image. .. _EPSG: http://www.epsg.org/ 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). .. _api.ragnar.image-metadata.footprint: **Footprint**: Footprint is a `GeoJSON`_ ``MultiPolygon`` in WGS84 coordinates that encloses an area on Earth, which is photographed in the scene. .. _GeoJSON: https://tools.ietf.org/html/rfc7946 .. _api.ragnar.image-metadata.sun: **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. .. image:: /attachments/satellite_geometry/sun.png .. _api.ragnar.image-metadata.off-nadir: **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. .. _Nadir: https://en.wikipedia.org/wiki/Nadir .. image:: /attachments/satellite_geometry/satellite.png .. _api.ragnar.image-metadata.radiance-reflectance: **Radiance and Reflectance**: Use this equation to calculate spectral radiance of a pixel .. math:: L_{\lambda} = M_{radiance} \cdot P_{int} + A_{radiance}, where :math:`M_{radiance}` is radiance multiplicative correction factor (``radianceMult``), :math:`P_{int}` is pixel value (see below) and :math:`A_{radiance}` is radiance additive correction factor (``radianceAdd``). Value of :math:`L_{\lambda}` represents the flux power per unit of solid angle, projected area and wavelength. Units are :math:`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 .. math:: \rho^\prime_{\lambda} = M_{reflectance} \cdot P_{int} + A_{reflectance}, where :math:`M_{reflectance}` is reflectance multiplicative correction factor (``reflectanceMult``), :math:`P_{int}` is pixel value (see below) and :math:`A_{reflectance}` is reflectance additive correction factor (``reflectanceAdd``). :math:`\rho^\prime_{\lambda}` is not corrected with solar angle. It is unitless. Reflectance is defined by the following formula: .. math:: \rho^\prime_{\lambda} = \frac{\pi \cdot L_{\lambda} \cdot d^2}{ESUN_{\lambda}}, where :math:`L_{\lambda}` is pixel radiance, :math:`d^2` is square of distance between Earth and Sun in AU and :math:`ESUN_{\lambda}` is mean solar exoatmospheric irradiance in :math:`W \cdot m^{-2} \cdot \mu m^{-1}` (on the band frequency). The following formula can be used to correct reflectance by solar angle: .. math:: \rho_{\lambda} = \frac{\rho^\prime_{\lambda}}{sin(\theta_s)}, where :math:`\theta_s` corresponds to sun elevation angle (``sunElevation``). Pixel value (:math:`P_{int}`) used in above formulas is a value between 0 and :math:`2^n` where :math:`n` is bit dept. .. note:: Correction factors for radiance and reflectance may differ for each band. .. _api.ragnar.search: 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. .. math:: 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 :ref:`asynchronous ` and :ref:`paginated `. See :docs:`Ragnar Search Initiate` and :docs:`Ragnar Search Retrieve`. .. _api.ragnar.scene-info: Scene Info ========== See :docs:`Ragnar Scene Info API reference`. .. _api.ragnar.datasets_endpoint: Imagery Providers ================= See :docs:`List Datasets API reference`.