IntelligenceService

GetCountryCoverage

GetCountryCoverage returns the country panel's visible coverage timeline: clustered news incidents reconciled against first-party structured records, with per-producer freshness so an empty list is never silent. PRO-gated. Requires an active Pro subscription.

get/api/intelligence/v1/get-country-coverage

Request

  • Base URL: https://api.worldmonitor.app
  • URL: https://api.worldmonitor.app/api/intelligence/v1/get-country-coverage
  • Auth: one of:
    • API key in header X-WorldMonitor-Key
    • API key in header X-Api-Key
    • HTTP bearer

Query parameters

country_codestring required

ISO 3166-1 alpha-2 country code.

window_hoursinteger

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.

limitinteger

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

jmespathstring

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

OK

countryCodestring

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

countryNamestring

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

windowHoursinteger

Window actually applied, in hours.

generatedAtstring

When this response was assembled, ISO-8601 UTC.

degradedboolean

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.

containmentstring

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.

Changes

No recorded changes to this operation across all 1 revision of this API.