Skip to main content
Version: 1.0

Raster Analytics API

Raster Analytics API provides direct, scalable, high-performance access to imagery with dynamic on-the-fly processing. The service presents available images as a virtual GeoTIFF. The images are virtual in that they are created just-in-time upon service request. This allows the Raster Analytics API to support a multitude of ouput representations for a given collect, providing users the exact image data they need.

Raster Analytics API renders imagery on demand from IPE scripts and serves it as a virtual GeoTIFF that is read with tile-aligned HTTP byte-range requests.

What defines an image Every image endpoint (/{script_id}/metadata, /{script_id}/geotiff, /{script_id}/rpc) identifies an image by the parameters used. Send the same parameters, on every request, for that image.

  • Script id (path {script_id}): a stored, immutable IPEScript, for example ortho.
  • Function (query function): the entry point inside that script to evaluate, for example pansharp_ortho.
  • Parameters (repeated query p=key=value): the inputs to that function. Each value is parsed as JSON: string values are quoted, booleans and numbers are not. Quotes must be URL-encoded, for example p=collect_identifier=%2210400100655F5400%22&p=crs=%22UTM%22&p=bands=%22rgb%22&p=dra=true. The collect identifier selects the source imagery; the remaining parameters shape the output, for example crs (output projection), bands (band selection or combination), dra (dynamic range adjustment).

Together these three values fully determine the image the service presents: its extent, pixel size, coordinate system, band count and data type, and therefore its tile grid and GeoTIFF byte layout. Changing any parameter, even one that only alters pixel values, defines a different image with its own tile grid. Never mix byte ranges across different parameter sets.

Inspecting versus downloading GET /{script_id}/metadata exists to inspect an image: dimensions, tile size, spatial transform, band descriptions, histogram and statistics. It is purely informational and is not part of the download path. To download an image you do not need to call /metadata at all. The required first step is a single HEAD /{script_id}/geotiff, which returns everything a client needs to compute the tile grid and per-tile byte ranges.

/metadata and /rpc are rate limited far more restrictively than /geotiff to keep them from being used as a per-tile, per-worker or polling call. Call them at most once per image, from one place, and never from inside a download loop. Exceeding the limit returns 429 with Retry-After.

How to download a whole image efficiently

  • Request one TIFF tile per byte-range request against GET /{script_id}/geotiff, aligned to the tile grid. Read the TIFF header first (HEAD /{script_id}/geotiff) to get the tile grid and each tile's byte range. Never request arbitrary byte ranges that span or split tiles.
  • Use ONE shared queue and ONE bounded worker pool per image. Up to 16 concurrent tile requests per image is fine, provided the queue is ordered with spatially bounded mixed ordering: divide the tile grid into parts of about 128x128 tiles, visit parts row-major, randomize tile order within each part, and let workers flow across part boundaries.
  • Anti-pattern, do not do this: splitting the image into large granules, strips or chunks and processing those granules in parallel, with each granule running its own concurrent tile fetches. Nested parallelism of this kind multiplies the service's active working set, spreads requests across the whole image at once, defeats server-side prefetch, and makes the service less efficient for everyone. It does not make your download faster.
  • On 429 or 503, honour Retry-After and retry with exponential backoff and jitter. Do not re-issue the same request immediately and do not add workers in response.

Authentication​

Bearer token from Oauth2 Password Flow

Security Scheme Type:

oauth2

OAuth Flow (password):

Scopes:

    License

    License

    Last updated on