SAGRIS ODC — API Documentation

Overview #

The SAGRIS ODC exposes two complementary API surfaces: a STAC 1.0 catalog API for dataset discovery and metadata retrieval, and a custom Analysis API for server-side backscatter aggregation over user-supplied geometries. Both require an API key.

The data cube holds 850,000+ analysis-ready Sentinel-1 GRD datasets covering Europe from 2015 to the present, in both VH and VV polarisations. Backscatter values are expressed as gamma-naught (γ⁰) × 10³ integer DN — multiply by 0.001 to obtain linear γ⁰.

ℹ️

OGC Compliance. The STAC endpoint is fully OGC API – Features compliant and can be consumed directly by QGIS 3.x (built-in STAC plugin), ArcGIS Pro, pystac-client, and any GDAL ≥ 3.4 installation.

Authentication #

All API requests must include a valid API key. Keys are issued per user account and tied to a rate-limit tier. Register at odcube.landimage.info/register to obtain a free key.

Header-based authentication (recommended)

HTTP Header
X-Api-Key: YOUR_API_KEY

Query parameter fallback

URL
https://odcube.landimage.info/stac/?api_key=YOUR_API_KEY

⚠️

Security note. Prefer the X-Api-Key header over query parameters to avoid keys appearing in server logs or browser history.

Base URL & Versioning #

All endpoints are served from a single base URL. The STAC API follows the STAC 1.0.0 specification. The Analysis API is versioned implicitly via the /api/ path prefix.

Surface	Path prefix	Spec
STAC Catalog API	/stac/	STAC 1.0.0 · OGC API Features
Analysis / Timeseries API	/api/	Custom REST · JSON
ODC Explorer UI	/products	datacube-explorer
STAC Browser UI	/browser	STAC Browser v5

STAC Root Catalog #

The root catalog endpoint returns the top-level STAC landing page with links to all available collections and conformance declarations.

GET /stac/ Root catalog

Returns a STAC Catalog object with links to collections, the search endpoint, and conformance classes.

curl
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://odcube.landimage.info/stac/

Collections #

Collections group datasets by polarisation. Each collection contains all temporal acquisitions for a given SAR polarisation channel across the European coverage area.

GET /stac/collections List all collections

Returns a JSON array of all available STAC collections with their spatial and temporal extents.

GET /stac/collections/{collection_id} Single collection

Returns the full metadata record for one collection, including spatial extent (WGS84 bounding box), temporal extent, and available asset types.

Parameter	Type	Required	Description
collection_id	string	required	Collection identifier — see Collection Names below.

curl
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://odcube.landimage.info/stac/collections/sagris_s1_rtc_vh_img_europe

Items & Search #

Individual Sentinel-1 acquisitions are represented as STAC Items. Use the search endpoint to filter by bounding box, datetime range, and collection.

GET /stac/collections/{collection_id}/items List items in collection

Query param	Type		Description
bbox	string	optional	Comma-separated bounding box: `min_lon,min_lat,max_lon,max_lat` in WGS84.
datetime	string	optional	Single date or interval: `2024-03-01/2024-08-31`. ISO 8601.
limit	integer	optional	Page size. Default 10, max 500.
token	string	optional	Pagination cursor from previous response `context.next`.

POST /stac/search Cross-collection search

OGC-compliant STAC search across one or more collections. Accepts a JSON body.

Body field	Type		Description
collections	string[]	optional	Array of collection IDs to search. Omit to search all.
bbox	number[]	optional	`[min_lon, min_lat, max_lon, max_lat]`
datetime	string	optional	Date or interval string. ISO 8601.
intersects	GeoJSON	optional	GeoJSON geometry to intersect. Use instead of `bbox` for polygon queries.
limit	integer	optional	Max items to return. Default 10, max 500.

Example
                Python
                curl
              

              from pystac_client import Client

catalog = Client.open(
    "https://odcube.landimage.info/stac/",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
results = catalog.search(
    collections=["sagris_s1_rtc_vh_img_europe"],
    bbox=[23.5, 54.2, 26.0, 56.5],
    datetime="2024-04-01/2024-07-31",
    max_items=100
)
for item in results.items():
    print(item.id, item.datetime, item.assets["vh"].href)
              curl -s -X POST \
  https://odcube.landimage.info/stac/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": ["sagris_s1_rtc_vh_img_europe"],
    "bbox": [23.5, 54.2, 26.0, 56.5],
    "datetime": "2024-04-01/2024-07-31",
    "limit": 50
  }'
            

Assets & Downloads #

Each STAC Item contains asset links for the raster data file, a PNG thumbnail, and the source metadata. Assets are served as GeoTIFF files in EPSG:4326.

Asset key	Type	Description
vh	image/tiff	VH polarisation GeoTIFF, γ⁰ × 10³ DN, EPSG:4326, ~20m resolution.
vv	image/tiff	VV polarisation GeoTIFF, γ⁰ × 10³ DN, EPSG:4326, ~20m resolution.
thumbnail	image/png	256×256 PNG preview image, contrast-stretched.
metadata	application/yaml	EO3-compliant YAML dataset descriptor used for ODC ingestion.

ℹ️

Direct GeoTIFF access is available to Professional tier and above. Free tier accounts receive STAC metadata and thumbnail access only. Asset href URLs will return HTTP 403 for Free tier requests.

POST /api/timeseries #

The core analysis endpoint. Submit a GeoJSON polygon geometry and a date range; receive a per-acquisition time series of γ⁰ backscatter statistics aggregated over all pixels within the polygon. Available to all tiers.

POST /api/timeseries Backscatter time series

Request body (JSON)

Field	Type		Description
geometry	GeoJSON object	required	GeoJSON `Polygon` or `MultiPolygon` in WGS84 (EPSG:4326). Maximum area 50 km².
polarisation	string	required	`"VH"` or `"VV"`. Case-insensitive.
date_from	string	required	Start date, inclusive. ISO 8601: `"2024-03-01"`.
date_to	string	required	End date, inclusive. ISO 8601: `"2024-08-31"`.
stats	string[]	optional	Statistics to include. Default: `["mean","median","std","count"]`. Options: `mean`, `median`, `std`, `min`, `max`, `count`, `valid_pct`.

Request
                Python
                curl
                R
              

              import requests, pandas as pd

r = requests.post(
    "https://odcube.landimage.info/api/timeseries",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={
        "geometry": {
            "type": "Polygon",
            "coordinates": [[[24.10,54.68],[24.12,54.68],
                               [24.12,54.70],[24.10,54.70],
                               [24.10,54.68]]]
        },
        "polarisation": "VH",
        "date_from": "2024-03-01",
        "date_to":   "2024-08-31",
        "stats": ["mean", "std", "count"]
    }
)
df = pd.DataFrame(r.json()["results"])
df["date"] = pd.to_datetime(df["date"])
df["mean_linear"] = df["mean"] * 0.001  # DN → linear γ⁰
print(df.head())
              curl -s -X POST \
  https://odcube.landimage.info/api/timeseries \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "polarisation": "VH",
    "date_from": "2024-03-01",
    "date_to":   "2024-08-31",
    "stats": ["mean","std","count"],
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[24.10,54.68],[24.12,54.68],
                       [24.12,54.70],[24.10,54.70],
                       [24.10,54.68]]]
    }
  }' | python3 -m json.tool
              # install.packages(c("httr","jsonlite","dplyr"))
library(httr); library(jsonlite); library(dplyr)

body <- list(
  geometry = list(type="Polygon",
    coordinates=list(list(
      c(24.10,54.68),c(24.12,54.68),
      c(24.12,54.70),c(24.10,54.70),
      c(24.10,54.68)))),
  polarisation = "VH",
  date_from = "2024-03-01",
  date_to   = "2024-08-31"
)
resp <- POST(
  "https://odcube.landimage.info/api/timeseries",
  add_headers("X-Api-Key"="YOUR_API_KEY"),
  body=toJSON(body, auto_unbox=TRUE),
  content_type_json()
)
df <- as.data.frame(fromJSON(content(resp,"text"))$results)
            

Response Format #

The timeseries endpoint returns a JSON object with a results array — one entry per Sentinel-1 acquisition that intersects the geometry and date range.

Response · 200 OK

{
  "status":      "ok",
  "collection":  "sagris_s1_rtc_vh_img_europe",
  "polarisation":"VH",
  "pixel_size_m": 20,
  "units":       "γ⁰ × 10³ DN  (multiply by 0.001 → linear γ⁰)",
  "results": [
    {
      "date":       "2024-03-04",
      "mean":       312,
      "median":     298,
      "std":        87,
      "min":        42,
      "max":        1204,
      "count":      1847,
      "valid_pct":  98.4
    },
    // ... one object per acquisition date
  ]
}
        

Field	Type	Description
date	string	Acquisition date. ISO 8601 `YYYY-MM-DD`.
mean	integer	Mean γ⁰ × 10³ over all valid pixels in the polygon.
median	integer	Median γ⁰ × 10³.
std	integer	Standard deviation γ⁰ × 10³.
min / max	integer	Minimum and maximum pixel values within the polygon.
count	integer	Total number of valid pixels used in the aggregation.
valid_pct	float	Percentage of pixels with valid (non-nodata) values.

Collection Names #

Use these exact identifiers in STAC queries and API requests. Collections follow the naming convention sagris_s1_rtc_{polarisation}_img_{region}.

Collection ID	Polarisation	Coverage	Period
sagris_s1_rtc_vh_img_europe	VH	Europe (~6.5M km²)	2015 – present
sagris_s1_rtc_vv_img_europe	VV	Europe (~6.5M km²)	2015 – present

🔭

Planned collections. Africa and Middle East regional collections are in preparation and will follow the same naming convention with _africa and _mideast suffixes.

Rate Limits & Quotas #

API usage is throttled per API key according to the account tier. Exceeding limits returns HTTP 429 with a Retry-After header.

Tier	API requests / month	Images accessed / month	Max geometry area	Queue priority
Free	500	1,000	10 km²	Standard
Professional	10,000	25,000	50 km²	Priority
Enterprise	Unlimited	100,000+	200 km²	Dedicated pool
Institutional	Custom	Custom	Custom	Named contact

📊

Current usage and remaining quota are returned in every API response as HTTP headers: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes #

All errors return a JSON body with error and message fields alongside the HTTP status code.

HTTP Status	Error code	Description
400	invalid_geometry	GeoJSON is malformed or not a valid Polygon/MultiPolygon.
400	invalid_date_range	`date_from` is after `date_to`, or dates are outside 2015–present.
400	area_too_large	Polygon area exceeds the tier limit. Reduce geometry or upgrade tier.
401	missing_api_key	No `X-Api-Key` header or `api_key` query parameter provided.
401	invalid_api_key	Key does not exist or has been revoked.
403	asset_access_denied	Direct GeoTIFF asset access requires Professional tier or above.
429	rate_limit_exceeded	Monthly quota exhausted. Check `Retry-After` header or upgrade tier.
500	internal_error	Server-side processing error. Contact info@geomatrix.lt with the request ID from the response.

Error response example
{
  "status":    "error",
  "error":     "area_too_large",
  "message":   "Polygon area 78.3 km² exceeds the 50 km² limit for Professional tier.",
  "request_id":"req_a1b2c3d4"
}

Compatible Clients #

The STAC API is interoperable with all standard OGC and STAC-compatible clients.

Client	Type	How to connect
pystac-client	Python	`Client.open("https://odcube.landimage.info/stac/", headers={"X-Api-Key":"..."})`
QGIS 3.x	Desktop GIS	Plugins → STAC API Browser → New connection → URL: `https://odcube.landimage.info/stac/`, auth header.
ArcGIS Pro	Desktop GIS	Add STAC connection via Living Atlas → Custom STAC URL, set `X-Api-Key` in header settings.
GDAL / rasterio	Library	Use STAC item asset `href` directly with `GDAL_HTTP_HEADER_FILE` env var for auth.
Google Colab	Notebook	Use `requests` or `pystac-client` — no installation of GDAL/PROJ required for STAC metadata queries.
R (httr)	R	See R code example in the timeseries section above.

💬

Need help integrating?

Open a support request at info@geomatrix.lt — include your API key tier, language/client, and a minimal reproducible example. Professional and Institutional tier accounts receive priority support with a 48h response SLA.

SAGRIS ODC API Documentation