Skip to main content
GET
GetCountryCoverage

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Query Parameters

country_code
string
required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$
window_hours
integer<int32>

Look-back window in hours. 0 or absent means the 168-hour (7-day) window the country panel uses. Values above 168 are rejected: the upstream coverage query itself is pinned to when:7d, so a longer window would silently return the same events under a wider label.

limit
integer<int32>

Maximum timeline events to return, newest last. 0 or absent means 200.

jmespath
string

Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.

Response

Successful response

GetCountryCoverageResponse is the country panel's visible coverage set.

countryCode
string

ISO 3166-1 alpha-2 code, echoed back uppercased.

countryName
string

Resolved country name, or the ISO code when no name is known.

windowHours
integer<int32>

Window actually applied, in hours.

generatedAt
string

When this response was assembled, ISO-8601 UTC.

headlines
object[]
events
object[]
sources
object[]
degraded
boolean

True when any producer is "stale" or "failed" — something is wrong now that was not wrong before. An agent must not read an empty events list as "nothing happened" while this is true.

Deliberately EXCLUDES "unavailable" and "unknown". Both are STRUCTURAL properties of this surface, true on every response regardless of upstream health: two producers have no server-side equivalent at all, and a producer that returns nothing globally cannot prove it was reached. Folding either in would pin this flag to true forever and destroy its signal.

This hides nothing: sources always carries every producer's own state, and that is where the "an empty list is never silently healthy" guarantee lives. Read sources before interpreting an empty events list, always.

containment
string

How a structured event was tested for being inside this country: "bbox" on this surface. The browser panel tests the loaded country polygon first and falls back to the same box, so a structured event inside the box but outside the polygon appears here and not in the panel. Coverage events are matched by headline text and are unaffected.