Copernicus EMS Rapid Mapping

This module provides access to Copernicus EMS Rapid Mapping emergency activation products. The Copernicus Emergency Management Service (CEMS) Rapid Mapping component publishes geospatial damage-assessment products for disasters (earthquakes, floods, wildfires, …). It is not storm-specific — the module works for any activation on the API.

Each activation (e.g. EMSR884, “Earthquake in Venezuela”) is divided into one or more AOIs (areas of interest), each carrying one or more products (First Estimate, Delineation, Grading/damage assessment, …). Every product is downloadable as a zip and also exposed as individual layers (GeoJSON / vector tiles / COG, each with an SLD style file). Access is via two public, unauthenticated JSON endpoints — no API key required.

Quick Start

Finding activations

import ocha_lens as lens

# All activations (one row per activation), or filter
df = lens.cems.get_activations()
quakes = lens.cems.get_activations(category="Earthquake", closed=False)
venezuela = lens.cems.get_activations(country="venezuela")

get_activations walks the paginated listing endpoint and returns a tidy table sorted newest-first. Filtering (category / closed / country) is applied client-side. Pass closed=False for the catalog of ongoing activations.

The product_type codes that appear in get_products/get_catalog (e.g. GRA) are described in the lens.cems.PRODUCT_TYPES dictionary — REF (reference), FEP (first estimate), DEL (delineation), GRA (grading/damage), GRM (ground movement). Map it onto a products table with products["product_type"].map(lens.cems.PRODUCT_TYPES).

Inspecting one activation

# Full nested detail tree (activation → AOIs → products → layers/stats)
act = lens.cems.get_activation("EMSR884")

# Flatten to tabular views (each accepts a code or the fetched dict)
products = lens.cems.get_products(act)   # one row per product (download targets)
catalog = lens.cems.get_catalog(act)     # one row per layer (geojson/sld URLs)
stats = lens.cems.get_stats(act)         # per-product damage-statistics table

get_activation returns the raw dict rather than a DataFrame because the hierarchy doesn’t flatten to a single table without losing the AOI/product/layer relationships. The three flatteners give the tabular views.

Downloading products (primary workflow)

# Every produced product for the activation, in memory ({filename: bytes})
zips = lens.cems.download_products("EMSR884")

# Filter by product type / AOI, and write to disk instead of memory
lens.cems.download_products(
    "EMSR884",
    product_types=["GRA"],   # grading / damage assessment only
    aoi_numbers=[0, 2],
    dest_dir="./emsr884",    # returns {filename: Path}
)

# A single product (from a get_products row, a product dict, or a URL)
row = products.iloc[0]
data = lens.cems.download_product(row)                  # bytes
path = lens.cems.download_product(row, dest="./out")    # Path

# The whole-activation bundle (one big zip of every product)
lens.cems.download_activation_bundle("EMSR884", dest="./emsr884.zip")

By default download_products skips products marked feasible=False (requested but not produced) and those with no published zip URL (logged at WARNING).

Working with individual layers

# Pull one layer's GeoJSON straight into a GeoDataFrame
geojson_layers = catalog[catalog["geojson_url"].notna()]
gdf = lens.cems.download_geojson(geojson_layers.iloc[0])

# Generic download primitive for anything (COG, SLD, …)
raw = lens.cems.download_file(url)              # bytes
path = lens.cems.download_file(url, dest="./")  # streamed to disk

Persisting to blob

# Push any downloaded bytes to the OCHA Azure blob store
data = lens.cems.download_product(row)
lens.cems.to_blob(data, "cems/EMSR884/grading.zip", stage="dev")

to_blob is a thin wrapper around ocha-stratus, imported lazily so it stays an optional dependency — the rest of the module works without it.

Notes

  • Host: the module targets rapidmapping.emergency.copernicus.eu. The mapping.emergency.copernicus.eu host that appears in some published OpenAPI specs 404s.

  • In-memory by default: every download returns bytes / GeoDataFrames unless you pass dest / dest_dir. Layer GeoJSONs can be large (tens of MB), so prefer streaming to disk for bulk work.

  • Mixed timestamp precision: the service mixes ISO8601 precisions within one activation (some timestamps carry microseconds, some don’t); they are parsed per-value rather than with a single inferred format.

  • Stats coercion: statistic totals/affected are coerced to float; the service’s placeholder strings (e.g. "NA") become null.

See the API reference for full function signatures.