{ "openapi": "3.0.3", "info": { "title": "GDELT Cloud API v2", "version": "2.0.0", "description": "Clean v2 REST API for generated GDELT Cloud structured Events, clustered Stories, linked Entities, summaries, admin1 discovery, significance ranking, and paginated article evidence.\n\nEvent significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves. goldstein_scale is one canonical public metric, populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful. Story linked_event_count is a Story-to-Event link aggregate, not a distinct Event total." }, "servers": [ { "url": "https://gdeltcloud.com", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v2/events": { "get": { "operationId": "search-events-v2", "summary": "Search Events", "description": "Discrete events we code in-house from news coverage into a CAMEO+ / ACLED-aligned taxonomy. Each carries: the ACTORS on both sides (`actors`, with their countries and roles), geography down to admin-1 with a stated precision, the linked story and its source articles, a written rationale, and a set of METRICS — `significance` (the default sort, and the only one meant to compare events across domains), plus `magnitude`, `systemic_importance`, `propagation_potential` and `market_sensitivity`, each filterable with `_min` / `_max`. Goldstein and quad class are published where the taxonomy defines them. Metric values also carry `metrics.metric_inputs`: the sub-factor scores the coder read off the article, each with the reason it gave — so a score can be audited rather than trusted. Definitions: https://docs.gdeltcloud.com/reference/metrics\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `fatalities_min`, `fatalities_max`, `min_fatalities`, `max_fatalities`, `fatalities` → 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint. `fatalities` is also a CONFLICT-family observable — the CAMEO+ family has no such field and serves null — so a range filter would quietly exclude most of the corpus on top of that. Gate with `has_fatalities=true`, then threshold the `fatalities` field returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows, `/api/v2/events/summary` returns `fatalities` and `fatality_event_count` per bucket. Use instead: `has_fatalities=true`, `fatalities (response field — threshold client-side)`, `/api/v2/events/summary?group_by=country`.\n- `geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `quad_class` → 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.\n- `as_of` → 400 UNSUPPORTED_PARAM. Event metrics are computed live and are not vintaged, so as_of cannot return a reproducible point-in-time result here. Use observed_start / observed_end to bound by when an event was coded, or the Atlas (/api/v2/intelligence/*) and macro (/api/v2/macro/*) endpoints for true point-in-time reads. Use instead: `observed_start`, `observed_end`, `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`.\n\n", "tags": [ "Events" ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. Also accepts: `start_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "start_date" ] }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the window (YYYY-MM-DD). Also accepts: `end_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "end_date" ] }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 7 }, "description": "Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "7", "x-aliases": [ "window" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single-day anchor — equivalent to date_start = date_end = this value. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04" }, { "name": "observed_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. Also accepts: `observedStart`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "observedStart" ] }, { "name": "observed_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Upper bound on the coded-at window. Also accepts: `observedEnd`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "observedEnd" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Rows per page. Default 25, max 100. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor taken from the previous response's `pagination.next_cursor`. Also accepts: `offset`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25", "x-aliases": [ "offset" ] }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set `country_match` to narrow it to location only. The definition in force is echoed as `applied_filters.country_match`. Also accepts: `country_iso3`. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#country", "example": "UKR,RUS", "x-aliases": [ "country_iso3" ] }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "One ACLED-style region. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region", "example": "Middle East" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "One continent. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent", "example": "Europe" }, { "name": "country_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "location_or_actor_origin", "location" ], "default": "location_or_actor_origin" }, "description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Defaults to the wider one, which is why omitting it changes nothing. Applies to `region` and `continent` too, since both expand into the same country set. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match", "example": "location" }, { "name": "admin1", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#admin1", "example": "Kharkivska Oblast" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box `lat_min,lon_min,lat_max,lon_max`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "11,41,16,45" }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Point proximity `lat,lon`, combined with `radius_km`. Applied as the enclosing bounding box, not a true distance filter — results are a deliberate superset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "31.05,111.00" }, { "name": "lat", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Point proximity component (`lat`), an alternative spelling of `near`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "31.05" }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Point proximity component (`lon`), an alternative spelling of `near`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "31.05" }, { "name": "lng", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Point proximity component (`lng`), an alternative spelling of `near`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "31.05" }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for point proximity. Default 100, capped 2000. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "100" }, { "name": "source_actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of the ACTING side. Combine with `target_actor_country` to express a direction — `source_actor_country=CHN&target_actor_country=USA,GBR` is \"China acting on those countries\", which `country=` cannot say. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "CHN" }, { "name": "target_actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of the RECEIVING side — the actor the action was directed at. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "USA,GBR,FRA" }, { "name": "actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of EITHER side, without regard to direction. This is the actor-origin half of what `country=` matches, on its own — use it to exclude events that merely happened in a country without any actor from it. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "CHN" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict to one entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Also accepts: `entity_id`, `entities`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle", "example": "e_0576e79c82962452", "x-aliases": [ "entity_id", "entities" ] }, { "name": "entity_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "material", "actor", "coverage" ], "default": "material" }, "description": "Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match", "example": "material" }, { "name": "category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with `subcategory`: an impossible pair returns 400, never an empty 200. Also accepts: `categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "categories" ] }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by `category` — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (`Sexual violence` is the measured example: its definition boundary sends nearly all such reporting to `Attack`). Before building a monitor on one code, measure it: `GET /api/v2/events/summary?group_by=subcategory` returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete", "example": "Peaceful protest" }, { "name": "significance_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Significance lower bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#significance", "example": "0" }, { "name": "significance_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Significance upper bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#significance", "example": "1" }, { "name": "confidence_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Confidence lower bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence", "example": "0" }, { "name": "confidence_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Confidence upper bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence", "example": "1" }, { "name": "goldstein_scale_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": -10, "maximum": 10 }, "description": "Goldstein scale lower bound (-10–10). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale", "example": "-10" }, { "name": "goldstein_scale_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": -10, "maximum": 10 }, "description": "Goldstein scale upper bound (-10–10). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale", "example": "10" }, { "name": "magnitude_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 10 }, "description": "Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude", "example": "0" }, { "name": "magnitude_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 10 }, "description": "Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude", "example": "10" }, { "name": "systemic_importance_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance", "example": "0" }, { "name": "systemic_importance_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance", "example": "1" }, { "name": "propagation_potential_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential", "example": "0" }, { "name": "propagation_potential_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential", "example": "1" }, { "name": "market_sensitivity_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity", "example": "0" }, { "name": "market_sensitivity_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity", "example": "1" }, { "name": "geo_precision_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 3 }, "description": "Geo precision lower bound (1–3). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision", "example": "1" }, { "name": "geo_precision_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 3 }, "description": "Geo precision upper bound (1–3). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision", "example": "3" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Semantic search — the string is embedded and ranked by cosine similarity, so results are conceptual neighbours rather than substring matches. There is no boolean parser: a query shaped `a OR b` is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. Aliases `q`, `query`, `keyword`. Also accepts: `q`, `query`, `keyword`, `name`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "power grid blackout", "x-aliases": [ "q", "query", "keyword", "name" ] }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "significance", "recent" ], "default": "significance" }, "description": "Ranking. A bare `search` with no explicit sort ranks by relevance instead. Full value list: https://docs.gdeltcloud.com/reference/enums#sort", "example": "significance" }, { "name": "incident_resolution", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "unadjudicated", "self", "llm" ] } }, "description": "Restrict to events by whether they were checked for duplication. Comma-separated. Adjudication is deliberately partial, so `llm,self` is how you get the subset where `incident.uid` is a trustworthy grouping key; omitting the filter returns everything, most of which is `unadjudicated`. Also accepts: `incident_resolutions`. Full value list: https://docs.gdeltcloud.com/reference/enums#incident_resolution", "example": "llm,self", "x-aliases": [ "incident_resolutions" ] }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Add `pagination.estimated_total` — how many events match the filters, ignoring the page. Off by default because it costs a second scan of the same window. Counted from the SAME filters and the same row source as the page, so it always describes the result set you are walking. It is `null` (not a number) on a `search=` request: semantic retrieval is bounded by a candidate cap, so any total there would describe the candidate pool rather than the matching events. Without it, `pagination.next_cursor` still tells you whether more rows exist — non-null means yes, null means the walk is finished.", "example": "true" }, { "name": "has_fatalities", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to events with a non-zero fatality count. CONFLICT FAMILY ONLY. `fatalities` is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry `fatalities: null` (never a fabricated 0) and can never satisfy `true`. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. `false` is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means \"not known to be lethal\", never \"known to be non-lethal\". For a lethality screen across all families use `significance_min` (cross-domain by construction) or `goldstein_scale_max` — Goldstein is signed, so an upper bound like `goldstein_scale_max=-5` selects the strongly conflictual end — and read `fatalities` off the card to tell a measured 0 from an absent observable. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "civilian_targeting", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to events coded as targeting civilians. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Source-language filter (ISO 639-1/2) on the linked Story's coverage. Also accepts: `language`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language", "example": "en,fr", "x-aliases": [ "language" ] }, { "name": "include_images", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Attach story images to each card. Off by default — images cost an extra lookup, so pass `true` to opt in. Also accepts: `include_entity_images`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true", "x-aliases": [ "include_entity_images" ] }, { "name": "collapse_duplicates", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Fold Events adjudicated as the same real-world incident. Off by default for compatibility; Alerts enable it by default. Unadjudicated Events remain distinct. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "event_family", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conflict", "cameoplus" ] }, "description": "Deprecated. Prefer `category`, which implies the family. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#event_family", "example": "conflict", "deprecated": true }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] }, "description": "Deprecated CAMEO+ domain filter. Prefer `category`. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#cameoplus_domain", "example": "ECONOMIC", "deprecated": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Event cards", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventCard" } }, "sort": { "$ref": "#/components/schemas/Sort" }, "meta": { "$ref": "#/components/schemas/ListResponseMeta" } } } ] }, "examples": { "events": { "value": { "success": true, "data": [ { "id": "conflict_13e29fd7", "url": "https://gdeltcloud.com/story/example-story", "primary_story_url": "https://gdeltcloud.com/story/example-story", "family": "conflict", "title": "Attack in Delft", "summary": "A conflict Event coded from linked source articles.", "event_date": "2026-04-15", "category": "Violence against civilians", "subcategory": "Attack", "domain": "CONFLICT", "event_code": "conflict_13e29fd7", "geo": { "country": "South Africa", "region": "Southern Africa", "continent": "Africa", "admin1": "Western Cape", "location": "Delft", "latitude": -33.955, "longitude": 18.634 }, "actors": [ { "name": "Unknown armed actor", "country": null, "role": "actor1" } ], "metrics": { "significance": 0.3585, "goldstein_scale": -7, "magnitude": null, "systemic_importance": null, "propagation_potential": null, "market_sensitivity": null, "confidence": 0.82, "article_count": 1 }, "has_fatalities": true, "fatalities": 4, "story_refs": [ { "id": "story_123", "url": "https://gdeltcloud.com/story/example-story", "title": "Delft mass shooting coverage", "story_date": "2026-04-15", "article_count": 1 } ], "entity_refs": [], "top_articles": [ { "url": "https://www.example.com/delft-mass-shooting", "title": "Delft mass shooting: child among 4 killed", "domain": "example.com", "rank": 1 } ] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "eyJvZmZzZXQiOjI1fQ==" }, "sort": "significance" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v2/events/{event_id}": { "get": { "operationId": "get-event-v2", "summary": "Get Event", "description": "Fetch one known structured Event by ID.", "tags": [ "Events" ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "Event ID returned by Search Events, for example `conflict_...` or `cameoplus_...`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EventCard" } } }, "examples": { "event": { "value": { "success": true, "data": { "id": "conflict_13e29fd7", "url": "https://gdeltcloud.com/story/example-story", "primary_story_url": "https://gdeltcloud.com/story/example-story", "family": "conflict", "title": "Attack in Delft", "summary": "A conflict Event coded from linked source articles.", "event_date": "2026-04-15", "category": "Violence against civilians", "subcategory": "Attack", "domain": "CONFLICT", "event_code": "conflict_13e29fd7", "geo": { "country": "South Africa", "region": "Southern Africa", "continent": "Africa", "admin1": "Western Cape", "location": "Delft", "latitude": -33.955, "longitude": 18.634 }, "actors": [ { "name": "Unknown armed actor", "country": null, "role": "actor1" } ], "metrics": { "significance": 0.3585, "goldstein_scale": -7, "magnitude": null, "systemic_importance": null, "propagation_potential": null, "market_sensitivity": null, "confidence": 0.82, "article_count": 1 }, "has_fatalities": true, "fatalities": 4, "story_refs": [ { "id": "story_123", "url": "https://gdeltcloud.com/story/example-story", "title": "Delft mass shooting coverage", "story_date": "2026-04-15", "article_count": 1 } ], "entity_refs": [], "top_articles": [ { "url": "https://www.example.com/delft-mass-shooting", "title": "Delft mass shooting: child among 4 killed", "domain": "example.com", "rank": 1 } ] } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/events/conflict_13e29fd7\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/events/{event_id}/stories": { "get": { "operationId": "get-event-stories-v2", "summary": "Get Event Stories", "description": "The live story cluster(s) this Event belongs to. Reads the Event→Story links (including `rehomed` links produced by orphan reconnection) joined to the latest, non-superseded story clusters, so a merged-away story is never returned. Usually one story (the canonical); a reconnected Event also carries its re-homed story; a multi-cluster Event lists each live story that covered it. `relation` is `reconnected` when the Event was re-homed to this story after its original cluster merged away, otherwise `primary`.", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "description": "Event ID returned by Search Events, for example `conflict_...` or `cameoplus_...`.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "description": "Optional ISO date (YYYY-MM-DD) lower bound. Defaults to the Event's own date window.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "description": "Optional ISO date (YYYY-MM-DD) upper bound. Defaults to the Event's own date window.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Live stories for the Event", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Story (cluster) id." }, "url": { "type": "string", "description": "Public story URL." }, "title": { "type": "string", "nullable": true, "description": "Story headline (label)." }, "story_date": { "type": "string", "format": "date" }, "article_count": { "type": "integer", "description": "Live article count of the story." }, "relation": { "type": "string", "enum": [ "primary", "reconnected" ], "description": "`reconnected` = the Event was re-homed here after its original cluster merged away; else `primary`." } } } } } }, "examples": { "stories": { "value": { "success": true, "data": [ { "id": "9ae8e929c096", "url": "https://gdeltcloud.com/stories/ndrangheta-assets-seized-9ae8e929", "title": "Ndrangheta: assets worth €2.7 million seized from Reggio Calabria businessman", "story_date": "2026-07-08", "article_count": 3, "relation": "reconnected" } ] } } } } } } } } }, "/api/v2/events/summary": { "get": { "operationId": "summarize-events-v2", "summary": "Summarize Events", "description": "Aggregate counts and metric statistics over the same Events `/api/v2/events` returns, grouped by date, country, region, continent, category or subcategory. Accepts every filter the list accepts, so a summary and a list of the same window are directly reconcilable. Metric averages are means over the rows where that metric is present, not over `event_count` — family-scoped metrics are genuinely absent on the other family.\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `search` → 400 UNSUPPORTED_FILTER. search is only supported on list/search endpoints. Use /api/v2/events for semantic Event retrieval, then summarize with structured filters. Use instead: `/api/v2/events`.\n- `sort` → 400 UNSUPPORTED_PARAM. sort orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead: `/api/v2/events`, `limit`.\n- `cursor` → 400 UNSUPPORTED_PARAM. cursor orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead: `/api/v2/events`, `limit`.\n- `offset` → 400 UNSUPPORTED_PARAM. offset orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/events to walk the underlying rows. Use instead: `/api/v2/events`, `limit`.\n- `include_images` → 400 UNSUPPORTED_PARAM. include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images. Use instead: `/api/v2/events`.\n- `include_entity_images` → 400 UNSUPPORTED_PARAM. include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/events for rows with images. Use instead: `/api/v2/events`.\n- `geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `quad_class` → 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/quad_class selectors.\n- `as_of` → 400 UNSUPPORTED_PARAM. Event metrics are computed live and are not vintaged, so as_of cannot return a reproducible point-in-time result here. Use observed_start / observed_end to bound by when an event was coded, or the Atlas (/api/v2/intelligence/*) and macro (/api/v2/macro/*) endpoints for true point-in-time reads. Use instead: `observed_start`, `observed_end`, `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`.\n\n", "tags": [ "Events" ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. Also accepts: `start_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "start_date" ] }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the window (YYYY-MM-DD). Also accepts: `end_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "end_date" ] }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 7 }, "description": "Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "7", "x-aliases": [ "window" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single-day anchor — equivalent to date_start = date_end = this value. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04" }, { "name": "observed_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. Also accepts: `observedStart`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "observedStart" ] }, { "name": "observed_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Upper bound on the coded-at window. Also accepts: `observedEnd`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "observedEnd" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Maximum number of BUCKETS returned (not rows). Default 50, max 500. There is no cursor on this endpoint, so a result at the limit may be truncated — widen the limit or narrow the window. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "50" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "date", "country", "region", "continent", "category", "subcategory", "source_actor_country", "target_actor_country" ], "default": "date" }, "description": "The dimension to aggregate over. Every dimension reconciles to the same total. Full value list: https://docs.gdeltcloud.com/reference/enums#event_group_by", "example": "date" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set `country_match` to narrow it to location only. The definition in force is echoed as `applied_filters.country_match`. Also accepts: `country_iso3`. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#country", "example": "UKR,RUS", "x-aliases": [ "country_iso3" ] }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "One ACLED-style region. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region", "example": "Middle East" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "One continent. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent", "example": "Europe" }, { "name": "country_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "location_or_actor_origin", "location" ], "default": "location_or_actor_origin" }, "description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Defaults to the wider one, which is why omitting it changes nothing. Applies to `region` and `continent` too, since both expand into the same country set. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match", "example": "location" }, { "name": "admin1", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#admin1", "example": "Kharkivska Oblast" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box `lat_min,lon_min,lat_max,lon_max`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "11,41,16,45" }, { "name": "source_actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of the ACTING side. Combine with `target_actor_country` to express a direction — `source_actor_country=CHN&target_actor_country=USA,GBR` is \"China acting on those countries\", which `country=` cannot say. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "CHN" }, { "name": "target_actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of the RECEIVING side — the actor the action was directed at. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "USA,GBR,FRA" }, { "name": "actor_country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin country of EITHER side, without regard to direction. This is the actor-origin half of what `country=` matches, on its own — use it to exclude events that merely happened in a country without any actor from it. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike `country`, `region` and `continent` do not expand onto the actor side. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "CHN" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict to one entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Also accepts: `entity_id`, `entities`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle", "example": "e_0576e79c82962452", "x-aliases": [ "entity_id", "entities" ] }, { "name": "entity_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "material", "actor", "coverage" ], "default": "material" }, "description": "Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match", "example": "material" }, { "name": "category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with `subcategory`: an impossible pair returns 400, never an empty 200. Also accepts: `categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "categories" ] }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by `category` — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (`Sexual violence` is the measured example: its definition boundary sends nearly all such reporting to `Attack`). Before building a monitor on one code, measure it: `GET /api/v2/events/summary?group_by=subcategory` returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete", "example": "Peaceful protest" }, { "name": "significance_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Significance lower bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#significance", "example": "0" }, { "name": "significance_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Significance upper bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#significance", "example": "1" }, { "name": "confidence_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Confidence lower bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence", "example": "0" }, { "name": "confidence_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Confidence upper bound (0–1). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#confidence", "example": "1" }, { "name": "goldstein_scale_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": -10, "maximum": 10 }, "description": "Goldstein scale lower bound (-10–10). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale", "example": "-10" }, { "name": "goldstein_scale_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": -10, "maximum": 10 }, "description": "Goldstein scale upper bound (-10–10). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#goldstein_scale", "example": "10" }, { "name": "magnitude_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 10 }, "description": "Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude", "example": "0" }, { "name": "magnitude_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 10 }, "description": "Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/magnitude", "example": "10" }, { "name": "systemic_importance_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance", "example": "0" }, { "name": "systemic_importance_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/systemic-importance", "example": "1" }, { "name": "propagation_potential_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential", "example": "0" }, { "name": "propagation_potential_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/propagation-potential", "example": "1" }, { "name": "market_sensitivity_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity", "example": "0" }, { "name": "market_sensitivity_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics/market-sensitivity", "example": "1" }, { "name": "geo_precision_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 3 }, "description": "Geo precision lower bound (1–3). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision", "example": "1" }, { "name": "geo_precision_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 3 }, "description": "Geo precision upper bound (1–3). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/metrics#geo_precision", "example": "3" }, { "name": "has_fatalities", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to events with a non-zero fatality count. CONFLICT FAMILY ONLY. `fatalities` is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry `fatalities: null` (never a fabricated 0) and can never satisfy `true`. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. `false` is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means \"not known to be lethal\", never \"known to be non-lethal\". For a lethality screen across all families use `significance_min` (cross-domain by construction) or `goldstein_scale_max` — Goldstein is signed, so an upper bound like `goldstein_scale_max=-5` selects the strongly conflictual end — and read `fatalities` off the card to tell a measured 0 from an absent observable. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "civilian_targeting", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to events coded as targeting civilians. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "incident_resolution", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "unadjudicated", "self", "llm" ] } }, "description": "Restrict to events by whether they were checked for duplication. Comma-separated. Adjudication is deliberately partial, so `llm,self` is how you get the subset where `incident.uid` is a trustworthy grouping key; omitting the filter returns everything, most of which is `unadjudicated`. Also accepts: `incident_resolutions`. Full value list: https://docs.gdeltcloud.com/reference/enums#incident_resolution", "example": "llm,self", "x-aliases": [ "incident_resolutions" ] }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Coverage-language filter (ISO 639-1/2) on the underlying articles. Also accepts: `language`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language", "example": "en,zh", "x-aliases": [ "language" ] }, { "name": "event_family", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conflict", "cameoplus" ] }, "description": "Deprecated. Prefer `category`, which implies the family. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#event_family", "example": "conflict", "deprecated": true }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] }, "description": "Deprecated CAMEO+ domain filter. Prefer `category`. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#cameoplus_domain", "example": "ECONOMIC", "deprecated": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Event summary buckets", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventSummaryBucket" } } } }, "examples": { "summary": { "value": { "success": true, "group_by": "date", "data": [ { "key": "2026-04-15", "group_by": "date", "event_count": 12, "conflict_event_count": 7, "cameoplus_event_count": 5, "fatality_event_count": 2, "fatality_event_rate": 0.167, "fatalities": 6, "article_count": 38, "avg_article_count": 3.17, "max_article_count": 9, "avg_significance": 0.42, "max_significance": 0.86, "min_significance": 0.12, "avg_goldstein_scale": -3.8, "min_goldstein_scale": -9.5, "max_goldstein_scale": 3.4, "avg_goldstein_severity": 4.1, "avg_magnitude": 0.44, "avg_systemic_importance": 0.36, "avg_propagation_potential": 0.31, "avg_market_sensitivity": 0.18, "avg_confidence": 0.74, "metrics": { "significance": { "avg": 0.42, "max": 0.86, "min": 0.12 }, "goldstein_scale": { "avg": -3.8, "min": -9.5, "max": 3.4, "avg_severity": 4.1 }, "cameoplus": { "magnitude": { "avg": 0.44, "max": 0.72 }, "systemic_importance": { "avg": 0.36, "max": 0.68 }, "propagation_potential": { "avg": 0.31, "max": 0.59 }, "market_sensitivity": { "avg": 0.18, "max": 0.41 } }, "confidence": { "avg": 0.74, "max": 0.91 }, "article_count": { "total": 38, "avg": 3.17, "max": 9 }, "fatalities": { "events": 2, "rate": 0.167, "total": 6 } }, "metric_stats": { "significance": { "avg": 0.42, "max": 0.86, "min": 0.12 } } } ] } } } } } } } } }, "/api/v2/stories": { "get": { "operationId": "search-stories-v2", "summary": "Search Stories", "description": "Deduplicated news Stories — clusters of articles about the same real-world development, built by us from the articles themselves. Each carries the source articles behind it, article and outlet counts, the coverage languages it appeared in, the entities it mentions, and the Events coded from it. One story can yield several events. `related=true` attaches adjacent clusters; `collapse_duplicates` folds same-incident stories an adjudicator has merged — it changes result cardinality, so it changes paging. `matched_categories` reports which of your taxonomy filters each story actually matched, which is the fastest way to see why a result came back.\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `fatalities_min`, `fatalities_max`, `min_fatalities`, `max_fatalities`, `fatalities` → 400 UNSUPPORTED_FILTER. Fatality RANGE filters are not implemented on this endpoint. `fatalities` is also a CONFLICT-family observable — the CAMEO+ family has no such field and serves null — so a range filter would quietly exclude most of the corpus on top of that. Gate with `has_fatalities=true`, then threshold the `fatalities` field returned on each card — client-side keeps the null-vs-zero distinction a server-side range filter would destroy. For tolls rather than rows, `/api/v2/stories/summary` returns `fatalities` and `fatality_event_count` per bucket. Use instead: `has_fatalities=true`, `fatalities (response field — threshold client-side)`, `/api/v2/stories/summary?group_by=country`.\n- `geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `total_events` → 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/total_events selectors.\n\n", "tags": [ "Stories" ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. Also accepts: `start_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "start_date" ] }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the window (YYYY-MM-DD). Also accepts: `end_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "end_date" ] }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 7 }, "description": "Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "7", "x-aliases": [ "window" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single-day anchor — equivalent to date_start = date_end = this value. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04" }, { "name": "observed_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. Also accepts: `observedStart`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "observedStart" ] }, { "name": "observed_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Upper bound on the coded-at window. Also accepts: `observedEnd`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "observedEnd" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Rows per page. Default 25, max 100. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor taken from the previous response's `pagination.next_cursor`. Also accepts: `offset`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25", "x-aliases": [ "offset" ] }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set `country_match` to narrow it to location only. The definition in force is echoed as `applied_filters.country_match`. A Story also matches on its OWN attributed country, so Stories with no coded Event are reachable — over 2026-08-14..16 that took the reachable set from 5,386 to 24,207 of 25,463 Stories. Combining `country` with an Event-scoped filter (`event_category`, `subcategory`, `admin1`, `bbox`, `domain`, `civilian_targeting`) keeps the Event-only definition, because those ask about the Story's Events. Attribution begins 2026-07; earlier windows are Event-derived only. Also accepts: `country_iso3`. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#country", "example": "UKR,RUS", "x-aliases": [ "country_iso3" ] }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "One ACLED-style region. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region", "example": "Middle East" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "One continent. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent", "example": "Europe" }, { "name": "country_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "location_or_actor_origin", "location" ], "default": "location_or_actor_origin" }, "description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Defaults to the wider one, which is why omitting it changes nothing. Applies to `region` and `continent` too, since both expand into the same country set. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match", "example": "location" }, { "name": "admin1", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#admin1", "example": "Kharkivska Oblast" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box `lat_min,lon_min,lat_max,lon_max`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "11,41,16,45" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict to one entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Also accepts: `entity_id`, `entities`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle", "example": "e_0576e79c82962452", "x-aliases": [ "entity_id", "entities" ] }, { "name": "entity_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "material", "actor", "coverage" ], "default": "material" }, "description": "Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match", "example": "material" }, { "name": "category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with `subcategory`: an impossible pair returns 400, never an empty 200. Also accepts: `categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "categories" ] }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by `category` — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (`Sexual violence` is the measured example: its definition boundary sends nearly all such reporting to `Attack`). Before building a monitor on one code, measure it: `GET /api/v2/events/summary?group_by=subcategory` returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete", "example": "Peaceful protest" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Semantic search — the string is embedded and ranked by cosine similarity, so results are conceptual neighbours rather than substring matches. There is no boolean parser: a query shaped `a OR b` is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. Aliases `q`, `query`, `keyword`. Also accepts: `q`, `query`, `keyword`, `name`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "power grid blackout", "x-aliases": [ "q", "query", "keyword", "name" ] }, { "name": "story_category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conflict_security", "cameoplus_political", "cameoplus_crime", "cameoplus_economic", "cameoplus_corporate", "cameoplus_technology", "cameoplus_infrastructure", "cameoplus_environment", "cameoplus_health", "cameoplus_demographic", "cameoplus_information", "CONFLICT", "CORPORATE", "CRIME", "DEMOGRAPHIC", "ECONOMIC", "ENVIRONMENT", "HEALTH", "INFORMATION", "INFRASTRUCTURE", "POLITICAL", "TECHNOLOGY" ] }, "description": "Story-level category. Full value list: https://docs.gdeltcloud.com/reference/enums#story_category", "example": "conflict_security" }, { "name": "event_category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Legacy alias for `category` on Stories. Merges with `category` into one union filter. Also accepts: `event_categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "event_categories" ] }, { "name": "has_events", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories that have (or have not) linked Events. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "has_fatalities", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories whose linked Events carry fatalities. CONFLICT FAMILY ONLY. `fatalities` is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry `fatalities: null` (never a fabricated 0) and can never satisfy `true`. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. `false` is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means \"not known to be lethal\", never \"known to be non-lethal\". Stories publish no metric filters, so for a cross-family severity screen query `/api/v2/events` — which does — and follow `story_refs` back. Read `fatalities` off each linked event to tell a measured 0 from an absent observable. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "civilian_targeting", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories whose linked Events target civilians. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "article_count_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Minimum article count. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "5" }, { "name": "article_count_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Maximum article count. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "20" }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Coverage-language filter (ISO 639-1/2). Also accepts: `language`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language", "example": "en,zh", "x-aliases": [ "language" ] }, { "name": "include_images", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Attach story images. Off by default — images cost an extra lookup, so pass `true` to opt in. Also accepts: `include_entity_images`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true", "x-aliases": [ "include_entity_images" ] }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "significance", "recent" ], "default": "significance" }, "description": "Ranking. Full value list: https://docs.gdeltcloud.com/reference/enums#sort", "example": "significance" }, { "name": "related", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Attach related Stories (schema 130). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "collapse_duplicates", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Collapse near-duplicate Stories. On by default for compatibility; pass `false` for the stable raw Story-id walk. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "event_family", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conflict", "cameoplus" ] }, "description": "Deprecated. Prefer `category`, which implies the family. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#event_family", "example": "conflict", "deprecated": true }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] }, "description": "Deprecated CAMEO+ domain filter. Prefer `category`. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#cameoplus_domain", "example": "ECONOMIC", "deprecated": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Story cards", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoryCard" } }, "sort": { "$ref": "#/components/schemas/Sort" } } } ] }, "examples": { "stories": { "value": { "success": true, "data": [ { "id": "story_123", "url": "https://gdeltcloud.com/story/example-story", "title": "Data center projects in Asia", "story_date": "2026-04-15", "category": "infrastructure", "subcategory": null, "geo": { "country": "Japan", "region": "Eastern Asia", "continent": "Asia", "admin1": "Tokyo", "location": "Tokyo", "latitude": 35.6762, "longitude": 139.6503 }, "metrics": { "significance": 0.82, "article_count": 12, "linked_event_count": 2, "max_linked_event_significance": 0.71 }, "has_events": true, "has_fatalities": false, "fatalities": 0, "linked_events": [ { "id": "cameoplus_abc123", "title": "Infrastructure investment announced" } ], "entity_refs": [], "top_articles": [ { "url": "https://www.example.com/data-center", "title": "New data center project announced", "domain": "example.com", "rank": 1 } ] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "eyJvZmZzZXQiOjI1fQ==" }, "sort": "significance" } } } } } } } } }, "/api/v2/stories/{story_id}": { "get": { "operationId": "get-story-v2", "summary": "Get Story", "description": "Fetch one known Story by ID with linked Events, linked Entities, metrics, public URL, normalized geo, and top 3 inline articles.", "tags": [ "Stories" ], "parameters": [ { "name": "story_id", "in": "path", "required": true, "description": "Story ID returned by Search Stories or linked from an Event.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Story detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/StoryCard" } } }, "examples": { "story": { "value": { "success": true, "data": { "id": "story_123", "url": "https://gdeltcloud.com/story/example-story", "title": "Data center projects in Asia", "story_date": "2026-04-15", "category": "infrastructure", "subcategory": null, "geo": { "country": "Japan", "region": "Eastern Asia", "continent": "Asia", "admin1": "Tokyo", "location": "Tokyo", "latitude": 35.6762, "longitude": 139.6503 }, "metrics": { "significance": 0.82, "article_count": 12, "linked_event_count": 2, "max_linked_event_significance": 0.71 }, "has_events": true, "has_fatalities": false, "fatalities": 0, "linked_events": [ { "id": "cameoplus_abc123", "title": "Infrastructure investment announced" } ], "entity_refs": [], "top_articles": [ { "url": "https://www.example.com/data-center", "title": "New data center project announced", "domain": "example.com", "rank": 1 } ] } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/stories/story_123\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/stories/{story_id}/articles": { "get": { "operationId": "get-story-articles-v2", "summary": "Get Story Articles", "description": "Canonical-URL-deduplicated article evidence with source language and provenance-backed publisher country.", "tags": [ "Stories" ], "parameters": [ { "name": "story_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The story id." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "First Story partition date. `date_start` is an alias. Also accepts: `date_start`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20", "x-aliases": [ "date_start" ] }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Last Story partition date. `date_end` is an alias. Also accepts: `date_end`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20", "x-aliases": [ "date_end" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single Story partition date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 14 }, "description": "Trailing date window. `window` is an alias. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "14", "x-aliases": [ "window" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum articles returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Legacy numeric offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0" }, { "name": "include_images", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Attach resolved article images. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origin language filter. `languages` is an alias. Also accepts: `languages`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "en,fr", "x-aliases": [ "languages" ] }, { "name": "publisher_country_iso3", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Known publisher-country filter. `publisher_country` is an alias; unknown publishers are never guessed. Also accepts: `publisher_country`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "GBR", "x-aliases": [ "publisher_country" ] } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Paginated source articles", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } } ] }, "examples": { "articles": { "value": { "success": true, "data": [ { "url": "https://www.example.com/data-center", "title": "New data center project announced", "domain": "example.com", "rank": 1 } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "eyJvZmZzZXQiOjI1fQ==" } } } } } } } } } }, "/api/v2/stories/summary": { "get": { "operationId": "summarize-stories-v2", "summary": "Summarize Stories", "description": "Aggregate counts and statistics over the same Stories `/api/v2/stories` returns, grouped by date, country, region, continent, category or subcategory. Event-scoped filters are applied inside the linked-event rollup, so a story's counts reflect the events that matched your filters rather than its total.\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `event_family` → 400 UNSUPPORTED_PARAM. event_family is not supported on the Stories summary — a Story is not scoped to one event family. Filter the linked events with event_category, or use /api/v2/events/summary. Use instead: `event_category`, `/api/v2/events/summary`.\n- `search` → 400 UNSUPPORTED_FILTER. search is only supported on list/search endpoints. Use /api/v2/stories for semantic Story retrieval, then summarize with structured filters. Use instead: `/api/v2/stories`.\n- `sort` → 400 UNSUPPORTED_PARAM. sort orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead: `/api/v2/stories`, `limit`.\n- `cursor` → 400 UNSUPPORTED_PARAM. cursor orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead: `/api/v2/stories`, `limit`.\n- `offset` → 400 UNSUPPORTED_PARAM. offset orders or pages ROWS, and a summary returns buckets. Use `limit` to bound the number of buckets, or /api/v2/stories to walk the underlying rows. Use instead: `/api/v2/stories`, `limit`.\n- `include_images` → 400 UNSUPPORTED_PARAM. include_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images. Use instead: `/api/v2/stories`.\n- `include_entity_images` → 400 UNSUPPORTED_PARAM. include_entity_images attaches images to ROWS, and a summary returns buckets. Use /api/v2/stories for rows with images. Use instead: `/api/v2/stories`.\n- `geo_scope`, `scope`, `detail`, `event_readiness`, `cluster_certainty`, `total_events` → 400 UNSUPPORTED_FILTER. This v2 endpoint does not support scope/detail/readiness/certainty/total_events selectors.\n\n", "tags": [ "Stories" ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the window (YYYY-MM-DD). Windows are capped at 30 days. Also accepts: `start_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "start_date" ] }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the window (YYYY-MM-DD). Also accepts: `end_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "end_date" ] }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 7 }, "description": "Rolling window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "7", "x-aliases": [ "window" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single-day anchor — equivalent to date_start = date_end = this value. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04" }, { "name": "observed_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Bound by when an event was CODED rather than when it happened. The supported point-in-time lever on this endpoint. Also accepts: `observedStart`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "observedStart" ] }, { "name": "observed_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Upper bound on the coded-at window. Also accepts: `observedEnd`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "observedEnd" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Maximum number of BUCKETS returned (not rows). Default 50, max 500. There is no cursor on this endpoint, so a result at the limit may be truncated — widen the limit or narrow the window. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "50" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "date", "country", "region", "continent", "category", "subcategory" ], "default": "date" }, "description": "The dimension to aggregate over. Every dimension reconciles to the same total. Full value list: https://docs.gdeltcloud.com/reference/enums#story_group_by", "example": "date" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set `country_match` to narrow it to location only. The definition in force is echoed as `applied_filters.country_match`. A Story also matches on its OWN attributed country, so Stories with no coded Event are reachable — over 2026-08-14..16 that took the reachable set from 5,386 to 24,207 of 25,463 Stories. Combining `country` with an Event-scoped filter (`event_category`, `subcategory`, `admin1`, `bbox`, `domain`, `civilian_targeting`) keeps the Event-only definition, because those ask about the Story's Events. Attribution begins 2026-07; earlier windows are Event-derived only. Also accepts: `country_iso3`. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#country", "example": "UKR,RUS", "x-aliases": [ "country_iso3" ] }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "One ACLED-style region. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region", "example": "Middle East" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "One continent. Expanded to its member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent", "example": "Europe" }, { "name": "country_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "location_or_actor_origin", "location" ], "default": "location_or_actor_origin" }, "description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Defaults to the wider one, which is why omitting it changes nothing. Applies to `region` and `continent` too, since both expand into the same country set. Full value list: https://docs.gdeltcloud.com/reference/enums#country_match", "example": "location" }, { "name": "admin1", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-national admin1. Discover valid values with `GET /api/v2/geo/admin1?country=`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#admin1", "example": "Kharkivska Oblast" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box `lat_min,lon_min,lat_max,lon_max`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "11,41,16,45" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict to one entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Also accepts: `entity_id`, `entities`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle", "example": "e_0576e79c82962452", "x-aliases": [ "entity_id", "entities" ] }, { "name": "entity_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "material", "actor", "coverage" ], "default": "material" }, "description": "Why an entity-scoped row is eligible. `material` (default) requires persisted evidence; `actor` requires a coded actor; `coverage` explicitly opts into broad story co-occurrence. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match", "example": "material" }, { "name": "category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Event category — an ACLED event type or a CAMEO+ domain. Comma-separate for OR. Validated together with `subcategory`: an impossible pair returns 400, never an empty 200. Also accepts: `categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "categories" ] }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate multiple values for OR. Scoped by `category` — sending it alone is 400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is 400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a bad value is never an empty 200 (both verified 2026-08-13). The taxonomy is closed and published in full, but PUBLICATION IS NOT COVERAGE — a defined code can carry zero events in any given window, and a few carry zero in most windows (`Sexual violence` is the measured example: its definition boundary sends nearly all such reporting to `Attack`). Before building a monitor on one code, measure it: `GET /api/v2/events/summary?group_by=subcategory` returns the codes that actually carry events in your window, with counts. An empty 200 here means no coverage for that combination, never zero real-world activity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/taxonomy-complete", "example": "Peaceful protest" }, { "name": "story_category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conflict_security", "cameoplus_political", "cameoplus_crime", "cameoplus_economic", "cameoplus_corporate", "cameoplus_technology", "cameoplus_infrastructure", "cameoplus_environment", "cameoplus_health", "cameoplus_demographic", "cameoplus_information", "CONFLICT", "CORPORATE", "CRIME", "DEMOGRAPHIC", "ECONOMIC", "ENVIRONMENT", "HEALTH", "INFORMATION", "INFRASTRUCTURE", "POLITICAL", "TECHNOLOGY" ] }, "description": "Story-level topic. Distinct from the EVENT taxonomy that `category` filters. Full value list: https://docs.gdeltcloud.com/reference/enums#story_category", "example": "conflict_security" }, { "name": "event_category", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Battles", "Protests", "Riots", "Explosions/Remote violence", "Violence against civilians", "Strategic developments", "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] } }, "description": "Filter Stories by the EVENT taxonomy of the events linked to them. Also accepts: `event_categories`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#event_category", "example": "Protests", "x-aliases": [ "event_categories" ] }, { "name": "has_events", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories with at least one linked Event. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "has_fatalities", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories whose linked events carry fatalities. CONFLICT FAMILY ONLY. `fatalities` is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry `fatalities: null` (never a fabricated 0) and can never satisfy `true`. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. `false` is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means \"not known to be lethal\", never \"known to be non-lethal\". Stories publish no metric filters, so for a cross-family severity screen query `/api/v2/events` — which does — and follow `story_refs` back. Read `fatalities` off each linked event to tell a measured 0 from an absent observable. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "civilian_targeting", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to Stories with civilian-targeting events. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "article_count_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1 }, "description": "Lower bound on the number of source articles behind a Story. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2" }, { "name": "article_count_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1 }, "description": "Upper bound on the number of source articles behind a Story. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "50" }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Coverage-language filter (ISO 639-1/2) on the underlying articles. Also accepts: `language`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language", "example": "en,zh", "x-aliases": [ "language" ] }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "POLITICAL", "CRIME", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "ENVIRONMENT", "HEALTH", "DEMOGRAPHIC", "INFORMATION" ] }, "description": "Deprecated CAMEO+ domain filter. Prefer `category`. Since 2026-05; use `category`. Full value list: https://docs.gdeltcloud.com/reference/enums#cameoplus_domain", "example": "ECONOMIC", "deprecated": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Story summary buckets", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorySummaryBucket" } } } }, "examples": { "summary": { "value": { "success": true, "group_by": "country", "data": [ { "key": "Japan", "group_by": "country", "story_count": 8, "article_count": 44, "avg_article_count": 5.5, "max_article_count": 13, "stories_with_events": 6, "stories_with_fatalities": 0, "fatalities": 0, "avg_significance": 0.51, "max_significance": 0.83, "min_significance": 0.19, "linked_event_count": 11, "avg_linked_event_count": 1.38, "max_linked_event_count": 4, "metrics": { "significance": { "avg": 0.51, "max": 0.83, "min": 0.19 }, "article_count": { "total": 44, "avg": 5.5, "max": 13 }, "linked_events": { "count": 11, "avg_per_story": 1.38, "max_per_story": 4, "significance": { "avg": 0.47, "max": 0.78 }, "goldstein_scale": { "avg": -1.9, "max": 4.2, "avg_severity": 2.6 }, "cameoplus": { "magnitude": { "avg": 0.38, "max": 0.7 }, "systemic_importance": { "avg": 0.33, "max": 0.62 }, "propagation_potential": { "avg": 0.27, "max": 0.55 }, "market_sensitivity": { "avg": 0.29, "max": 0.61 } }, "confidence": { "avg": 0.79, "max": 0.94 } }, "recency_score": { "avg": 0.64 }, "fatalities": { "stories": 0, "rate": 0, "total": 0 } } } ] } } } } } } } } }, "/api/v2/entities": { "get": { "operationId": "search-entities-v2", "summary": "Search Entities", "description": "Discover linked people and organizations that connect to Stories and Events. Entity taxonomy filters operate on linked Story/Event evidence.", "tags": [ "Entities" ], "parameters": [ { "name": "search", "in": "query", "description": "Entity name or phrase to search for. Aliases `q`, `query`, `keyword`, and `name` are accepted (first non-empty wins); for high-recall cross-source discovery see `GET /api/v2/search`. Resolved filters are echoed in the response `applied_filters` block, with unrecognized params under `applied_filters.ignored`.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Optional entity type filter. `place` covers geographies (countries, cities, regions), typed from Wikidata P31 — before 2026-07-30 these were mis-filed under organization and person, so type=organization returned countries. Roles and offices are deliberately none of these three and are excluded rather than mislabelled. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_type", "schema": { "type": "string", "enum": [ "person", "organization", "place" ] } }, { "$ref": "#/components/parameters/dateStart" }, { "$ref": "#/components/parameters/dateEnd" }, { "$ref": "#/components/parameters/eventFamily" }, { "$ref": "#/components/parameters/category" }, { "$ref": "#/components/parameters/subcategory" }, { "$ref": "#/components/parameters/domain" }, { "$ref": "#/components/parameters/hasFatalities" }, { "$ref": "#/components/parameters/civilianTargeting" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "example": "UKR,RUS", "x-aliases": [ "country_iso3" ], "description": "Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Resolved through the same shared resolver `/api/v2/events` and `/api/v2/stories` use, and it narrows BOTH which entities are returned AND the `metrics` on each row — so a count on a country-filtered list is that entity's coverage in that country, not worldwide. The response sets `metrics_scope: \"filter_scoped\"` to say so.\n\nThat matters when comparing to `/api/v2/entities/{entity_id}`, which has no geography parameter and always reports the window-wide number. The two legitimately disagree under a country filter; `metrics_scope` is how you tell which you are holding.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Middle East", "description": "One ACLED-style region, expanded to its member countries. Same resolver and same value list as on `/api/v2/events`; see the value reference for the full set.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Europe", "description": "One continent, expanded to its member countries. Same resolver and same value list as on `/api/v2/events`.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" }, { "name": "include_images", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "example": "true", "description": "Attach entity images. Off by default — images cost an extra lookup, so pass `true` to opt in.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "example": "en,zh", "x-aliases": [ "language" ], "description": "Source-language filter (ISO 639-1/2). Keeps entities appearing in a story carrying at least one article in the requested origin language. Also accepts: `language`.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" }, { "name": "country_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "location", "location_or_actor_origin" ] }, "example": "location", "description": "How `country` is matched. `location_or_actor_origin` (the default) also keeps entities whose coverage involves an actor FROM that country wherever the event happened; `location` restricts to geography alone. Same two definitions as on `/api/v2/events` and `/api/v2/stories`.", "x-declared-by": "constitution/api/phantom-params#UNDECLARED_PARAMS" } ], "responses": { "200": { "description": "Entity cards", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityCard" } } } } ] }, "examples": { "entities": { "value": { "success": true, "data": [ { "id": "https://en.wikipedia.org/wiki/United_Nations", "url": "https://gdeltcloud.com/entities/e_united_nations", "name": "United Nations", "type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/United_Nations", "story_refs": [], "event_refs": [] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "eyJvZmZzZXQiOjI1fQ==" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/entities\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/entities/{entity_id}": { "get": { "operationId": "get-entity-v2", "summary": "Get Entity", "description": "Fetch one Entity profile with linked Stories and Events. Admin/internal callers can set include_tone=true to join cached Entity Tone coverage; when no tone score exists, the response returns tone_status=not_available rather than hiding the entity or treating missing tone as neutral.", "tags": [ "Entities" ], "parameters": [ { "name": "entity_id", "in": "path", "required": true, "description": "Entity ID returned by Search Entities or an entity_refs array. Wikipedia URLs are valid IDs and must be URL-encoded.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/dateStart" }, { "$ref": "#/components/parameters/dateEnd" }, { "$ref": "#/components/parameters/limitDetail" }, { "name": "include_images", "in": "query", "required": false, "description": "Set false to skip best-effort Wikipedia thumbnail/avatar enrichment.", "schema": { "type": "boolean", "default": true } }, { "name": "include_tone", "in": "query", "required": false, "description": "Admin/internal preview: include cached Entity Tone coverage when available. Missing tone returns entity_tone.tone_status = not_available and should not be interpreted as neutral.", "schema": { "type": "boolean", "default": false } }, { "name": "include_registry", "in": "query", "required": false, "description": "Overlay the canonical registry sections (SEC filings / energy / screening / China) on the entity profile. Plan-gated (no admin bypass): requires a plan carrying registry access (`can_use_filings`, `can_use_screening`, `can_use_china`, or `can_use_exposure`), otherwise returns 403 PLAN_REQUIRED. Legacy bundled flag — prefer the per-source `sources` map, where each section is gated by its own plan flag.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Entity detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EntityCard" } } }, "examples": { "entity": { "value": { "success": true, "data": { "id": "https://en.wikipedia.org/wiki/United_Nations", "url": "https://gdeltcloud.com/entities/e_united_nations", "name": "United Nations", "type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/United_Nations", "story_refs": [], "event_refs": [] } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/entities/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FExample\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/entities/{entity_id}/hierarchy": { "get": { "operationId": "get-entity-hierarchy-v2", "summary": "Corporate hierarchy for a resolved entity", "description": "An entity's corporate hierarchy resolved through our spine: `direct_parent`, `ultimate_parent`, `children` and `child_count`. Accepts the same identifiers as the rest of the API — a name, an `e_` id, a `wiki:` id or a wikipedia_url — and additionally a bare 20-character LEI, so the identifier you searched with works at this hop too.\n\n**Read the `coverage` block before the hierarchy.** `lei_present: false` means the entity carries no LEI in our crosswalk — a coverage gap, NOT evidence the entity has no parent. `reporting_exception` carries the reason a filer gave for not naming a parent (for example NO_KNOWN_PERSON), which is a DECLARED absence and materially different from an unknown one. `child_count` is null, never 0, when the requested direction excluded children.\n\nCorporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists.\n\nGated on the existing `can_use_exposure` entitlement; the LEI itself is ungated. Point-in-time (`as_of`) is not supported for this source.", "tags": [ "Entities" ], "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A name, an `e_` spine id, a `wiki:` news id, a wikipedia_url, or a bare 20-character LEI.", "example": "Gazprom" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "up", "down", "both" ], "default": "both" }, "description": "Which way to walk. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_hierarchy_direction", "example": "both" }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 }, "description": "Ancestor chain depth." }, { "name": "include_siblings", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include entities sharing the same direct parent." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "description": "Children to return." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "`entity`, `hierarchy` (or null), `coverage` and `meta` — the latter carrying the GLEIF attribution, the consolidation disclaimer verbatim, and `time_semantics`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter — `code` is one of INVALID_LEI, INVALID_ENUM, INVALID_LIMIT or FILTER_REQUIRED, with `details.accepted_values` where an enum was rejected." }, "403": { "description": "PLAN_REQUIRED — the caller's plan lacks `can_use_gleif`." }, "404": { "description": "ENTITY_NOT_FOUND — the reference did not resolve, or the LEI is not in the index we serve." } } } }, "/api/v2/entities/{entity_id}/tone": { "get": { "operationId": "get-entity-tone-v2", "summary": "Entity tone (by entity)", "tags": [ "Entities" ], "description": "Media tone toward a specific entity over a date window, with optional cited evidence. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.\n\n**`bucket` is not a parameter of this endpoint.** Entity tone is always DAILY. The series is scored per entity per story per day and the response carries `bucket_granularity: \"day\"` on every row; there is no weekly or monthly aggregation to request. The spec previously advertised `bucket=day|week|month`, which the service never parsed — `bucket=month` returned daily rows with a 200. Aggregate on your side, or narrow the window with `date_start`/`date_end`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical entity id or wikipedia_url." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30)." }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated language filter (e.g. en,zh). Accepted codes: [Taxonomy & Codes — Languages](/api-reference/taxonomy#languages). Observed vocabulary, measured 2026-08-10 (77 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/stories?limit=1 — read `coverage.languages``. The languages the corpus actually carries, canonicalized toward ISO 639-1 (639-2 codes are folded to their 2-letter form, and a long tail of 639-3 codes survives for outlets that have no 639-1 code). The filter validates SHAPE, not membership: it rejects only a token that cannot be an ISO code — a normalized value longer than 3 characters, so `languages=english` is a 400 while `languages=zz` is an accepted, empty 200. A code absent from this list may still be valid; it just had no coverage in the measured window. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#coverage_language" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "language" ] }, "description": "group_by=language returns a per-language tone breakdown over ALL scored Stories in the window — on each entity_coverage[].by_language: mean_tone, mean_risk, confidence, scored_story_count (scored Stories covered in that language), article_count (total articles in that language, real coverage volume — not the evidence sample), and a per-language daily series. Use it to compare how the entity is covered across languages." }, { "name": "include_evidence", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return cited evidence snippets." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Max rows." }, { "name": "quality", "in": "query", "required": false, "description": "Evidence-gating quality tier for which tone rows to return. Full value list: https://docs.gdeltcloud.com/reference/enums#quality", "schema": { "type": "string", "enum": [ "production_ready", "reviewable", "all" ], "default": "production_ready" } }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum per-bucket tone confidence to include (0–1).", "schema": { "type": "number", "minimum": 0, "maximum": 1 } } ], "responses": { "200": { "description": "Entity tone (by entity).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "entities": { "type": "array", "items": { "type": "string" } }, "resolved_entities": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "match_type": { "type": "string" } } } }, "unresolved_terms": { "type": "array", "items": {} }, "entity_coverage": { "type": "array", "items": { "type": "object", "properties": { "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "tone_status": { "type": "string" }, "row_count": { "type": "integer" }, "candidate_story_count": { "type": "integer" }, "candidate_article_count": { "type": "integer" }, "candidate_mention_count": { "type": "integer" }, "scored_story_count": { "type": "integer" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "bucket_date": { "type": "string" }, "bucket_granularity": { "type": "string" }, "denominator_hash": { "type": "string" }, "candidate_story_count": { "type": "integer" }, "scored_story_count": { "type": "integer" }, "scored_article_count": { "type": "integer" }, "insufficient_evidence_count": { "type": "integer" }, "needs_review_count": { "type": "integer" }, "avg_tone_score": { "type": "number" }, "avg_risk_score": { "type": "number" }, "avg_confidence": { "type": "number" }, "coverage_ratio": { "type": "number" }, "agreement_score": { "type": "number" }, "languages": { "type": "array", "items": { "type": "string" } }, "top_positive_story_ids": { "type": "array", "items": { "type": "string" } }, "top_negative_story_ids": { "type": "array", "items": {} }, "top_risky_story_ids": { "type": "array", "items": { "type": "string" } } } } }, "methodology": { "type": "object", "properties": { "unit": { "type": "string" }, "tone_score": { "type": "string" }, "risk_score": { "type": "string" }, "missing_tone": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/entities/{entity_id}/tone — example response", "value": { "status": "available", "start_date": "2026-06-01", "end_date": "2026-06-28", "entities": [ "wikipedia:en:Saudi_Aramco" ], "resolved_entities": [ { "input": "Saudi Aramco", "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "match_type": "exact_alias" } ], "unresolved_terms": [], "entity_coverage": [ { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "tone_status": "scored", "row_count": 28, "candidate_story_count": 213, "candidate_article_count": 1486, "candidate_mention_count": 2741, "scored_story_count": 188 } ], "rows": [ { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "bucket_date": "2026-06-14", "bucket_granularity": "day", "denominator_hash": "", "candidate_story_count": 12, "scored_story_count": 11, "scored_article_count": 86, "insufficient_evidence_count": 1, "needs_review_count": 0, "avg_tone_score": 9.6, "avg_risk_score": 25.1, "avg_confidence": 0.83, "coverage_ratio": 0.91, "agreement_score": 0.77, "languages": [ "en", "ar" ], "top_positive_story_ids": [ "20260614-aramco-upstream-expansion" ], "top_negative_story_ids": [], "top_risky_story_ids": [ "20260614-aramco-pipeline-incident" ] }, { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "bucket_date": "2026-06-15", "bucket_granularity": "day", "denominator_hash": "", "candidate_story_count": 17, "scored_story_count": 15, "scored_article_count": 112, "insufficient_evidence_count": 1, "needs_review_count": 1, "avg_tone_score": 12.4, "avg_risk_score": 28.7, "avg_confidence": 0.81, "coverage_ratio": 0.88, "agreement_score": 0.74, "languages": [ "en", "ar", "fr" ], "top_positive_story_ids": [ "20260615-aramco-dividend-raise", "20260615-aramco-lng-deal" ], "top_negative_story_ids": [ "20260615-aramco-emissions-report" ], "top_risky_story_ids": [ "20260615-aramco-emissions-report" ] } ], "methodology": { "unit": "entity-story rollups over article-entity evidence", "tone_score": "-100..100 media tone toward the entity; not direct public opinion", "risk_score": "0..100 reputational or issue-risk severity, separate from tone direction", "missing_tone": "missing or insufficient evidence is unavailable, not neutral" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/search": { "get": { "operationId": "unified-entity-search-v2", "summary": "Unified cross-source entity search", "tags": [ "Unified Search" ], "description": "High-recall fuzzy + semantic entity search across EVERY entity universe — news, GEG-Wikipedia, SEC/EDGAR, Global Energy Monitor, sanctions lists, China development finance, and Epoch AI — deduplicated into ONE result per real-world entity (keyed on the canonical spine `e_` id), each with a per-source availability map and cross-source identifiers. This is a CANDIDATE LIST (not resolve-to-one): a query like `Zelensky` legitimately means several people. Available to any authenticated API key — search itself carries no plan flag. Your plan still governs the DETAIL behind a hit: sources you are not entitled to are redacted from the `sources` availability map and `identifiers` rather than blocking the search.\n\nUse this to find an entity by any name/alias/acronym without knowing which source it lives in, then jump into `/api/v2/entities/{entity_id}` for the full profile. The `q` param is canonical; `query`, `keyword`, `name`, and `search` are accepted aliases.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 }, "description": "Search text — a name, alias, or acronym. Fuzzy + semantic, so exact spelling is not required. Required. Aliases `query`, `keyword`, `name`, and `search` are accepted (first non-empty wins)." }, { "name": "universe", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "news", "reference", "registry" ], "default": "all" }, "description": "Which universes to search. `all` (default) spans every source; `news` restricts to entities seen in news coverage; `reference` restricts to the canonical spine (SEC / GEM / sanctions / China / Epoch). `registry` searches the raw GLEIF Global LEI Index (3.39M records, CC0) by legal name or LEI in its own lane: hits are legal-entity REGISTRATIONS, not evidence of news coverage. Each carries `resolved_in_spine` (whether we also cover the entity itself) and a `lei` that chains to /api/v2/gleif/entities/{lei} and /api/v2/entities/{lei}/hierarchy. Registry rows never appear under `all` or `reference`. Full value list: https://docs.gdeltcloud.com/reference/enums#search_universe" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "Germany" }, "description": "Optional country disambiguator, folded to one ISO-3 set through the shared `resolveCohortGeoIso3` resolver (the same layer `region`/`continent` use). Accepts a country name (`Germany`), ISO-2 (`DE`), ISO-3 (`DEU`), or alias (comma-separated list allowed). Additive — it keeps entities carrying a matching country but never drops entities that have no country (media/GEG entities usually lack one), so it narrows a common name without gutting results. An unresolvable value now returns `400 INVALID_ENUM`, consistent with the rest of the API." }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Additive geo disambiguator — expanded to an ISO-3 set via the same `resolveCohortGeoIso3` resolver as `country` and combinable with it. An unresolvable value returns `400 INVALID_ENUM`." }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Additive geo disambiguator — expanded to an ISO-3 set via `resolveCohortGeoIso3`. An unresolvable value returns `400 INVALID_ENUM`." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "person", "organization", "place" ] }, "description": "Optional entity type filter. `place` covers geographies (countries, cities, regions), typed from Wikidata P31 — before 2026-07-30 these were mis-filed under organization and person, so type=organization returned countries. Roles and offices are deliberately none of these three and are excluded rather than mislabelled. Full value list: https://docs.gdeltcloud.com/reference/enums#search_entity_type The enum above is the UNION across every endpoint that shares this parameter: `person`, `organization`, `place` — ACCEPTED ONLY ON `/api/v2/search`. Elsewhere they return 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "description": "Number of distinct real-world entities to return (1–50). Defaults to 10." } ], "responses": { "200": { "description": "A ranked list of distinct real-world entities. Each item carries the canonical entity id, an optional spine id, a normalized entity_type, a per-source availability map (`sources`), cross-source identifiers, and the universes it was matched in. Envelope: `{ success, query, count, data, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "string" }, "count": { "type": "integer", "description": "Number of entities in `data` (echoes data.length)." }, "data": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Canonical entity id — the spine `e_` id when the entity resolves into the spine, else the source candidate's own id. Feed this to `/api/v2/entities/{entity_id}`." }, "spine_id": { "type": "string", "nullable": true, "description": "The spine `e_` id when the entity is in the registry-of-record, else null." }, "name": { "type": "string" }, "entity_type": { "type": "string", "description": "Normalized canonical type. `entity` is the fallback when no source carried a usable type.", "enum": [ "person", "company", "organization", "government", "state_body", "place", "entity" ] }, "entity_type_raw": { "type": "string", "description": "The raw per-source type string that won the vote, preserved for debugging." }, "wikipedia_url": { "type": "string", "nullable": true }, "score": { "type": "number", "description": "Match score (higher is a stronger match)." }, "match_type": { "type": "string", "description": "How the entity matched, e.g. exact_name, token_set, acronym, fuzzy_name, semantic." }, "match_reason": { "type": "string", "description": "Human-readable reason the entity matched the query." }, "sources": { "type": "object", "description": "Per-source availability for this entity. Each flag is a real JSON boolean. `gov` covers US federal awards (USAspending) and FARA foreign-principal registrations. The gated flags (`sec`, `sanctions`, `china`, `epoch`, `gov`) are present ONLY for callers entitled to the matching plan feature and are OMITTED otherwise — an omitted flag means the source was not checked for you, never that the entity has no such records. Test with `'gov' in sources`, not `sources.gov === false`.", "properties": { "news": { "type": "boolean" }, "sec": { "type": "boolean" }, "gem": { "type": "boolean" }, "sanctions": { "type": "boolean" }, "china": { "type": "boolean" }, "wiki": { "type": "boolean" }, "epoch": { "type": "boolean" }, "gov": { "type": "boolean" } } }, "identifiers": { "type": "object", "description": "Cross-source identifiers keyed by id type (e.g. us_sec_cik, ticker, gem, epoch_org), each an array of values. Empty when the entity has no spine id.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "source_universes": { "type": "array", "description": "Which universes contributed to this merged entity (media, geg_wiki, reference).", "items": { "type": "string" } } } } }, "applied_filters": { "type": "object", "properties": { "q": { "type": "string" }, "universe": { "type": "string" }, "limit": { "type": "integer" }, "country": { "type": "string", "description": "Resolved country name — echoed only when a country/region/continent resolved." }, "region": { "type": "string", "description": "Resolved region — echoed only when supplied and resolvable." }, "continent": { "type": "string", "description": "Resolved continent — echoed only when supplied and resolvable." }, "country_iso3": { "type": "array", "items": { "type": "string" }, "description": "The ISO-3 set the geo filter expanded to; present only when a country/region/continent resolved." }, "ignored": { "type": "array", "items": { "type": "string" } } } } } }, "examples": { "example": { "summary": "GET /api/v2/search?q=Rosneft — example response", "value": { "success": true, "query": "Rosneft", "count": 1, "data": [ { "entity_id": "e_1a2b3c4d5e6f7a8b", "spine_id": "e_1a2b3c4d5e6f7a8b", "name": "Rosneft Oil Company", "entity_type": "company", "entity_type_raw": "state-owned enterprise", "wikipedia_url": "https://en.wikipedia.org/wiki/Rosneft", "score": 0.987, "match_type": "exact_name", "match_reason": "Exact match on canonical name", "sources": { "news": true, "sec": false, "gem": true, "sanctions": true, "china": false, "wiki": true, "epoch": false }, "identifiers": { "gem": [ "G100000112345" ], "list_entry": [ "OFAC-SDN-12345" ] }, "source_universes": [ "media", "reference" ] } ], "applied_filters": { "q": "Rosneft", "universe": "all", "limit": 10 } } } } } } }, "400": { "description": "Missing/invalid query (MISSING_PARAM / QUERY_TOO_LONG)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key disabled or access denied (`API_KEY_DISABLED`). Unified search carries no plan flag, so a plan can never 403 it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/entity-tone": { "get": { "operationId": "entity-tone-v2", "summary": "Entity tone", "tags": [ "Media Intelligence" ], "description": "Entity-conditioned media tone, risk, and confidence over a window, with cited evidence. Resolve the entity first with /api/v2/search. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical entity id / wikipedia_url." }, { "name": "entity_search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Resolve by name instead of id." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alias for entity_search." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30)." }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Language filter (e.g. en,zh,ar). Accepted codes: [Taxonomy & Codes — Languages](/api-reference/taxonomy#languages)." }, { "name": "include_evidence", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include evidence snippets." }, { "name": "evidence_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 }, "description": "Max evidence samples returned for the window — one card per story (default 25, max 250). Applied as a single global limit over the window, not a per-bucket cap." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Max rows." } ], "responses": { "200": { "description": "Entity tone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "entities": { "type": "array", "items": { "type": "string" } }, "resolved_entities": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "match_type": { "type": "string" } } } }, "unresolved_terms": { "type": "array", "items": {} }, "entity_coverage": { "type": "array", "items": { "type": "object", "properties": { "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "tone_status": { "type": "string" }, "row_count": { "type": "integer" }, "candidate_story_count": { "type": "integer" }, "candidate_article_count": { "type": "integer" }, "candidate_mention_count": { "type": "integer" }, "scored_story_count": { "type": "integer" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "bucket_date": { "type": "string" }, "bucket_granularity": { "type": "string" }, "denominator_hash": { "type": "string" }, "candidate_story_count": { "type": "integer" }, "scored_story_count": { "type": "integer" }, "scored_article_count": { "type": "integer" }, "insufficient_evidence_count": { "type": "integer" }, "needs_review_count": { "type": "integer" }, "avg_tone_score": { "type": "number" }, "avg_risk_score": { "type": "number" }, "avg_confidence": { "type": "number" }, "coverage_ratio": { "type": "number" }, "agreement_score": { "type": "number" }, "languages": { "type": "array", "items": { "type": "string" } }, "top_positive_story_ids": { "type": "array", "items": { "type": "string" } }, "top_negative_story_ids": { "type": "array", "items": { "type": "string" } }, "top_risky_story_ids": { "type": "array", "items": { "type": "string" } } } } }, "methodology": { "type": "object", "properties": { "unit": { "type": "string" }, "tone_score": { "type": "string" }, "risk_score": { "type": "string" }, "missing_tone": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/entity-tone — example response", "value": { "status": "available", "start_date": "2026-06-01", "end_date": "2026-06-28", "entities": [ "wikipedia:en:Saudi_Aramco", "wikipedia:en:Tesla,_Inc." ], "resolved_entities": [ { "input": "Saudi Aramco", "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "match_type": "exact_alias" }, { "input": "Tesla", "canonical_entity_id": "wikipedia:en:Tesla,_Inc.", "display_name": "Tesla, Inc.", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Tesla,_Inc.", "match_type": "exact_alias" } ], "unresolved_terms": [], "entity_coverage": [ { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "tone_status": "scored", "row_count": 14, "candidate_story_count": 213, "candidate_article_count": 1486, "candidate_mention_count": 2741, "scored_story_count": 188 }, { "canonical_entity_id": "wikipedia:en:Tesla,_Inc.", "display_name": "Tesla, Inc.", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Tesla,_Inc.", "tone_status": "scored", "row_count": 21, "candidate_story_count": 642, "candidate_article_count": 5310, "candidate_mention_count": 9874, "scored_story_count": 604 } ], "rows": [ { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "bucket_date": "2026-06-15", "bucket_granularity": "day", "denominator_hash": "", "candidate_story_count": 17, "scored_story_count": 15, "scored_article_count": 112, "insufficient_evidence_count": 1, "needs_review_count": 1, "avg_tone_score": 12.4, "avg_risk_score": 28.7, "avg_confidence": 0.81, "coverage_ratio": 0.88, "agreement_score": 0.74, "languages": [ "en", "ar", "fr" ], "top_positive_story_ids": [ "20260615-aramco-dividend-raise", "20260615-aramco-lng-deal" ], "top_negative_story_ids": [ "20260615-aramco-emissions-report" ], "top_risky_story_ids": [ "20260615-aramco-emissions-report" ] }, { "canonical_entity_id": "wikipedia:en:Tesla,_Inc.", "display_name": "Tesla, Inc.", "entity_type": "organization", "bucket_date": "2026-06-15", "bucket_granularity": "day", "denominator_hash": "", "candidate_story_count": 53, "scored_story_count": 49, "scored_article_count": 401, "insufficient_evidence_count": 2, "needs_review_count": 2, "avg_tone_score": -8.2, "avg_risk_score": 41.3, "avg_confidence": 0.79, "coverage_ratio": 0.92, "agreement_score": 0.68, "languages": [ "en", "de", "zh" ], "top_positive_story_ids": [ "20260615-tesla-q2-deliveries-beat" ], "top_negative_story_ids": [ "20260615-tesla-recall-autopilot", "20260615-tesla-margin-pressure" ], "top_risky_story_ids": [ "20260615-tesla-recall-autopilot" ] } ], "methodology": { "unit": "entity-story rollups over article-entity evidence", "tone_score": "-100..100 media tone toward the entity; not direct public opinion", "risk_score": "0..100 reputational or issue-risk severity, separate from tone direction", "missing_tone": "missing or insufficient evidence is unavailable, not neutral" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/entity-tone/runs": { "get": { "operationId": "list-entity-tone-runs-v2", "summary": "List tone runs", "tags": [ "Media Intelligence" ], "description": "List entity-tone scoring runs. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "List tone runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string" }, "run_type": { "type": "string" }, "status": { "type": "string" }, "request_source": { "type": "string" }, "requester_user_id": { "type": "string" }, "requester_email": { "type": "string" }, "request_json": { "type": "string" }, "denominator_hash": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "target_entity_count": { "type": "integer" }, "candidate_story_count": { "type": "integer" }, "scored_case_count": { "type": "integer" }, "estimated_query_units": { "type": "integer" }, "charged_query_units": { "type": "integer" }, "estimated_cost_usd": { "type": "number" }, "error": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {}, "has_more": { "type": "boolean" } } } } }, "examples": { "example": { "summary": "GET /api/v2/entity-tone/runs — example response", "value": { "success": true, "data": [ { "run_id": "entity-tone-v2-3f9c1b2a-7d4e-4a51-9c83-1e6b2f0a55d1", "run_type": "entity_tone", "status": "succeeded", "request_source": "api", "requester_user_id": "a1d4f7c2-9b3e-4c08-8f21-6d5b0e9a3c47", "requester_email": "", "request_json": "{\"entity_ids\":[\"wikipedia:en:Saudi_Aramco\"],\"start_date\":\"2026-06-01\",\"end_date\":\"2026-06-28\",\"filters\":{}}", "denominator_hash": "c0ffee7a1b2c3d4e", "start_date": "2026-06-01", "end_date": "2026-06-28", "target_entity_count": 1, "candidate_story_count": 213, "scored_case_count": 188, "estimated_query_units": 23, "charged_query_units": 23, "estimated_cost_usd": 0.1704, "error": "", "created_at": "2026-06-28 14:22:07", "updated_at": "2026-06-28 14:41:55" }, { "run_id": "entity-tone-v2-8b71e4d0-2a16-4f93-bc55-9aa0c7e21f08", "run_type": "entity_tone", "status": "queued", "request_source": "api", "requester_user_id": "a1d4f7c2-9b3e-4c08-8f21-6d5b0e9a3c47", "requester_email": "", "request_json": "{\"entity_ids\":[\"wikipedia:en:Tesla,_Inc.\"],\"start_date\":\"2026-06-20\",\"end_date\":\"2026-06-28\",\"filters\":{}}", "denominator_hash": "9a8b7c6d5e4f3021", "start_date": "2026-06-20", "end_date": "2026-06-28", "target_entity_count": 1, "candidate_story_count": 642, "scored_case_count": 0, "estimated_query_units": 66, "charged_query_units": 0, "estimated_cost_usd": 0.5136, "error": "", "created_at": "2026-06-29 09:03:12", "updated_at": "2026-06-29 09:03:12" } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null, "has_more": false } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "create-entity-tone-run-v2", "summary": "Trigger a tone run", "tags": [ "Media Intelligence" ], "description": "Queue an on-demand entity-tone scoring run for an entity/topic. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entity_search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Entity to score." }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional topic anchor." } ], "responses": { "200": { "description": "Trigger a tone run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "poll_url": { "type": "string" }, "confirm_required": { "type": "boolean" }, "entity_ids": { "type": "array", "items": { "type": "string" } }, "resolved_entities": { "type": "array", "items": { "type": "object", "properties": { "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "match_type": { "type": "string" }, "confidence": { "type": "number" } } } }, "window": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } } }, "candidate_story_count": { "type": "integer" }, "candidate_article_count": { "type": "integer" }, "queued_case_count": { "type": "integer" }, "estimated_query_units": { "type": "integer" }, "charged_query_units": { "type": "integer" }, "estimated_cost_usd": { "type": "number" }, "note": { "type": "string" } } } } }, "examples": { "example": { "summary": "POST /api/v2/entity-tone/runs — example response", "value": { "success": true, "data": { "run_id": "entity-tone-v2-3f9c1b2a-7d4e-4a51-9c83-1e6b2f0a55d1", "status": "queued", "poll_url": "/api/v2/entity-tone/runs/entity-tone-v2-3f9c1b2a-7d4e-4a51-9c83-1e6b2f0a55d1", "confirm_required": false, "entity_ids": [ "wikipedia:en:Saudi_Aramco" ], "resolved_entities": [ { "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "match_type": "exact_alias", "confidence": 0.98 } ], "window": { "start_date": "2026-06-01", "end_date": "2026-06-28" }, "candidate_story_count": 213, "candidate_article_count": 1486, "queued_case_count": 188, "estimated_query_units": 23, "charged_query_units": 0, "estimated_cost_usd": 0.1704, "note": "Run queued in the V2 entity-tone side pipeline. Scoring is asynchronous and cached rows become available through /api/v2/entity-tone." } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/entity-tone/runs/{run_id}": { "get": { "operationId": "get-entity-tone-run-v2", "summary": "Tone run status", "tags": [ "Media Intelligence" ], "description": "Status + result of a queued entity-tone run. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id from the create call." } ], "responses": { "200": { "description": "Tone run status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "run_id": { "type": "string" }, "run_type": { "type": "string" }, "status": { "type": "string" }, "request_source": { "type": "string" }, "requester_user_id": { "type": "string" }, "requester_email": { "type": "string" }, "request_json": { "type": "string" }, "denominator_hash": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "target_entity_count": { "type": "integer" }, "candidate_story_count": { "type": "integer" }, "scored_case_count": { "type": "integer" }, "estimated_query_units": { "type": "integer" }, "charged_query_units": { "type": "integer" }, "estimated_cost_usd": { "type": "number" }, "error": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "case_status_counts": { "type": "array", "items": { "type": "object", "properties": { "case_status": { "type": "string" }, "count": { "type": "integer" } } } } } } } }, "examples": { "example": { "summary": "GET /api/v2/entity-tone/runs/{run_id} — example response", "value": { "success": true, "data": { "run_id": "entity-tone-v2-3f9c1b2a-7d4e-4a51-9c83-1e6b2f0a55d1", "run_type": "entity_tone", "status": "succeeded", "request_source": "api", "requester_user_id": "a1d4f7c2-9b3e-4c08-8f21-6d5b0e9a3c47", "requester_email": "", "request_json": "{\"entity_ids\":[\"wikipedia:en:Saudi_Aramco\"],\"resolved_entities\":[{\"canonical_entity_id\":\"wikipedia:en:Saudi_Aramco\",\"display_name\":\"Saudi Aramco\",\"entity_type\":\"organization\",\"wikipedia_url\":\"https://en.wikipedia.org/wiki/Saudi_Aramco\",\"match_type\":\"exact_alias\",\"confidence\":0.98}],\"start_date\":\"2026-06-01\",\"end_date\":\"2026-06-28\",\"filters\":{}}", "denominator_hash": "c0ffee7a1b2c3d4e", "start_date": "2026-06-01", "end_date": "2026-06-28", "target_entity_count": 1, "candidate_story_count": 213, "scored_case_count": 188, "estimated_query_units": 23, "charged_query_units": 23, "estimated_cost_usd": 0.1704, "error": "", "created_at": "2026-06-28 14:22:07", "updated_at": "2026-06-28 14:41:55", "case_status_counts": [ { "case_status": "done", "count": 188 }, { "case_status": "insufficient_evidence", "count": 19 }, { "case_status": "queued", "count": 6 } ] } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/share-of-voice": { "get": { "operationId": "get-share-of-voice-v2", "summary": "Share of Voice", "description": "Compare resolved entities within one explicit news denominator. All compatibility spellings are published as aliases.", "tags": [ "Media Intelligence" ], "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Semantic denominator query. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "oil supply disruption" }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lexical denominator topic. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "shipping" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Story or event category denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "Battles" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "NGA" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "West Africa" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "Africa" }, { "name": "languages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Language-code denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "en,fr" }, { "name": "source_set", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named source-universe denominator. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "all" }, { "name": "entities", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Entity identifiers. `entity_id` and `entity` are singular compatibility aliases. Also accepts: `entity_id`, `entity`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "e_123,e_456", "x-aliases": [ "entity_id", "entity" ] }, { "name": "entity_query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Entity-name resolver input. `entity_search`, `entity_terms`, and `numerator` are aliases. Also accepts: `entity_search`, `entity_terms`, `numerator`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "Siemens", "x-aliases": [ "entity_search", "entity_terms", "numerator" ] }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Previously materialized analytics run. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "run_123" }, { "name": "denominator_hash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Previously computed denominator identity. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "sha256" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "First occurrence date. `date_start` is an alias. Also accepts: `date_start`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "date_start" ] }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Last occurrence date. `date_end` is an alias. Also accepts: `date_end`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-21", "x-aliases": [ "date_end" ] }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Single occurrence date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Trailing window. `window` is an alias. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "30", "x-aliases": [ "window" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum entity rows. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "opaque" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Legacy numeric offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Share of Voice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "entities": { "type": "array", "items": { "type": "string" } }, "resolved_entities": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "match_type": { "type": "string" } } } }, "unresolved_terms": { "type": "array", "items": {} }, "coverage": { "type": "object", "properties": { "observed_entities": { "type": "array", "items": { "type": "string" } }, "not_observed_entities": { "type": "array", "items": {} }, "note": { "type": "string" } } }, "denominator": { "type": "object", "properties": { "hash": { "type": "string" }, "scope": { "type": "object", "properties": { "category": { "type": "string" }, "languages": { "type": "array", "items": {} }, "source_set": { "type": "array", "items": {} }, "countries": { "type": "array", "items": {} }, "regions": { "type": "array", "items": {} }, "topic": { "type": "string" } } }, "unit": { "type": "string" }, "validation": { "type": "string" }, "source": { "type": "string" }, "total_story_count": { "type": "integer" }, "total_article_count": { "type": "integer" }, "total_weight": { "type": "integer" }, "search_mode": { "type": "string" }, "semantic_min_score": {}, "semantic_candidate_limit": {}, "semantic_truncated": { "type": "boolean" } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string" }, "bucket_date": { "type": "string" }, "canonical_entity_id": { "type": "string" }, "display_name": { "type": "string" }, "entity_type": { "type": "string" }, "wikipedia_url": { "type": "string" }, "entity_status": { "type": "string" }, "denominator_hash": { "type": "string" }, "denominator_profile_json": { "type": "string" }, "denominator_story_count": { "type": "integer" }, "denominator_article_count": { "type": "integer" }, "denominator_weight": { "type": "integer" }, "entity_story_count": { "type": "integer" }, "entity_article_count": { "type": "integer" }, "entity_weight": { "type": "integer" }, "story_share": { "type": "number" }, "article_share": { "type": "number" }, "weighted_share": { "type": "number" }, "avg_tone_score": { "type": "number" }, "avg_risk_score": { "type": "number" }, "tone_coverage_ratio": { "type": "number" }, "coverage_warnings": { "type": "array", "items": {} } } } }, "methodology": { "type": "object", "properties": { "default_metric": { "type": "string" }, "denominator_required": { "type": "boolean" }, "note": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/share-of-voice — example response", "value": { "status": "available_live", "start_date": "2026-06-01", "end_date": "2026-06-28", "entities": [ "wikipedia:en:Saudi_Aramco", "wikipedia:en:Tesla,_Inc." ], "resolved_entities": [ { "input": "Saudi Aramco", "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "match_type": "exact_alias" }, { "input": "Tesla", "canonical_entity_id": "wikipedia:en:Tesla,_Inc.", "display_name": "Tesla, Inc.", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Tesla,_Inc.", "match_type": "exact_alias" } ], "unresolved_terms": [], "coverage": { "observed_entities": [ "wikipedia:en:Saudi_Aramco", "wikipedia:en:Tesla,_Inc." ], "not_observed_entities": [], "note": "All requested entities were observed in the denominator." }, "denominator": { "hash": "d41f2c8a6b9e0357", "scope": { "category": "energy", "languages": [], "source_set": [], "countries": [], "regions": [], "topic": "" }, "unit": "story", "validation": "accepted", "source": "live_query", "total_story_count": 4820, "total_article_count": 38917, "total_weight": 41263, "search_mode": "structured_filters", "semantic_min_score": null, "semantic_candidate_limit": null, "semantic_truncated": false }, "rows": [ { "run_id": "", "bucket_date": "2026-06-15", "canonical_entity_id": "wikipedia:en:Saudi_Aramco", "display_name": "Saudi Aramco", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Saudi_Aramco", "entity_status": "active", "denominator_hash": "d41f2c8a6b9e0357", "denominator_profile_json": "{\"scope\":{\"category\":\"energy\"},\"start_date\":\"2026-06-01\",\"end_date\":\"2026-06-28\"}", "denominator_story_count": 172, "denominator_article_count": 1389, "denominator_weight": 1474, "entity_story_count": 17, "entity_article_count": 142, "entity_weight": 151, "story_share": 0.0988, "article_share": 0.1022, "weighted_share": 0.1024, "avg_tone_score": 12.4, "avg_risk_score": 28.7, "tone_coverage_ratio": 0.88, "coverage_warnings": [] }, { "run_id": "", "bucket_date": "2026-06-15", "canonical_entity_id": "wikipedia:en:Tesla,_Inc.", "display_name": "Tesla, Inc.", "entity_type": "organization", "wikipedia_url": "https://en.wikipedia.org/wiki/Tesla,_Inc.", "entity_status": "active", "denominator_hash": "d41f2c8a6b9e0357", "denominator_profile_json": "{\"scope\":{\"category\":\"energy\"},\"start_date\":\"2026-06-01\",\"end_date\":\"2026-06-28\"}", "denominator_story_count": 172, "denominator_article_count": 1389, "denominator_weight": 1474, "entity_story_count": 9, "entity_article_count": 71, "entity_weight": 74, "story_share": 0.0523, "article_share": 0.0511, "weighted_share": 0.0502, "avg_tone_score": -8.2, "avg_risk_score": 41.3, "tone_coverage_ratio": 0.78, "coverage_warnings": [ "tone_not_yet_scored" ] } ], "methodology": { "default_metric": "story_share", "denominator_required": true, "note": "Share of voice is share of a DEFINED conversation (the denominator). A 0% share means the entity was not observed within this denominator — for a semantic denominator, its coverage fell below the similarity threshold — NOT that the entity is absent from the news; see coverage.not_observed_entities. V2 computes live denominators from story/event/article filters and joins canonical resolved entity-story links. Tone and risk fields are optional context when entity-tone rows exist; SOV itself remains count/share based." } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry `can_use_share_of_voice`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-plan-feature": "can_use_share_of_voice" } }, "/api/v2/facilities": { "get": { "operationId": "search-facilities-v2", "summary": "Search Facilities", "description": "Unified physical-asset directory — GEM energy and heavy-industry sites, WPI ports and AI data centers, deduped to one facility per real-world site.\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `admin1` → 400 UNSUPPORTED_FILTER. Facilities carry no sub-national admin1 column. Filter by country / region / continent / bbox / near instead. Use instead: `country`, `region`, `continent`, `bbox`, `near`.\n\n", "tags": [ "Facilities" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Rows per page. Default 25, max 100. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor taken from the previous response's `pagination.next_cursor`. Also accepts: `offset`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25", "x-aliases": [ "offset" ] }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "default": "site" }, "description": "`site` (default) returns one canonical physical site; `unit` exposes source registry units. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "site" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match over `name`. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results are ordered by facility name (A–Z), not by relevance, so a query matching more rows than `limit` returns an arbitrary slice. Also accepts: `search`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "Gazprom", "x-aliases": [ "search" ] }, { "name": "type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "coal_plant", "oil_gas_plant", "nuclear_plant", "geothermal_plant", "bioenergy_plant", "hydropower_plant", "solar_farm", "wind_farm", "coal_mine", "oil_gas_field", "iron_ore_mine", "coal_terminal", "lng_terminal", "gas_pipeline", "oil_pipeline", "lng_carrier", "port", "steel_plant", "cement_plant", "chemical_plant", "data_center" ] } }, "description": "Facility type (21 values). Comma-separate for OR. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#facility_type", "example": "coal_plant,lng_terminal" }, { "name": "class", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "power", "extraction", "transport_logistics", "ports", "heavy_industry", "digital_infrastructure" ] } }, "description": "Broad facility class; expanded to its member types. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#facility_class", "example": "power_generation" }, { "name": "source", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gem", "maritime_ports", "epoch" ] } }, "description": "Source silo the facility was projected from. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#facility_source_silo", "example": "gem" }, { "name": "status", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Lifecycle status. Matched case-insensitively — the corpus carries both `operating` and `Operating` — and GEM's \"- inferred N y\" variants fold into their base state. This is an OBSERVED vocabulary measured from the directory, not a closed list. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Observed vocabulary, measured 2026-08-10 (32 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/facilities?limit=1 (see applied_filters) or /api/v2/meta/enums`. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#facility_status", "example": "operating" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter (ISO-3). `region` and `continent` expand to their member countries. A facility matches on either its primary or secondary country. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "USA" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region; expanded to member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region", "example": "Middle East" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent; expanded to member countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent", "example": "Europe" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Owner filter. An `e_` spine id matches the resolved owner exactly; a name falls back to a fuzzy match on owner names. Also accepts: `owner_entity_id`, `owner_search`, `owner`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_handle", "example": "e_0576e79c82962452", "x-aliases": [ "owner_entity_id", "owner_search", "owner" ] }, { "name": "capacity_mw_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Minimum capacity in MW. Capacity units differ per tracker — see the tracker reference. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "100" }, { "name": "capacity_mw_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Maximum capacity in MW. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "5000" }, { "name": "has_geo", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to facilities that do (or do not) carry coordinates. 99.15% of the directory does; the residual are GEM linear/areal assets — pipelines and fields — which are geometry, not a point. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "has_owner", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true` restricts to facilities with a SPINE-RESOLVED owner (`owners[].entity_id` non-null). A facility can carry an unresolved owner NAME and still be excluded — that is the documented meaning of \"owner\" here, and it is the resolved id that makes owner-bridge fusion and `entity=` chaining possible. Owner coverage is 47.1% overall: heavy industry 99.9%, AI data centers 85%, GEM power 43%, ports 0% (WPI publishes no ownership layer). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ordering: name · capacity_desc · capacity_asc · recent · country. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "capacity_desc" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box `lat_min,lon_min,lat_max,lon_max`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "30,110,32,112" }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Point proximity `lat,lon,radius_km`, refined by true great-circle distance. Note this is the three-part grammar — /api/v2/events takes `near=lat,lon` with a separate `radius_km`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "31.05,111.00,25" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitiesListResponse" }, "examples": { "example_1": { "summary": "Canonical site with registry-unit evidence", "value": { "success": true, "data": [ { "facility_id": "s_8dead1adbc3b3684", "canonical_site_id": "s_8dead1adbc3b3684", "granularity": "site", "unit_id": null, "unit_count": 5, "unit_ids": [ "f_62714966cc4b283a" ], "unit_statuses": [ { "facility_id": "f_62714966cc4b283a", "status_source": "operating", "status": "operating" } ], "status_breakdown": [ { "status": "operating", "unit_count": 5 } ], "name": "Zaporizhzhia Ferroalloys Plant", "facility_type": "steel_plant", "facility_class": "heavy_industry", "source_silo": "gem", "country_iso3": "UKR", "lat": 47.86, "lon": 35.1, "status": "operating", "status_source": "operating", "status_sources": [ "operating" ], "capacity_mw": null, "owners": [ { "entity_id": "e_e3369180240c3a9e", "name": "Dniprospetsstal Plant PJSC" } ], "attributes": {}, "detail_url": "/api/v2/facilities/s_8dead1adbc3b3684", "owner_portfolio_url": "/api/v2/facilities?owner_entity_id=e_e3369180240c3a9e" } ], "meta": { "granularity": "site", "count_unit": "canonical_sites" }, "pagination": { "limit": 1, "offset": 0, "returned": 1, "has_more": false, "next_cursor": null }, "applied_filters": { "granularity": "site", "limit": 1 } } } } } } }, "400": { "description": "Invalid facility filter (unknown type / class / source / sort).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Invalid type 'power_plant'. Accepted: coal_plant, oil_gas_plant, nuclear_plant, …, port, data_center", "code": "INVALID_ENUM" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "403": { "description": "The caller's plan does not carry the can_use_facilities entitlement (Analyst plan and up).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Your plan does not include the Facilities data source.", "code": "PLAN_REQUIRED" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch facilities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch facilities.", "code": "INTERNAL_ERROR" } } } } } } }, "x-plan-feature": "can_use_facilities" } }, "/api/v2/facilities/{facility_id}": { "get": { "operationId": "get-facility-v2", "summary": "Get Facility", "description": "Returns a canonical physical site with unit count, unit identifiers and status breakdown. A legacy registry-unit id resolves to the same parent site.", "tags": [ "Facilities" ], "parameters": [ { "name": "facility_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The facility id." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityDetailResponse" }, "examples": { "facility": { "value": { "success": true, "facility": { "facility_id": "f_581be6619920626d", "name": "Alibaba Zhangbei", "facility_type": "data_center", "facility_class": "digital_infrastructure", "source_silo": "epoch", "country_iso3": "CHN", "lat": null, "lon": null, "address": "Alibaba Zhangbei Yun Calculation Data Center, Zhangbei County, Zhangjiakou, Hebei, China", "status": null, "capacity_mw": 169, "owners": [ { "entity_id": "e_a4db9cd53edee666", "name": "Alibaba" } ], "attributes": { "current_power_mw": "169", "current_h100e": "132895.4", "chip_types": "" }, "first_seen_date": "2026-07-09", "last_seen_date": "2026-07-09", "detail_url": "/api/v2/facilities/f_581be6619920626d", "owner_portfolio_url": "/api/v2/facilities?owner_entity_id=e_a4db9cd53edee666" }, "merge_history": [] } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "403": { "description": "The caller's plan does not carry the can_use_facilities entitlement (Analyst plan and up).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Your plan does not include the Facilities data source.", "code": "PLAN_REQUIRED" } } } } } }, "404": { "description": "No facility with that id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Facility not found.", "code": "NOT_FOUND" } } } } } }, "500": { "description": "Failed to fetch the facility.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch the facility.", "code": "INTERNAL_ERROR" } } } } } } }, "x-plan-feature": "can_use_facilities" } }, "/api/v2/facilities/{facility_id}/context": { "get": { "operationId": "get-facility-context-v2", "summary": "Facility context", "description": "A facility fused with its OWNER's media coverage, plus optional government exposure. Returns `owner_events` — events about the owner, NOT events located at the site. When the owner cannot be resolved or cannot be bridged to the news layer, the arrays are `null` rather than empty, so \"we did not look\" is never mistaken for \"we looked and found nothing\".\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `as_of` → 400 UNSUPPORTED_PARAM. Facility ownership is not vintaged — the directory records the latest known owner and prior owners are not yet reconstructable as-of, so an as_of result here would not be reproducible. Use instead: `/api/v2/intelligence/gpr?as_of=`, `/api/v2/macro/*?as_of=`.\n\n", "tags": [ "Facilities" ], "parameters": [ { "name": "facility_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The facility id." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "default": 7 }, "description": "Owner-coverage window in days, max 30. Also accepts: `window`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "30", "x-aliases": [ "window" ] }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Explicit start of the owner-coverage window. Also accepts: `start_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-01", "x-aliases": [ "start_date" ] }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Explicit end of the owner-coverage window. Also accepts: `end_date`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-04", "x-aliases": [ "end_date" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Maximum owner events to attach. Default 10, max 50. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "10" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gov" ] } }, "description": "Optional extra blocks. `gov` attaches the owner's federal-award / FARA / sanctions footprint. An unentitled plan degrades the block to null with a `sources_unavailable` entry — it never 403s the whole response. Full value list: https://docs.gdeltcloud.com/reference/enums#facility_context_include", "example": "gov" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid parameter" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Plan does not include this surface" }, "429": { "description": "Quota or rate limit exceeded" }, "500": { "description": "Server error" } }, "x-plan-feature": "can_use_facilities" } }, "/api/v2/facilities/{facility_id}/units": { "get": { "operationId": "get-facility-units-v2", "summary": "List Facility registry units", "description": "Lists the source registry units belonging to a canonical physical site. A canonical site id or any legacy unit id may identify the site.", "tags": [ "Facilities" ], "parameters": [ { "name": "facility_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The facility id." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } }, "examples": { "default": { "summary": "List source registry units for a site", "value": { "success": true, "data": [] } } } } } }, "400": { "description": "Invalid or unsupported parameter (see `code` and `details`)" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Plan does not include this surface" }, "404": { "description": "Not found" }, "429": { "description": "Quota or rate limit exceeded" }, "500": { "description": "Server error" } }, "x-plan-feature": "can_use_facilities" } }, "/api/v2/geo/admin1": { "get": { "operationId": "list-admin1-v2", "summary": "List Admin1 Values", "description": "Discover valid state/province/admin1 values for one country. This endpoint is intentionally country-scoped and does not return the full admin1 catalog.", "tags": [ "Geography" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country to enumerate admin1 (state/province) values for — required. Accepts a country name (`France`), ISO-2 (`FR`), or ISO-3 (`FRA`) via the shared `resolveCountryInput` layer; an unresolvable or missing value returns `400 INVALID_COUNTRY`.", "schema": { "type": "string" }, "example": "France" } ], "responses": { "200": { "description": "Country-scoped admin1 values", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "country": { "type": "string" }, "admin1": { "type": "array", "items": { "type": "string" } } } }, "examples": { "admin1": { "value": { "success": true, "country": "France", "admin1": [ "Auvergne-Rhone-Alpes", "Bretagne", "Ile-de-France", "Normandie", "Provence-Alpes-Cote d Azur" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/geo/admin1\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/gov/awards": { "get": { "operationId": "get-gov-awards-v2", "summary": "Federal Awards (USAspending)", "description": "US federal award exposure for an entity — USAspending prime awards (contracts + grants) resolved to the entity spine. Look a subject up three ways (at least one is required): a resolved spine `entity_id` (`entity=`), a SAM.gov Unique Entity Identifier (`uei=`), or a fuzzy recipient name (`recipient=`). Returns an aggregate `summary` (total obligated USD, award + recipient counts) with a per-UEI `recipient_rollups` breakdown (top 25 by obligated USD, each with its awarding agencies and first/last action dates), plus the recent `awards` timeline — every row cited to its USAspending permalink. **D&B carve-out:** keyed on the SAM.gov UEI only — Dun & Bradstreet's DUNS number and corporate-family (parent) tree are never ingested or surfaced. Plan-gated: requires the `can_use_gov` entitlement (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Reads are bounded key-prefix lookups on the current award snapshot (no all-time scan).", "tags": [ "Government" ], "parameters": [ { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A resolved spine entity id (`e_…` / `wiki:…` / `cik:…`). A bare name is rejected with 400 INVALID_ENTITY_ID — resolve it first via GET /api/v2/search. Returns that entity's federal awards.", "example": "e_7e9bc31057830fbf" }, { "name": "uei", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A SAM.gov Unique Entity Identifier (12-char). Case-insensitive.", "example": "K8YHEXAMPLE01" }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fuzzy (case-insensitive substring) recipient-name match — no id required.", "example": "Lockheed" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Award-timeline rows to return (max 500). The summary and recipient_rollups aggregate across ALL matching awards regardless of this cap." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovAwardsResponse" }, "examples": { "awards": { "value": { "query": { "entity": null, "uei": null, "recipient": "Lockheed", "limit": 25 }, "summary": { "recipients": 34, "total_awards": 4821, "total_obligated": 342118904233, "recipient_rollups": [ { "recipient_uei": "K8YHEXAMPLE01", "recipient_name": "LOCKHEED MARTIN CORPORATION", "entity_id": "e_7e9bc31057830fbf", "award_count": 3120, "total_obligated": 301884221190, "agency_count": 12, "top_agencies": [ "Department of Defense", "National Aeronautics and Space Administration", "Department of State" ], "first_action_date": "1998-03-11", "last_action_date": "2026-06-28" } ] }, "awards": [ { "award_id": "CONT_AWD_FA860124C0001_9700", "recipient_name": "LOCKHEED MARTIN CORPORATION", "recipient_uei": "K8YHEXAMPLE01", "entity_id": "e_7e9bc31057830fbf", "award_amount": 1200000000, "awarding_agency": "Department of Defense", "awarding_sub_agency": "Department of the Air Force", "award_group": "contract", "award_type": "DEFINITIVE CONTRACT", "action_date": "2026-06-28", "end_date": "2031-06-27", "source_url": "https://www.usaspending.gov/award/CONT_AWD_FA860124C0001_9700" } ], "meta": { "source": "gov.usaspending_awards", "attributions": [ { "source": "USAspending.gov", "source_url": "https://www.usaspending.gov/", "license": "US Public Domain", "note": "Federal award data is US public domain. Keyed on SAM.gov UEI; Dun & Bradstreet fields (DUNS, corporate-family tree) are excluded by license." } ] } } } } } } }, "400": { "description": "Missing subject (need entity / uei / recipient), or a bare name passed to entity=.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "gov \"entity\"/\"entity_id\" must be a resolved entity id (e.g. e_… or wiki:…). \"Lockheed\" looks like a name — resolve it via GET /api/v2/search?q=Lockheed and pass its entity_id, or use recipient= for a fuzzy recipient-name match, or uei= for a SAM.gov UEI.", "code": "INVALID_ENTITY_ID" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "403": { "description": "The caller's plan does not carry the can_use_gov entitlement (Markets plan and up).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Government exposure (federal awards) is not included in your plan. Upgrade at https://gdeltcloud.com/pricing to unlock it.", "code": "PLAN_REQUIRED" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch government exposure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch government exposure.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/gov/fara": { "get": { "operationId": "get-gov-fara-v2", "summary": "Foreign Agents (FARA)", "description": "US foreign-influence graph — DOJ FARA registrations linking a US registrant (law/lobby/PR firm) to the foreign principal it represents, resolved to the entity spine. Filter by a resolved `entity` (matches EITHER side of the link), a fuzzy `registrant` or `foreign_principal` name, or a `country`; `adversary_only` restricts to adversary governments and `sanctioned_only` to the killer cross — US firms registered as agents for a **sanctioned** entity (the foreign principal is matched to our screening lists — OFAC SDN / BIS Entity / DoD 1260H / OFAC CMIC / UK — with the specific `fp_sanction_lists` + `fp_sanction_programs`). At least one filter is required. Plan-gated: requires `can_use_gov` (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. US Public Domain (DOJ NSD FARA eFile).", "tags": [ "Government" ], "parameters": [ { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A resolved spine entity id (`e_…`). Matches the registrant OR the foreign principal side of the link.", "example": "e_1a2b3c4d5e6f7a8b" }, { "name": "registrant", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fuzzy (case-insensitive) US-registrant name match.", "example": "Hogan Lovells" }, { "name": "foreign_principal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fuzzy foreign-principal name match.", "example": "Huawei" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country/location represented, as published by FARA (upper-case). Observed vocabulary, measured 2026-08-10 (265 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/gov/fara?entity= — read `country` on each foreign principal`. The foreign principal's country AS FARA SPELLS IT — `KOREA, SOUTH`, `MYANMAR (BURMA)`, `GREAT BRITAIN`. The `country=` filter resolves your input to ISO-3 and then matches every stored spelling that maps to it, so you may send an ISO code or an English name; these are the raw values you will see in a response. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#fara_country", "example": "RUSSIA" }, { "name": "adversary_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to adversary-government links (RU/CN/IR/KP/SY/CU/VE/BY/MM)." }, { "name": "sanctioned_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to links whose foreign principal is on a sanctions/restricted list." }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to still-active registrations (no termination date)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Link rows to return (max 500). Summary aggregates across ALL matching links." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovFaraResponse" }, "examples": { "fara": { "value": { "query": { "entity": null, "registrant": null, "foreign_principal": null, "country": null, "adversary_only": false, "sanctioned_only": true, "active_only": false, "limit": 25 }, "summary": { "links": 73, "registrants": 68, "foreign_principals": 57, "countries": 22, "adversary_links": 41, "sanctioned_links": 73, "active_links": 6 }, "links": [ { "registration_number": "6560", "registrant_name": "Ruder Finn, Inc.", "registrant_entity_id": "e_1a2b3c4d5e6f7a8b", "foreign_principal": "Huawei Technologies Co., Ltd.", "foreign_principal_entity_id": "e_9f8e7d6c5b4a3f2e", "country": "CHINA", "country_adversary": 1, "fp_sanctioned": 1, "fp_sanction_lists": [ "dod_1260h", "csl_bis_entity", "csl_ofac_cmic" ], "fp_sanction_programs": [ "1260H", "CMIC-EO13959" ], "fp_registration_date": "2024-05-14", "fp_termination_date": "", "is_active": 1, "source_url": "https://efile.fara.gov/ords/fara/f?p=1381:200:::NO:RP,200:P200_REG_NUMBER:6560" } ], "meta": { "source": "gov.fara_foreign_principals", "attributions": [ { "source": "DOJ NSD — FARA eFile (Foreign Agents Registration Act)", "source_url": "https://efile.fara.gov/", "license": "US Public Domain", "note": "Foreign Agents Registration Act filings are US public domain (Department of Justice). One row per (US registrant, foreign principal) link." } ] } } } } } } }, "400": { "description": "Missing filter — need one of entity / registrant / foreign_principal / country / adversary_only / sanctioned_only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "one of entity= (resolved entity_id), registrant= (fuzzy name), foreign_principal= (fuzzy name), country= (e.g. RUSSIA), adversary_only=true, or sanctioned_only=true is required.", "code": "MISSING_PARAM" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "403": { "description": "The caller's plan does not carry the can_use_gov entitlement (Markets plan and up).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Government exposure (federal awards) is not included in your plan. Upgrade at https://gdeltcloud.com/pricing to unlock it.", "code": "PLAN_REQUIRED" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch FARA links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch FARA links.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/filings": { "get": { "operationId": "list-filings-v2", "summary": "List SEC filings", "tags": [ "Filings" ], "description": "List the SEC EDGAR filing index by company (CIK), form type, name, and date window. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Anchor date YYYY-MM-DD (use with days)." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30)." }, { "name": "cik", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One or more CIK numbers (comma-separated)." }, { "name": "form_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One or more form types (e.g. 10-K,8-K,4). Observed vocabulary, measured 2026-08-10 (262 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/filings/summary?group_by=form_type`. SEC form types are an open vocabulary: 264 distinct values appeared in a single 30-day window, and 424B2 alone was 36.3% of them. Any closed list here would be wrong within a quarter, so this filter accepts anything and returns an empty result for a form type the window does not contain. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#sec_form_type" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company-name search." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filer business-address country — name / ISO-2 / ISO-3 / alias, comma-separated. Filters on biz_country_iso2, which is populated for ~45% of filings and is almost entirely US, so non-US values such as CN/JP currently return 0 rows. Full value list: https://docs.gdeltcloud.com/reference/enums#country" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region expanded to an ISO-3 country set, then matched against the filer's biz_country_iso2." }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent expanded to an ISO-3 country set, then matched against the filer's biz_country_iso2." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent", "filer" ], "default": "recent" }, "description": "recent | filer. Full value list: https://docs.gdeltcloud.com/reference/enums#filings_sort" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "A page of filings, most recent first (or grouped by filer when sort=filer). Each row: accession_no, cik, company_name, form_type, file_date, is_amendment (bool), primary_doc_url, biz_country_iso2 (when known), items (form-specific item tags, when present). Standard envelope: { success, data, pagination, sort, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "accession_no": { "type": "string" }, "cik": { "type": "integer" }, "company_name": { "type": "string" }, "form_type": { "type": "string" }, "file_date": { "type": "string" }, "is_amendment": { "type": "boolean" }, "primary_doc_url": { "type": "string" }, "biz_country_iso2": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "sort": { "type": "string" }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "cik": { "type": "array", "items": { "type": "integer" } }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings — example response", "value": { "success": true, "data": [ { "accession_no": "0000065270-26-000058", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "form_type": "8-K", "file_date": "2026-06-18", "is_amendment": false, "primary_doc_url": "https://www.sec.gov/Archives/edgar/data/65270/000006527026000058/mei-20260618.htm", "biz_country_iso2": "US", "items": [ "2.02", "9.01" ] }, { "accession_no": "0000065270-26-000041", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "form_type": "10-K", "file_date": "2026-06-12", "is_amendment": false, "primary_doc_url": "https://www.sec.gov/Archives/edgar/data/65270/000006527026000041/mei-20260501.htm", "biz_country_iso2": "US" } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null }, "sort": "recent", "applied_filters": { "date_start": "2026-05-30", "date_end": "2026-06-28", "cik": [ 65270 ], "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/summary": { "get": { "operationId": "summarize-filings-v2", "summary": "Summarize filings", "tags": [ "Filings" ], "description": "Rollup of filings by form type, date, or filer — counts + distinct filers. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Anchor date YYYY-MM-DD (use with days)." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30)." }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "form_type", "date", "filer" ], "default": "form_type" }, "description": "form_type | date | filer. Full value list: https://docs.gdeltcloud.com/reference/enums#filings_summary_group_by" }, { "name": "form_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one or more form types. Observed vocabulary, measured 2026-08-10 (262 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/filings/summary?group_by=form_type`. SEC form types are an open vocabulary: 264 distinct values appeared in a single 30-day window, and 424B2 alone was 36.3% of them. Any closed list here would be wrong within a quarter, so this filter accepts anything and returns an empty result for a form type the window does not contain. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#sec_form_type" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filer business-address country — name / ISO-2 / ISO-3 / alias, comma-separated. Filters on biz_country_iso2, which is populated for ~45% of filings and is almost entirely US, so non-US values such as CN/JP currently return 0 rows." }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region expanded to an ISO-3 country set, then matched against the filer's biz_country_iso2." }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent expanded to an ISO-3 country set, then matched against the filer's biz_country_iso2." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "description": "Max buckets returned; pagination.truncated=true when total_buckets exceeds it." } ], "responses": { "200": { "description": "Filing counts bucketed by group_by (form_type | date | filer), highest count first. Each row carries the bucket key (form_type, date, or cik), filings (count) and — except when grouping by filer — filers (distinct CIKs). Envelope: { success, group_by, data, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "group_by": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "form_type": { "type": "string" }, "filings": { "type": "integer" }, "filers": { "type": "integer" } } } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/summary — example response", "value": { "success": true, "group_by": "form_type", "data": [ { "form_type": "8-K", "filings": 4821, "filers": 3970 }, { "form_type": "10-Q", "filings": 1638, "filers": 1602 } ], "applied_filters": { "date_start": "2026-05-30", "date_end": "2026-06-28", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/events": { "get": { "operationId": "list-material-events-v2", "summary": "Material events (8-K)", "tags": [ "Filings" ], "description": "Dated 8-K material corporate events (M&A, material agreements, executive changes, bankruptcies, delistings, impairments) extracted from 8-K bodies, with counterparties resolved into the entity spine. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Anchor date YYYY-MM-DD (use with days)." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30, default 30)." }, { "name": "cik", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One or more CIK numbers (comma-separated)." }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "acquisition", "disposition", "material_agreement", "executive_change", "results", "guidance", "restructuring", "impairment", "delisting", "bankruptcy", "other" ] }, "description": "Filter to one classified event type. Full set: acquisition | disposition | material_agreement | executive_change | results | guidance | restructuring | impairment | delisting | bankruptcy | other. Matched exactly; omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#filings_event_type" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on the event headline." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page (1–200, default 50)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "A page of 8-K material events, most recent first. Each row: event_uid, cik, company_name, accession_no, item_code, event_type, headline, counterparties (names mentioned in the disclosure), amount_text (deal/transaction value as disclosed, when present), resolved_entity_ids (counterparties resolved into the entity spine), confidence, event_date. Standard envelope: { success, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "event_uid": { "type": "string" }, "cik": { "type": "integer" }, "company_name": { "type": "string" }, "accession_no": { "type": "string" }, "item_code": { "type": "string" }, "event_type": { "type": "string" }, "headline": { "type": "string" }, "counterparties": { "type": "array", "items": {} }, "amount_text": { "type": "string" }, "resolved_entity_ids": { "type": "array", "items": {} }, "confidence": { "type": "number" }, "event_date": { "type": "string" }, "model": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "cik": { "type": "array", "items": { "type": "integer" } }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/events — example response", "value": { "success": true, "data": [ { "event_uid": "9c8b7a6d5e4f30211029384756abcdef", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "accession_no": "0000065270-26-000058", "item_code": "2.02", "event_type": "results", "headline": "Methode Electronics reported fiscal fourth-quarter net sales of $260.1 million and a net loss of $0.79 per share, citing softer automotive demand and program transition costs.", "counterparties": [], "amount_text": "$260.1 million", "resolved_entity_ids": [], "confidence": 0.93, "event_date": "2026-06-18", "model": "gpt-5.4-mini:8k:v1" }, { "event_uid": "1f2e3d4c5b6a70819283746556fedcba", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "accession_no": "0000065270-26-000052", "item_code": "5.02", "event_type": "executive_change", "headline": "Methode Electronics announced the appointment of Jonathan B. DeGaynor as President and Chief Executive Officer, effective June 9, 2026, succeeding the interim CEO.", "counterparties": [ "Jonathan B. DeGaynor" ], "amount_text": null, "resolved_entity_ids": [ "ent_7e3a1c89d2b4" ], "confidence": 0.96, "event_date": "2026-06-09", "model": "gpt-5.4-mini:8k:v1" } ], "pagination": { "limit": 50, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-05-30", "date_end": "2026-06-28", "cik": [ 65270 ], "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/{cik}": { "get": { "operationId": "get-filer-v2", "summary": "Filer profile", "tags": [ "Filings" ], "description": "A filer's identity, ticker, resolved entity_id, recent filings, and XBRL financial highlights. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SEC CIK number." } ], "responses": { "200": { "description": "Filer profile for the CIK. Envelope: { success, cik, company_name, ticker (or null), entity_id (entity-spine id, or null), recent_filings (up to 25 recent rows: accession_no, company_name, form_type, file_date, is_amendment, primary_doc_url), risk_factors (disclosed Item-1A risk themes), xbrl_highlights (headline concepts: concept, unit, value, period_end) }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cik": { "type": "integer" }, "company_name": { "type": "string" }, "ticker": { "type": "string" }, "entity_id": { "type": "string" }, "recent_filings": { "type": "array", "items": { "type": "object", "properties": { "accession_no": { "type": "string" }, "cik": { "type": "integer" }, "company_name": { "type": "string" }, "form_type": { "type": "string" }, "file_date": { "type": "string" }, "is_amendment": { "type": "boolean" }, "primary_doc_url": { "type": "string" } } } }, "risk_factors": { "type": "array", "items": { "type": "string" } }, "business": { "type": "object", "properties": { "description": { "type": "string" }, "segments": { "type": "array", "items": { "type": "string" } }, "products_services": { "type": "array", "items": { "type": "string" } } } }, "xbrl_highlights": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string" }, "unit": { "type": "string" }, "value": { "type": "integer" }, "period_end": { "type": "string" } } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/{cik} — example response", "value": { "success": true, "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "ticker": "MEI", "entity_id": "ent_8f2c1a7d9b4e", "recent_filings": [ { "accession_no": "0000065270-26-000058", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "form_type": "8-K", "file_date": "2026-06-18", "is_amendment": false, "primary_doc_url": "https://www.sec.gov/Archives/edgar/data/65270/000006527026000058/mei-20260618.htm" }, { "accession_no": "0000065270-26-000041", "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "form_type": "10-K", "file_date": "2026-06-12", "is_amendment": false, "primary_doc_url": "https://www.sec.gov/Archives/edgar/data/65270/000006527026000041/mei-20260501.htm" } ], "risk_factors": [ "supply_concentration", "geopolitical" ], "business": { "description": "Methode Electronics is a global developer of custom-engineered and application-specific products and solutions utilizing electrical, radio remote control, electronic, wireless and sensing technologies, serving automotive, industrial, and commercial vehicle markets.", "segments": [ "Automotive", "Industrial", "Interface", "Medical" ], "products_services": [ "user interface assemblies", "LED lighting", "power distribution units", "sensors" ] }, "xbrl_highlights": [ { "concept": "Revenue", "unit": "USD", "value": 1049800000, "period_end": "2026-05-02" }, { "concept": "Assets", "unit": "USD", "value": 1387500000, "period_end": "2026-05-02" }, { "concept": "NetIncomeLoss", "unit": "USD", "value": -28400000, "period_end": "2026-05-02" }, { "concept": "StockholdersEquity", "unit": "USD", "value": 612300000, "period_end": "2026-05-02" } ] } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/{cik}/relations": { "get": { "operationId": "get-filer-relations-v2", "summary": "Filer relations (LLM)", "tags": [ "Filings" ], "description": "Subsidiary / supplier / customer / jurisdiction edges for a filer, derived from filing text through GDELT Cloud's proprietary AI pipeline and resolved to entity_ids with evidence. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SEC CIK number." }, { "name": "rel_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "subsidiary", "supplier", "customer", "counterparty", "partner", "jurisdiction_exposure", "risk_factor" ] }, "description": "Filter to one relation kind: subsidiary | supplier | customer | counterparty | partner | jurisdiction_exposure | risk_factor (Item 1A risk themes). Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#filings_rel_type" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "Vietnam" }, "description": "Filter to relation edges whose counterparty (object) jurisdiction matches this country — useful on `jurisdiction_exposure` edges. Accepts a country name (`Vietnam`), ISO-2 (`VN`), or ISO-3 (`VNM`) via the shared `resolveCountryInput` layer, matched against the edge's `object_country_iso3`; an unresolvable value returns `400 INVALID_COUNTRY`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Rows per page (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "A page of LLM-extracted relation edges, by rel_type then confidence. Each row: rel_type, source, subject_name, object_name, object_country_iso3, object_commodity, ownership_pct (or null), evidence (supporting quote), resolved_entity_id (entity-spine id, when resolved), confidence (0–1), model (extraction model version), accession_no. Envelope: { success, cik, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cik": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "relation_uid": { "type": "string" }, "rel_type": { "type": "string" }, "source": { "type": "string" }, "subject_name": { "type": "string" }, "object_name": { "type": "string" }, "object_country_iso3": { "type": "string" }, "object_commodity": {}, "ownership_pct": { "type": "integer" }, "amount_usd": {}, "amount_text": {}, "pct_value": {}, "evidence": { "type": "string" }, "resolved_entity_id": { "type": "string" }, "confidence": { "type": "number" }, "model": { "type": "string" }, "accession_no": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "cik": { "type": "integer" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/{cik}/relations — example response", "value": { "success": true, "cik": 65270, "data": [ { "relation_uid": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "rel_type": "subsidiary", "source": "ex21", "subject_name": "Methode Electronics, Inc.", "object_name": "Hetronic Germany GmbH", "object_country_iso3": "DEU", "object_commodity": null, "ownership_pct": 100, "amount_usd": null, "amount_text": null, "pct_value": null, "evidence": "Hetronic Germany GmbH (Germany) — 100% owned, included in the list of subsidiaries filed as Exhibit 21.1 to this Annual Report on Form 10-K.", "resolved_entity_id": "ent_4d9a2f31c7b8", "confidence": 0.97, "model": "gpt-5.4-nano:ex21:v1", "accession_no": "0000065270-26-000041" }, { "relation_uid": "f0e9d8c7b6a51403928f7e6d5c4b3a21", "rel_type": "supplier", "source": "item1", "subject_name": "Methode Electronics, Inc.", "object_name": "Taiwan Semiconductor Manufacturing Company", "object_country_iso3": "TWN", "object_commodity": "semiconductors", "ownership_pct": null, "amount_usd": 84000000, "amount_text": "approximately $84 million", "pct_value": null, "evidence": "We source a significant portion of our application-specific integrated circuits from foundry partners in Taiwan, and a disruption in that supply could materially affect our Automotive segment.", "resolved_entity_id": "ent_2b7c9e14a6d3", "confidence": 0.84, "model": "gpt-5.4-mini:item1:v1", "accession_no": "0000065270-26-000041" } ], "pagination": { "limit": 50, "cursor": null, "next_cursor": null }, "applied_filters": { "cik": 65270, "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/{cik}/facts": { "get": { "operationId": "get-filer-facts-v2", "summary": "Filer XBRL facts", "tags": [ "Filings" ], "description": "XBRL structured financial facts for a filer — a concept time series for exposure sizing. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SEC CIK number." }, { "name": "concept", "in": "query", "required": false, "schema": { "type": "string" }, "description": "XBRL concept (e.g. Revenues, NetIncomeLoss)." }, { "name": "taxonomy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Taxonomy (us-gaap | dei)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "A page of XBRL facts, by concept then period_end. Each row: concept, taxonomy, unit, period_end, fp (fiscal period, or null), fy (fiscal year, or null), value, form_type (or null), filed_date, accession_no. Envelope: { success, cik, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cik": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string" }, "taxonomy": { "type": "string" }, "unit": { "type": "string" }, "period_end": { "type": "string" }, "fp": { "type": "string" }, "fy": { "type": "integer" }, "value": { "type": "integer" }, "form_type": { "type": "string" }, "filed_date": { "type": "string" }, "accession_no": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "cik": { "type": "integer" }, "concept": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/{cik}/facts — example response", "value": { "success": true, "cik": 65270, "data": [ { "concept": "Revenues", "taxonomy": "us-gaap", "unit": "USD", "period_end": "2026-05-02", "fp": "FY", "fy": 2026, "value": 1049800000, "form_type": "10-K", "filed_date": "2026-06-12", "accession_no": "0000065270-26-000041" }, { "concept": "Revenues", "taxonomy": "us-gaap", "unit": "USD", "period_end": "2025-04-26", "fp": "FY", "fy": 2025, "value": 1114700000, "form_type": "10-K", "filed_date": "2025-06-25", "accession_no": "0000065270-25-000039" } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "cik": 65270, "concept": "Revenues", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/filings/resolve": { "get": { "operationId": "resolve-filing-entity-v2", "summary": "Resolve to CIK", "description": "Resolve a company name, ticker, or CIK to SEC filing identities and terminal spine entities.", "tags": [ "Filings" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company-name query. `name` and `search` are aliases. Also accepts: `name`, `search`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "CNOOC", "x-aliases": [ "name", "search" ] }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact ticker symbol. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "AAPL" }, { "name": "cik", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SEC CIK, with or without zero padding. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0000320193" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Maximum candidates returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "10" }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Minimum fuzzy-name candidate score. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0.6" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Resolution result. `query` echoes the { ticker, cik, name } you passed; `resolved` is { cik, entity_id } (entity_id may be null when the filer is not yet on the entity spine) or null when nothing matched. Envelope: { success, query, resolved }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "object", "properties": { "ticker": { "type": "string" }, "cik": {}, "name": {} } }, "resolved": { "type": "object", "properties": { "cik": { "type": "integer" }, "company_name": { "type": "string" }, "ticker": { "type": "string" }, "entity_id": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/filings/resolve — example response", "value": { "success": true, "query": { "ticker": "MEI", "cik": null, "name": null }, "resolved": { "cik": 65270, "company_name": "METHODE ELECTRONICS INC", "ticker": "MEI", "entity_id": "ent_8f2c1a7d9b4e" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-plan-feature": "can_use_filings" } }, "/api/v2/gleif/entities": { "get": { "operationId": "get-gleif-entities-v2", "summary": "GLEIF legal entities (Open Feed)", "description": "The GLEIF Global LEI Index — 3.39M legal entities with their registered name, jurisdiction, entity and registration status, legal form and registration authority, served close to as-published. **At least one filter is required**: the feed covers 3.39M records, so an unfiltered listing is refused with 400 FILTER_REQUIRED rather than served slowly. `name` matches the normalized legal name exactly or by prefix (never a substring scan). Plan-gated: requires the `can_use_gleif` entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries `meta.attributions[]` with GLEIF's required non-endorsement notice.", "tags": [ "Reference Data" ], "parameters": [ { "name": "lei", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One or more LEIs, comma-separated (max 100). Each must pass the ISO 17442 check digit.", "example": "213800FD9J2IHTA7YX78" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legal name — normalized-exact or prefix match. Not a substring search.", "example": "Siemens" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-3 country of the legal address (our house convention). Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "DEU" }, { "name": "jurisdiction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GLEIF's raw legal jurisdiction — alpha-2 or subdivision (`US-CA`). Observed vocabulary, measured 2026-08-10 (307 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/gleif/entities?country=&limit=1 — read `legal_jurisdiction``. GLEIF's legal jurisdiction as published — ISO 3166-1 alpha-2 plus alpha-2/subdivision forms such as `US-CA`. Uppercased but NOT validated by the serve layer, unlike the three GLEIF status enums beside it, so an unlisted jurisdiction returns an empty 200. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#gleif_jurisdiction", "example": "US-DE" }, { "name": "entity_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "NULL" ] }, "description": "Entity status. Validated against the allowed set; a bad value returns 400 INVALID_ENUM with details.accepted_values. Full value list: https://docs.gdeltcloud.com/reference/enums#gleif_entity_status", "example": "ACTIVE" }, { "name": "registration_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ISSUED", "LAPSED", "PENDING_TRANSFER", "PENDING_ARCHIVAL", "DUPLICATE", "RETIRED", "ANNULLED", "CANCELLED", "TRANSFERRED", "PENDING_VALIDATION", "PUBLISHED", "MERGED" ] }, "description": "LEI registration status — e.g. ISSUED, LAPSED, RETIRED. A LAPSED registration does NOT mean the company ceased to exist. Full value list: https://docs.gdeltcloud.com/reference/enums#gleif_registration_status", "example": "ISSUED" }, { "name": "entity_category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GENERAL", "BRANCH", "FUND", "SOLE_PROPRIETOR", "RESIDENT_GOVERNMENT_ENTITY", "INTERNATIONAL_ORGANIZATION" ] }, "description": "GLEIF entity category — e.g. GENERAL, FUND, BRANCH, SOLE_PROPRIETOR. Full value list: https://docs.gdeltcloud.com/reference/enums#gleif_entity_category", "example": "GENERAL" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Rows to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Offset cursor; echo `pagination.next_cursor` to page." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Matching LEI records with `pagination`, `applied_filters` and `meta.attributions[]`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter — `code` is one of INVALID_LEI, INVALID_ENUM, INVALID_LIMIT or FILTER_REQUIRED, with `details.accepted_values` where an enum was rejected." }, "403": { "description": "PLAN_REQUIRED — the caller's plan lacks `can_use_gleif`." } } } }, "/api/v2/gleif/entities/{lei}": { "get": { "operationId": "get-gleif-entity-by-lei-v2", "summary": "One GLEIF entity, with its relationships and ISINs", "description": "The full Level-1 record for a single LEI plus its Level-2 relationships, any declared reporting exceptions, and its LEI↔ISIN mappings. A structurally impossible LEI returns 400 INVALID_LEI (it fails the ISO 17442 check digit); a well-formed LEI we do not hold returns 404. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists. Plan-gated: requires the `can_use_gleif` entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries `meta.attributions[]` with GLEIF's required non-endorsement notice.", "tags": [ "Reference Data" ], "parameters": [ { "name": "lei", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A 20-character LEI passing the ISO 17442 check digit.", "example": "7LTWFZYICNSX8D621K86" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The L1 record with `relationships[]`, `reporting_exceptions[]` and `isins[]`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter — `code` is one of INVALID_LEI, INVALID_ENUM, INVALID_LIMIT or FILTER_REQUIRED, with `details.accepted_values` where an enum was rejected." }, "403": { "description": "PLAN_REQUIRED — the caller's plan lacks `can_use_gleif`." } } } }, "/api/v2/gleif/relationships": { "get": { "operationId": "get-gleif-relationships-v2", "summary": "GLEIF Level-2 relationships", "description": "Parent/child relationship records as filed with the Global LEI System. `lei` matches EITHER endpoint. Note the direction convention in the source data: the start node is the CHILD and the end node is the PARENT. Corporate hierarchy as reported to the Global LEI System: accounting consolidation under IFRS/US-GAAP, not percentage ownership and not beneficial ownership. Natural persons are out of scope, and reporting is partial — an absent parent usually means the filer declared a reporting exception rather than that none exists. Plan-gated: requires the `can_use_gleif` entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries `meta.attributions[]` with GLEIF's required non-endorsement notice.", "tags": [ "Reference Data" ], "parameters": [ { "name": "lei", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match relationships where this LEI is either endpoint. Must pass the ISO 17442 check digit.", "example": "7LTWFZYICNSX8D621K86" }, { "name": "relationship_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "IS_DIRECTLY_CONSOLIDATED_BY", "IS_ULTIMATELY_CONSOLIDATED_BY", "IS_INTERNATIONAL_BRANCH_OF", "IS_FUND-MANAGED_BY", "IS_SUBFUND_OF", "IS_FEEDER_TO" ] }, "description": "e.g. IS_DIRECTLY_CONSOLIDATED_BY, IS_ULTIMATELY_CONSOLIDATED_BY, IS_INTERNATIONAL_BRANCH_OF. Validated — 400 INVALID_ENUM otherwise. Full value list: https://docs.gdeltcloud.com/reference/enums#gleif_relationship_type", "example": "IS_DIRECTLY_CONSOLIDATED_BY" }, { "name": "relationship_status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ACTIVE or INACTIVE. Observed vocabulary, measured 2026-08-10 (3 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/gleif/relationships?lei= — read `status``. The status of a GLEIF relationship record. Unlike `relationship_type` beside it, this one is uppercased and passed through unvalidated, so it is published as measured. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#gleif_relationship_status", "example": "ACTIVE" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Rows to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Offset cursor." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Relationship records with `pagination`, `applied_filters` and `meta`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter — `code` is one of INVALID_LEI, INVALID_ENUM, INVALID_LIMIT or FILTER_REQUIRED, with `details.accepted_values` where an enum was rejected." }, "403": { "description": "PLAN_REQUIRED — the caller's plan lacks `can_use_gleif`." } } } }, "/api/v2/gleif/isin": { "get": { "operationId": "get-gleif-isin-v2", "summary": "LEI ↔ ISIN mappings", "description": "Resolve an LEI to its issued ISINs, or an ISIN back to its LEI. One of `lei` or `isin` is required — the mapping table holds ~9M rows and an unfiltered listing is refused with 400 FILTER_REQUIRED. Plan-gated: requires the `can_use_gleif` entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Source: GLEIF Golden Copy, published under CC0 1.0. Every response carries `meta.attributions[]` with GLEIF's required non-endorsement notice.", "tags": [ "Reference Data" ], "parameters": [ { "name": "lei", "in": "query", "required": false, "schema": { "type": "string" }, "description": "LEI to resolve to ISINs.", "example": "7LTWFZYICNSX8D621K86" }, { "name": "isin", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISIN to resolve back to its LEI.", "example": "DE0005140008" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Rows to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Offset cursor." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "LEI↔ISIN pairs with `pagination` and `meta`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid parameter — `code` is one of INVALID_LEI, INVALID_ENUM, INVALID_LIMIT or FILTER_REQUIRED, with `details.accepted_values` where an enum was rejected." }, "403": { "description": "PLAN_REQUIRED — the caller's plan lacks `can_use_gleif`." } } } }, "/api/v2/energy/assets": { "get": { "operationId": "search-energy-assets-v2", "summary": "Search Energy Assets", "description": "Search Global Energy Monitor energy-infrastructure assets across all 15 trackers. Returns clean asset cards with native capacity, MW capacity where meaningful, normalized geography, ownership arrays, GEM Wiki URLs, and detail/API links.", "tags": [ "Energy" ], "parameters": [ { "$ref": "#/components/parameters/energyTracker" }, { "$ref": "#/components/parameters/energyCountry" }, { "$ref": "#/components/parameters/energyRegion" }, { "$ref": "#/components/parameters/energyContinent" }, { "$ref": "#/components/parameters/energyStatus" }, { "$ref": "#/components/parameters/energyOperatingOnly" }, { "$ref": "#/components/parameters/energyTier" }, { "$ref": "#/components/parameters/energyFuel" }, { "$ref": "#/components/parameters/energyCapacityMwMin" }, { "$ref": "#/components/parameters/energyCapacityMwMax" }, { "$ref": "#/components/parameters/energyStartYearMin" }, { "$ref": "#/components/parameters/energyStartYearMax" }, { "$ref": "#/components/parameters/energyRetiredYearMin" }, { "$ref": "#/components/parameters/energyRetiredYearMax" }, { "$ref": "#/components/parameters/energyEntity" }, { "$ref": "#/components/parameters/energyOwnerSearch" }, { "$ref": "#/components/parameters/energyOwnerEntityId" }, { "$ref": "#/components/parameters/energyBbox" }, { "$ref": "#/components/parameters/energyNear" }, { "$ref": "#/components/parameters/energySearch" }, { "$ref": "#/components/parameters/energyAssetClass" }, { "$ref": "#/components/parameters/energySort" }, { "$ref": "#/components/parameters/energyLimit" }, { "$ref": "#/components/parameters/energyCursor" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyAssetsListResponse" }, "examples": { "assets": { "value": { "success": true, "data": [ { "id": "oil_gas_plants:G100001090366", "gem_id": "G100001090366", "tracker": "oil_gas_plants", "tier": "main", "asset_class": "fixed", "name": "GW Ranch Energy Center", "name_local": null, "name_other": null, "status": "pre-construction", "status_detail": null, "start_year": 2028, "retired_year": null, "fuel": "fossil gas: natural gas", "capacity": { "value": 5000, "unit": "MW", "mw": 5000, "mw_secondary": null }, "geo": { "country": "United States", "country_iso3": "USA", "secondary_country_iso3": null, "region": "North America", "subregion": "Northern America", "continent": "North America", "state_province": "Texas", "city": "Fort Stockton", "lat": 31.16, "lon": -102.9, "location_accuracy": "exact" }, "owners_raw": "Pacifico GW LLC", "owners": [ { "name": "Pacifico GW LLC", "entity_id": "E100002021305", "stake_pct": null } ], "operators_raw": null, "operators": [], "parents_raw": "Pacifico Energy Group LLC", "parents": [ { "name": "Pacifico Energy Group LLC", "entity_id": "E100002021513", "stake_pct": null } ], "wiki_url": "https://www.gem.wiki/GW_Ranch_Energy_Center", "last_updated": "2026-01-15", "detail_url": "/energy/oil_gas_plants/G100001090366", "api_url": "/api/v2/energy/assets/oil_gas_plants/G100001090366" } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null }, "sort": "capacity_desc", "filters_echo": { "tracker": [ "oil_gas_plants" ], "country_iso3": [ "USA" ], "status": [ "pre-construction" ], "tier": [], "fuel": [], "capacity_mw_min": null, "capacity_mw_max": null, "start_year_min": null, "start_year_max": null, "owner_search": null, "owner_entity_id": null, "bbox": null, "near": null, "search": null, "operating_only": false, "asset_class": "fixed" } } } } } } }, "400": { "description": "Invalid Energy filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Invalid Energy filter.", "code": "INVALID_TRACKER" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch energy assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy assets.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/energy/assets/summary": { "get": { "operationId": "summarize-energy-assets-v2", "summary": "Summarize Energy Assets", "description": "Aggregate counts and MW rollups across Energy assets. Summary endpoints use structured filters only. capacity_mw fields are meaningful for power-generation trackers; constrain tracker when comparing capacity across unit families.", "tags": [ "Energy" ], "parameters": [ { "$ref": "#/components/parameters/energyGroupBy" }, { "$ref": "#/components/parameters/energyTracker" }, { "$ref": "#/components/parameters/energyCountry" }, { "$ref": "#/components/parameters/energyRegion" }, { "$ref": "#/components/parameters/energyContinent" }, { "$ref": "#/components/parameters/energyStatus" }, { "$ref": "#/components/parameters/energyOperatingOnly" }, { "$ref": "#/components/parameters/energyTier" }, { "$ref": "#/components/parameters/energyFuel" }, { "$ref": "#/components/parameters/energyCapacityMwMin" }, { "$ref": "#/components/parameters/energyCapacityMwMax" }, { "$ref": "#/components/parameters/energyStartYearMin" }, { "$ref": "#/components/parameters/energyStartYearMax" }, { "$ref": "#/components/parameters/energyRetiredYearMin" }, { "$ref": "#/components/parameters/energyRetiredYearMax" }, { "$ref": "#/components/parameters/energyEntity" }, { "$ref": "#/components/parameters/energyOwnerSearch" }, { "$ref": "#/components/parameters/energyOwnerEntityId" }, { "$ref": "#/components/parameters/energyBbox" }, { "$ref": "#/components/parameters/energyNear" }, { "$ref": "#/components/parameters/energyAssetClass" }, { "$ref": "#/components/parameters/energySummaryLimit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyAssetsSummaryResponse" }, "examples": { "summary": { "value": { "success": true, "group_by": "tracker", "data": [ { "bucket": "solar", "bucket_kind": "tracker", "asset_count": 103940, "capacity_mw_total": 210000, "capacity_mw_avg": 82.4, "capacity_mw_max": 3500, "capacity_mw_min": 1, "status_counts": { "operating": 65000, "construction": 7000, "proposed": 28000, "cancelled": 2000, "retired": 100 } } ] } } } } } }, "400": { "description": "Invalid Energy summary filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Invalid Energy summary filter.", "code": "INVALID_ENUM" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch energy summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy summary.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/energy/assets/map": { "get": { "operationId": "map-energy-assets-v2", "summary": "Map Energy Assets", "description": "Return map-ready Energy asset data. Without a single explicit country filter, the endpoint returns aggregate country-centroid rows. With exactly one country filter and no region or continent, it returns fine-grained asset pins capped by map_limit/fine_grained_limit.", "tags": [ "Energy" ], "parameters": [ { "name": "tracker", "in": "query", "required": false, "schema": { "type": "string", "example": "coal_plants,solar", "enum": [ "coal_plants", "coal_mines", "coal_terminals", "oil_gas_plants", "oil_gas_extraction", "lng_terminals", "nuclear", "geothermal", "bioenergy", "hydropower", "solar", "wind", "gas_pipelines", "oil_pipelines", "lng_carriers" ] }, "description": "Comma-separated GEM trackers. Valid values: coal_plants, coal_mines, coal_terminals, oil_gas_plants, oil_gas_extraction, lng_terminals, nuclear, geothermal, bioenergy, hydropower, solar, wind, gas_pipelines, oil_pipelines, lng_carriers. Omit for all trackers. All trackers: [Taxonomy & Codes — Energy](/api-reference/taxonomy#energy-vocabularies). Full value list: https://docs.gdeltcloud.com/reference/enums#gem_heavy_industry_tracker The enum above is the UNION across every endpoint that shares this parameter: `iron_steel_plants`, `cement_plants`, `chemical_plants`, `iron_ore_mines` — ACCEPTED ONLY ON `/api/v2/energy/assets`, `/api/v2/energy/assets/summary`. Elsewhere they return 400. On this endpoint the accepted set is narrower than on the other endpoints that share this parameter: `iron_steel_plants`, `cement_plants`, `chemical_plants`, `iron_ore_mines` return 400 here.", "example": "coal_plants,solar" }, { "$ref": "#/components/parameters/energyCountry" }, { "$ref": "#/components/parameters/energyRegion" }, { "$ref": "#/components/parameters/energyContinent" }, { "$ref": "#/components/parameters/energyStatus" }, { "$ref": "#/components/parameters/energyOperatingOnly" }, { "$ref": "#/components/parameters/energyTier" }, { "$ref": "#/components/parameters/energyFuel" }, { "$ref": "#/components/parameters/energyCapacityMwMin" }, { "$ref": "#/components/parameters/energyCapacityMwMax" }, { "$ref": "#/components/parameters/energyStartYearMin" }, { "$ref": "#/components/parameters/energyStartYearMax" }, { "$ref": "#/components/parameters/energyRetiredYearMin" }, { "$ref": "#/components/parameters/energyRetiredYearMax" }, { "$ref": "#/components/parameters/energyEntity" }, { "$ref": "#/components/parameters/energyOwnerSearch" }, { "$ref": "#/components/parameters/energyOwnerEntityId" }, { "$ref": "#/components/parameters/energyBbox" }, { "$ref": "#/components/parameters/energyNear" }, { "$ref": "#/components/parameters/energySearch" }, { "$ref": "#/components/parameters/energyAssetClass" }, { "$ref": "#/components/parameters/energyMapLimit" }, { "$ref": "#/components/parameters/energyFineGrainedLimit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyAssetsMapResponse" }, "examples": { "map": { "value": { "success": true, "mode": "aggregate", "data": [ { "kind": "aggregate", "country_iso3": "USA", "country": "United States", "lat": 39.5, "lon": -98.35, "asset_count": 1200, "capacity_mw_total": 250000, "top_tracker": "solar", "trackers": [ "coal_plants", "solar", "wind" ] } ], "filters_echo": { "tracker": [], "country_iso3": [ "USA" ], "status": [], "tier": [], "fuel": [], "operating_only": false, "asset_class": "fixed" } } } } } } }, "400": { "description": "Invalid Energy map filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Invalid Energy map filter.", "code": "INVALID_BBOX" } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch energy map.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy map.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/energy/assets/{tracker}/{gem_id}": { "get": { "operationId": "get-energy-asset-v2", "summary": "Get Energy Asset", "description": "Fetch one Energy asset by tracker and GEM ID. The response includes the canonical asset card plus a raw source record containing tracker-specific fields.", "tags": [ "Energy" ], "parameters": [ { "name": "tracker", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "coal_plants", "coal_mines", "coal_terminals", "oil_gas_plants", "oil_gas_extraction", "lng_terminals", "nuclear", "geothermal", "bioenergy", "hydropower", "solar", "wind", "gas_pipelines", "oil_pipelines", "lng_carriers" ] }, "description": "GEM tracker name. All trackers: [Taxonomy & Codes — Energy](/api-reference/taxonomy#energy-vocabularies). Full value list: https://docs.gdeltcloud.com/reference/enums#gem_tracker" }, { "name": "gem_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "GEM asset ID returned by Search Energy Assets." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyAssetDetailResponse" }, "examples": { "asset": { "value": { "success": true, "data": { "id": "oil_gas_plants:G100001090366", "gem_id": "G100001090366", "tracker": "oil_gas_plants", "tier": "main", "asset_class": "fixed", "name": "GW Ranch Energy Center", "name_local": null, "name_other": null, "status": "pre-construction", "status_detail": null, "start_year": 2028, "retired_year": null, "fuel": "fossil gas: natural gas", "capacity": { "value": 5000, "unit": "MW", "mw": 5000, "mw_secondary": null }, "geo": { "country": "United States", "country_iso3": "USA", "secondary_country_iso3": null, "region": "North America", "subregion": "Northern America", "continent": "North America", "state_province": "Texas", "city": "Fort Stockton", "lat": 31.16, "lon": -102.9, "location_accuracy": "exact" }, "owners_raw": "Pacifico GW LLC", "owners": [ { "name": "Pacifico GW LLC", "entity_id": "E100002021305", "stake_pct": null } ], "operators_raw": null, "operators": [], "parents_raw": "Pacifico Energy Group LLC", "parents": [ { "name": "Pacifico Energy Group LLC", "entity_id": "E100002021513", "stake_pct": null } ], "wiki_url": "https://www.gem.wiki/GW_Ranch_Energy_Center", "last_updated": "2026-01-15", "detail_url": "/energy/oil_gas_plants/G100001090366", "api_url": "/api/v2/energy/assets/oil_gas_plants/G100001090366" }, "raw": { "gem_id": "G100001090366", "tracker": "oil_gas_plants", "dataset_version": "2026-01" } } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "404": { "description": "Asset not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Asset not found.", "code": "NOT_FOUND" } } } } } }, "429": { "description": "Rate limit or quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Rate limit or quota exceeded.", "code": "RATE_LIMITED" } } } } } }, "500": { "description": "Failed to fetch energy asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy asset.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/energy/owners": { "get": { "operationId": "search-energy-owners-v2", "summary": "Search Energy Owners", "description": "Search the Global Energy Monitor ownership registry for canonical owner entities. Use this endpoint to resolve a company, government owner, person, or investment vehicle to a GEM Entity ID before calling owner portfolio or exposure endpoints.", "tags": [ "Energy" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search owner name, abbreviation, GEM Entity ID, or external ID." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Alias for q." }, { "name": "entity_id", "in": "query", "schema": { "type": "string" }, "description": "Exact GEM ownership entity ID." }, { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country filter — matches an owner's registration or headquarters country. Accepts a country name, ISO-2, or ISO-3 via the shared `resolveCountryInput` layer (combinable with `region`/`continent`); an unresolvable value returns `400 INVALID_COUNTRY`." }, { "name": "region", "in": "query", "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region expanded to ISO-3 countries; matches registration or headquarters country." }, { "name": "continent", "in": "query", "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent expanded to ISO-3 countries; matches registration or headquarters country." }, { "name": "entity_type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated GEM owner entity types. Observed vocabulary, measured 2026-08-10 (6 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/energy/owners?limit=1 — read `entity_type``. The corporate-registry classification GEM assigns an ownership entity. Unvalidated at the serve layer — `/api/v2/energy/owners?entity_type=` is applied as a plain IN list, so an unlisted value returns an empty 200. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#gem_owner_entity_type" }, { "name": "publicly_listed", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by public-listing status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from pagination.next_cursor." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyOwnersListResponse" }, "examples": { "owners": { "value": { "success": true, "data": [ { "entity_id": "E100002021513", "full_name": "Pacifico Energy Group LLC", "name": "Pacifico Energy Group LLC", "abbreviation": null, "entity_type": "company", "legal_entity_type": "company", "publicly_listed": false, "registration_country_iso3": "USA", "headquarters_country_iso3": "USA", "gem_parent_ids": [], "external_ids": {}, "portfolio_url": "/api/v2/energy/assets?owner_entity_id=E100002021513", "detail_url": "/api/v2/energy/owners/E100002021513" } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null } } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "500": { "description": "Failed to fetch energy owners.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy owners.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/energy/owners/{entity_id}": { "get": { "operationId": "get-energy-owner-v2", "summary": "Get Energy Owner", "description": "Fetch one Global Energy Monitor ownership entity by GEM Entity ID, including parent IDs, external IDs, and a portfolio summary across Energy assets. Optional include_exposure=true adds plan-gated risk/exposure fields — requires `can_use_exposure` (the Corporate & Supply Chain plan and above).", "tags": [ "Energy" ], "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "GEM ownership entity ID." }, { "name": "include_exposure", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include admin-gated exposure_summary from the internal risk/exposure preview." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyOwnerDetailResponse" }, "examples": { "owner": { "value": { "success": true, "data": { "entity_id": "E100002021513", "full_name": "Pacifico Energy Group LLC", "name": "Pacifico Energy Group LLC", "abbreviation": null, "entity_type": "company", "legal_entity_type": "company", "publicly_listed": false, "registration_country_iso3": "USA", "headquarters_country_iso3": "USA", "gem_parent_ids": [], "external_ids": {}, "portfolio_summary": { "asset_count": 3, "capacity_mw_total": 5000, "by_tracker": [ { "tracker": "oil_gas_plants", "asset_count": 1, "capacity_mw_total": 5000, "operating_count": 0, "planned_count": 1, "inactive_count": 0 } ] }, "portfolio_url": "/api/v2/energy/assets?owner_entity_id=E100002021513", "detail_url": "/api/v2/energy/owners/E100002021513" } } } } } } }, "401": { "description": "API key required. Include: Authorization: Bearer gdelt_sk_...", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "error": "API key required. Include: Authorization: Bearer gdelt_sk_...", "code": "MISSING_API_KEY" } } } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — `include_exposure=true` needs the `can_use_exposure` entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Ownership-exposure context requires a plan with Risk Context access.", "code": "PLAN_REQUIRED" } } } } } }, "404": { "description": "Owner not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Owner not found.", "code": "NOT_FOUND" } } } } } }, "500": { "description": "Failed to fetch energy owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "value": { "success": false, "error": "Failed to fetch energy owner.", "code": "INTERNAL_ERROR" } } } } } } } } }, "/api/v2/epoch/models": { "get": { "operationId": "list-epoch-models-v2", "summary": "AI models catalog", "tags": [ "AI Compute" ], "description": "Epoch AI notable-models catalog (CC-BY 4.0). Each model carries its developer, domain, parameters, training compute (FLOP), training hardware, frontier flag, and accessibility. Rows can be sorted by publication date or training compute. Requires a plan with AI compute & models access (`can_use_epoch_ai`) — the Corporate & Supply Chain and Global Intelligence plans.\n\nBoolean fields (frontier_model, open_weights) are real JSON booleans, training_compute_flop is de-artifacted, and the response echoes `applied_filters` (unknown params surface in `applied_filters.ignored`). This product uses data from Epoch AI (CC-BY 4.0).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on the developing organization (e.g. OpenAI, Google, Anthropic, xAI, Meta AI). Alias `org` is accepted." }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Language", "Vision", "Biology", "Multimodal", "Image generation", "Video", "Speech", "Robotics", "Games", "Audio", "Medicine", "Mathematics", "Materials science", "Earth science", "Recommendation", "Driving", "Search", "3D modeling", "Other" ] }, "description": "Case-insensitive substring match on task domain. The enum lists the atomic domain vocabulary (models can span several, e.g. `Vision,Multimodal` — so `Vision` also catches those rows); any substring is accepted. Full value list: https://docs.gdeltcloud.com/reference/enums#epoch_model_domain" }, { "name": "model_accessibility", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Open weights (unrestricted)", "Open weights (restricted use)", "Open weights (non-commercial)", "API access", "Hosted access (no API)", "Unreleased" ] }, "description": "Release/access tier — exact, case-insensitive match on the stored value. Use the open-weights tiers to filter to models with released weights. Full value list: https://docs.gdeltcloud.com/reference/enums#epoch_model_accessibility" }, { "name": "organization_categorization", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on the developing organization's category. Accepted tokens: `Industry`, `Academia`, `Government`, `Research collective`. A model may carry several comma-composited categories, so a token matches any model with that contributor type (e.g. `Academia` = any model with an academic contributor, not academia-exclusive). Not strictly validated — an unmatched value returns 0 rows rather than 400. Observed vocabulary, measured 2026-08-10 (126 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/epoch/models?limit=1 — read `organization_categorization``. Epoch's classification of the publishing organization. The stored field is COMPOSITE — a paper with several organizations carries their categories comma-joined, which is why 126 distinct strings appear (measured 2026-08-10) behind four underlying categories, including repeats such as `Academia,Academia`. Substring-matched and unvalidated, so filtering on a single category works and an unlisted value is an empty 200 rather than a 400. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#epoch_organization_categorization" }, { "name": "frontier", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only models Epoch flags as frontier; false → the non-frontier rows. Accepts true/false/1/0." }, { "name": "min_compute", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Floor on training_compute_flop (e.g. 1e25)." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "description": "Filter to models with `publication_date` on or after this date (YYYY-MM-DD). A malformed date is ignored rather than erroring." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" }, "description": "Filter to models with `publication_date` on or before this date (YYYY-MM-DD). Combine with `date_start` for a publication-date window." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "publication_date", "compute" ], "default": "publication_date" }, "description": "Sort by publication date (default) or training compute (FLOP), both descending." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 25." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical page token — pass the `pagination.next_cursor` from the previous response here to fetch the next page (uniform across all list endpoints)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset for pagination. Prefer the canonical `cursor` token; both are supported." } ], "responses": { "200": { "description": "A page of AI models. Envelope: `{ success, data, pagination, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "domain": { "type": "string" }, "organization": { "type": "string" }, "publication_date": { "type": "string" }, "parameters": { "type": "number", "nullable": true }, "training_compute_flop": { "type": "number", "nullable": true }, "training_hardware": { "type": "string", "nullable": true }, "frontier_model": { "type": "boolean", "nullable": true }, "open_weights": { "type": "boolean", "nullable": true }, "model_accessibility": { "type": "string", "nullable": true }, "entity_id": { "type": "string", "description": "Spine entity id for the developing organization." }, "entity_page_name": { "type": "string", "description": "Wiki-backed name that resolves to the entity's `/entities` page, or empty string when it has no wiki twin." } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true, "description": "Canonical page token — pass it back as `cursor` to fetch the next page (uniform across all list endpoints). `null` when there are no more rows." }, "next_offset": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy — prefer `next_cursor` (still returned). Numeric row offset of the next page." } } }, "applied_filters": { "type": "object", "properties": { "organization": { "type": "string" }, "frontier": { "type": "boolean" }, "sort": { "type": "string" }, "ignored": { "type": "object" } } } } }, "examples": { "example": { "summary": "GET /api/v2/epoch/models?frontier=true&sort=compute — example response", "value": { "success": true, "data": [ { "model": "GPT-4", "domain": "Language", "organization": "OpenAI", "publication_date": "2023-03-14", "parameters": null, "training_compute_flop": 2.1e+25, "training_hardware": "NVIDIA A100 SXM4 80 GB", "frontier_model": true, "open_weights": false, "model_accessibility": "API access", "entity_id": "e_58a5cada3c775725", "entity_page_name": "OpenAI" } ], "pagination": { "limit": 25, "offset": 0, "next_cursor": null, "next_offset": null }, "applied_filters": { "frontier": true, "sort": "compute", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/epoch/hardware": { "get": { "operationId": "list-epoch-hardware-v2", "summary": "ML hardware catalog", "tags": [ "AI Compute" ], "description": "Epoch AI ML-hardware catalog (CC-BY 4.0) — accelerators (GPU / TPU / NPU / ASIC …) with manufacturer, release date, TDP, memory, process size, and FP16/FP8 throughput. Rows sort by release date descending. Requires a plan with AI compute & models access (`can_use_epoch_ai`) — the Corporate & Supply Chain and Global Intelligence plans. Response echoes `applied_filters`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GPU", "TPU", "XPU-R", "NPU", "GPGPU", "ASIC", "XPU", "LPU", "Hybrid CPU", "DCU (GPGPU)", "Other" ] }, "description": "Case-insensitive exact match on the accelerator class as recorded by Epoch; the enum lists every stored type. Some tokens are composite, e.g. `DCU (GPGPU)`. An unknown value returns 400 INVALID_ENUM. Full value list: https://docs.gdeltcloud.com/reference/enums#epoch_hardware_type" }, { "name": "manufacturer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on manufacturer (e.g. Nvidia, AMD, Google, Huawei, Cambricon). Alias `org` is accepted." }, { "name": "foundry", "in": "query", "required": false, "schema": { "type": "string", "example": "SMIC" }, "description": "Case-insensitive substring match on the fabricator. Observed values: TSMC, SMIC, Samsung, Intel (plus dual-fab `SMIC,TSMC` parts, which either `SMIC` or `TSMC` returns). Echoed in applied_filters. Not strictly validated — an unmatched value returns 0 rows rather than 400. Observed vocabulary, measured 2026-08-10 (5 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/epoch/hardware?limit=1 — read `foundry``. The fab that manufactured the accelerator, as Epoch publishes it. Matched as a case-insensitive SUBSTRING with no validation, so a typo returns an empty 200 rather than a 400. Note some rows carry a comma-joined pair (`SMIC,TSMC`). Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#epoch_foundry" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2023-01-01" }, "description": "Filter to hardware with `release_date` on or after this date (YYYY-MM-DD). A malformed date is ignored rather than erroring." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" }, "description": "Filter to hardware with `release_date` on or before this date (YYYY-MM-DD). Combine with `date_start` for a release-date window." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 25." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical page token — pass the `pagination.next_cursor` from the previous response here to fetch the next page (uniform across all list endpoints)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset for pagination. Prefer the canonical `cursor` token; both are supported." } ], "responses": { "200": { "description": "A page of ML hardware. Envelope: `{ success, data, pagination, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "hardware_name": { "type": "string" }, "manufacturer": { "type": "string" }, "type": { "type": "string" }, "release_date": { "type": "string", "nullable": true }, "release_price_usd": { "type": "number", "nullable": true }, "tensor_fp16_flops": { "type": "number", "nullable": true }, "fp8_flops": { "type": "number", "nullable": true }, "memory_bytes": { "type": "number", "nullable": true }, "tdp_w": { "type": "number", "nullable": true }, "process_size_nm": { "type": "number", "nullable": true }, "entity_id": { "type": "string" }, "entity_page_name": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true, "description": "Canonical page token — pass it back as `cursor` to fetch the next page (uniform across all list endpoints). `null` when there are no more rows." }, "next_offset": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy — prefer `next_cursor` (still returned). Numeric row offset of the next page." } } }, "applied_filters": { "type": "object", "properties": { "manufacturer": { "type": "string" }, "type": { "type": "string" }, "ignored": { "type": "object" } } } } }, "examples": { "example": { "summary": "GET /api/v2/epoch/hardware?manufacturer=Nvidia — example response", "value": { "success": true, "data": [ { "hardware_name": "NVIDIA H100 SXM5", "manufacturer": "NVIDIA", "type": "GPU", "release_date": "2022-03-22", "release_price_usd": null, "tensor_fp16_flops": 989000000000000, "fp8_flops": 1979000000000000, "memory_bytes": 85899345920, "tdp_w": 700, "process_size_nm": 4, "entity_id": "e_9f8e7d6c5b4a3210", "entity_page_name": "Nvidia" } ], "pagination": { "limit": 25, "offset": 0, "next_cursor": null, "next_offset": null }, "applied_filters": { "manufacturer": "Nvidia", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/epoch/data-centers": { "get": { "operationId": "list-epoch-data-centers-v2", "summary": "AI data centers", "tags": [ "AI Compute" ], "description": "Epoch AI data-center registry (CC-BY 4.0) — the largest AI compute clusters with power (MW), H100-equivalent compute, capital cost ($B), owner, chip types, and named users. Rows sort by compute (H100e) descending. Includes a per-country rollup (`by_country`) and dataset totals (`totals`). Requires a plan with AI compute & models access (`can_use_epoch_ai`) — the Corporate & Supply Chain and Global Intelligence plans. Response echoes `applied_filters`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Data-center country filter. Accepts a country name (`United States`), ISO-2 (`US`), or ISO-3 (`USA`) via the shared `resolveCountryInput` layer, matched exactly on the canonical country name; an unresolvable value returns `400 INVALID_COUNTRY`. Full value list: https://docs.gdeltcloud.com/reference/enums#country" }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on operating owner (e.g. Microsoft, Meta, xAI, Amazon). Alias: `org`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 25." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical page token — pass the `pagination.next_cursor` from the previous response here to fetch the next page (uniform across all list endpoints)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset for pagination. Prefer the canonical `cursor` token; both are supported." } ], "responses": { "200": { "description": "A page of data centers plus a country rollup and totals. Envelope: `{ success, data, by_country, totals, pagination, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "owner": { "type": "string", "nullable": true }, "current_power_mw": { "type": "number", "nullable": true }, "current_h100e": { "type": "number", "nullable": true }, "current_capital_cost_busd": { "type": "number", "nullable": true }, "country": { "type": "string", "nullable": true }, "users": { "type": "string", "nullable": true }, "current_chip_types": { "type": "string", "nullable": true }, "entity_id": { "type": "string" }, "entity_page_name": { "type": "string" } } } }, "by_country": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "data_centers": { "type": "integer" }, "power_mw_total": { "type": "number" }, "h100e_total": { "type": "number" }, "capital_cost_busd_total": { "type": "number" } } } }, "totals": { "type": "object", "properties": { "n": { "type": "integer" }, "power_mw": { "type": "number" }, "h100e": { "type": "number" }, "capital_cost_busd": { "type": "number" } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true, "description": "Canonical page token — pass it back as `cursor` to fetch the next page (uniform across all list endpoints). `null` when there are no more rows." }, "next_offset": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy — prefer `next_cursor` (still returned). Numeric row offset of the next page." } } }, "applied_filters": { "type": "object", "properties": { "country": { "type": "string" }, "owner": { "type": "string" }, "ignored": { "type": "object" } } } } }, "examples": { "example": { "summary": "GET /api/v2/epoch/data-centers?owner=Microsoft — example response", "value": { "success": true, "data": [ { "name": "Fairwater (Mount Pleasant)", "owner": "Microsoft", "current_power_mw": 300, "current_h100e": 400000, "current_capital_cost_busd": 3.3, "country": "United States", "users": "OpenAI", "current_chip_types": "NVIDIA GB200", "entity_id": "e_11223344aabbccdd", "entity_page_name": "Microsoft" } ], "by_country": [ { "country": "United States", "data_centers": 42, "power_mw_total": 5200, "h100e_total": 6100000, "capital_cost_busd_total": 58.4 } ], "totals": { "n": 71, "power_mw": 7300, "h100e": 8400000, "capital_cost_busd": 79.1 }, "pagination": { "limit": 25, "offset": 0, "next_cursor": null, "next_offset": null }, "applied_filters": { "owner": "Microsoft", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/epoch/companies": { "get": { "operationId": "list-epoch-companies-v2", "summary": "AI companies", "tags": [ "AI Compute" ], "description": "Epoch AI company tracker (CC-BY 4.0) — the tracked AI labs with latest valuation, annualized revenue, total equity funding, staff count, and company type. Latest financials are derived from the dated time-series (most recent closed funding round for valuation). Sorted by valuation descending. Requires a plan with AI compute & models access (`can_use_epoch_ai`) — the Corporate & Supply Chain and Global Intelligence plans.\n\nThis endpoint takes no filter params beyond pagination — any other query param (e.g. `search`, `org`) is surfaced back in `applied_filters.ignored` rather than silently applied.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical page token — pass the `pagination.next_cursor` from the previous response here to fetch the next page (uniform across all list endpoints)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset for pagination. Prefer the canonical `cursor` token; both are supported." } ], "responses": { "200": { "description": "A page of AI companies. Envelope: `{ success, data, pagination, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "company_type": { "type": "string", "nullable": true }, "product_domains": { "type": "string", "nullable": true }, "staff_count_latest": { "type": "number", "nullable": true }, "annualized_revenue_latest_usd": { "type": "number", "nullable": true }, "valuation_latest_usd": { "type": "number", "nullable": true }, "total_equity_funding_usd": { "type": "number", "nullable": true }, "founding_date": { "type": "string", "nullable": true }, "entity_id": { "type": "string" }, "entity_page_name": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true, "description": "Canonical page token — pass it back as `cursor` to fetch the next page (uniform across all list endpoints). `null` when there are no more rows." }, "next_offset": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy — prefer `next_cursor` (still returned). Numeric row offset of the next page." } } }, "applied_filters": { "type": "object", "properties": { "ignored": { "type": "object" } } } } }, "examples": { "example": { "summary": "GET /api/v2/epoch/companies — example response", "value": { "success": true, "data": [ { "name": "OpenAI", "company_type": "Industry", "product_domains": "Language, Multimodal", "staff_count_latest": 3000, "annualized_revenue_latest_usd": 12000000000, "valuation_latest_usd": 300000000000, "total_equity_funding_usd": 57900000000, "founding_date": "2015-12-11", "entity_id": "e_58a5cada3c775725", "entity_page_name": "OpenAI" } ], "pagination": { "limit": 50, "offset": 0, "next_cursor": null, "next_offset": null }, "applied_filters": { "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/epoch/chip-sales": { "get": { "operationId": "list-epoch-chip-sales-v2", "summary": "AI chip sales", "tags": [ "AI Compute" ], "description": "Epoch AI chip-sales rollup (CC-BY 4.0) — cumulative installed compute by chip designer (H100-equivalent), unit counts, and power draw (MW), at the latest reported window per manufacturer. Sorted by installed compute descending. Requires a plan with AI compute & models access (`can_use_epoch_ai`) — the Corporate & Supply Chain and Global Intelligence plans.\n\nFilter by `chip_manufacturer` (the endpoint's sole filter); any other query param is surfaced back in `applied_filters.ignored` rather than silently applied.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chip_manufacturer", "in": "query", "required": false, "schema": { "type": "string", "example": "Huawei" }, "description": "Filter to one chip designer — exact, case-insensitive match. The designers with data are Nvidia, Google, Amazon, Huawei, AMD, and Cambricon; any other value returns 0 rows rather than 400. Echoed in applied_filters. Observed vocabulary, measured 2026-08-10 (6 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/epoch/chip-sales?limit=1 — read `chip_manufacturer``. The accelerator designer in Epoch's chip-sales series. Lower-cased exact match with no validation — an unlisted manufacturer returns an empty 200. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#epoch_chip_manufacturer" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Canonical page token — pass the `pagination.next_cursor` from the previous response here to fetch the next page (uniform across all list endpoints)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Row offset for pagination. Prefer the canonical `cursor` token; both are supported." } ], "responses": { "200": { "description": "A page of chip-designer rollups. Envelope: `{ success, data, pagination, applied_filters }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "chip_manufacturer": { "type": "string" }, "compute_h100e": { "type": "number", "nullable": true }, "units": { "type": "number", "nullable": true }, "power_mw": { "type": "number", "nullable": true }, "as_of": { "type": "string", "description": "End date of the latest reported cumulative window." }, "entity_id": { "type": "string" }, "entity_page_name": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true, "description": "Canonical page token — pass it back as `cursor` to fetch the next page (uniform across all list endpoints). `null` when there are no more rows." }, "next_offset": { "type": "integer", "nullable": true, "deprecated": true, "description": "Legacy — prefer `next_cursor` (still returned). Numeric row offset of the next page." } } }, "applied_filters": { "type": "object", "properties": { "ignored": { "type": "object" } } } } }, "examples": { "example": { "summary": "GET /api/v2/epoch/chip-sales — example response", "value": { "success": true, "data": [ { "chip_manufacturer": "NVIDIA", "compute_h100e": 6500000, "units": 4100000, "power_mw": 3100.5, "as_of": "2025-12-31", "entity_id": "e_9f8e7d6c5b4a3210", "entity_page_name": "Nvidia" } ], "pagination": { "limit": 50, "offset": 0, "next_cursor": null, "next_offset": null }, "applied_filters": { "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/macro/series": { "get": { "operationId": "list-macro-series-v2", "summary": "List FRED series", "tags": [ "Macro Finance" ], "description": "List the FRED economic time-series catalog by title/ID search, agency, frequency, and seasonal adjustment. Call with no filters to enumerate the full curated catalog (ordered by popularity) — this is the way to discover a valid `series_id`. Quarantined (third-party copyrighted) series are never returned. Requires a plan with Macro & economic data access (`can_use_macro`) — the Corporate & Supply Chain and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive match against series title or series_id." }, { "name": "agency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BEA", "BLS", "CBOE", "Census", "DOL", "EIA", "FHFA", "FRB", "Freddie Mac", "Treasury", "U. Michigan" ] }, "description": "Exact source agency (e.g. BLS, BEA, FRB, EIA). See [Taxonomy & Codes — Macro Finance](/api-reference/taxonomy#macro-finance). Full value list: https://docs.gdeltcloud.com/reference/enums#macro_agency" }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "D", "W", "M", "Q", "A", "Daily", "Weekly", "Monthly", "Quarterly", "Annual" ] }, "description": "FRED frequency_short (D=Daily, W=Weekly, M=Monthly, Q=Quarterly, A=Annual). Case-insensitive; the word forms (Daily/Weekly/Monthly/Quarterly/Annual) are also accepted. Full value list: https://docs.gdeltcloud.com/reference/enums#macro_frequency" }, { "name": "seasonal_adjustment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Not Seasonally Adjusted", "Seasonally Adjusted", "Seasonally Adjusted Annual Rate" ] }, "description": "FRED seasonal-adjustment classification. Case-insensitive; an unknown value returns 400 INVALID_ENUM. Full value list: https://docs.gdeltcloud.com/reference/enums#macro_seasonal_adjustment" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "description": "Rows per page (1–100)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of series, ordered by popularity. Each row: series_id, title, frequency, frequency_short, units, units_short, seasonal_adjustment, observation_start, observation_end, source_agency, release_name, geo_country_iso3, compliance_status, popularity. Includes a meta object carrying the FRED non-endorsement attribution and source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "series_id": { "type": "string" }, "title": { "type": "string" }, "frequency": { "type": "string" }, "frequency_short": { "type": "string" }, "units": { "type": "string" }, "units_short": { "type": "string" }, "seasonal_adjustment": { "type": "string" }, "observation_start": { "type": "string" }, "observation_end": { "type": "string" }, "source_agency": { "type": "string" }, "release_name": { "type": "string" }, "geo_country_iso3": { "type": "string" }, "compliance_status": { "type": "string" }, "popularity": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "ignored": { "type": "object", "properties": {} } } }, "meta": { "type": "object", "properties": { "attribution": { "type": "string" }, "source": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/macro/series — example response", "value": { "success": true, "data": [ { "series_id": "DGS10", "title": "Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis", "frequency": "Daily", "frequency_short": "D", "units": "Percent", "units_short": "%", "seasonal_adjustment": "Not Seasonally Adjusted", "observation_start": "1962-01-02", "observation_end": "2026-06-26", "source_agency": "FRB", "release_name": "H.15 Selected Interest Rates", "geo_country_iso3": "USA", "compliance_status": "ok", "popularity": 91 }, { "series_id": "UNRATE", "title": "Unemployment Rate", "frequency": "Monthly", "frequency_short": "M", "units": "Percent", "units_short": "%", "seasonal_adjustment": "Seasonally Adjusted", "observation_start": "1948-01-01", "observation_end": "2026-05-01", "source_agency": "BLS", "release_name": "Employment Situation", "geo_country_iso3": "USA", "compliance_status": "ok", "popularity": 88 } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null }, "applied_filters": { "ignored": {} }, "meta": { "attribution": "This product uses data from the Federal Reserve Bank of St. Louis (FRED) but is not endorsed or certified by it.", "source": "Federal Reserve Bank of St. Louis (FRED)" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/macro/series/{series_id}": { "get": { "operationId": "get-macro-series-v2", "summary": "Get FRED series detail", "tags": [ "Macro Finance" ], "description": "Series catalog detail plus the most recent 24 observations (latest vintage). An unknown or quarantined series_id returns 404 with a message pointing to GET /api/v2/macro/series and the catalog. Requires a plan with Macro & economic data access (`can_use_macro`) — the Corporate & Supply Chain and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "series_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "FRED series ID (e.g. UNRATE, CPIAUCSL, DGS10). To discover valid IDs, call GET /api/v2/macro/series with no filters" } ], "responses": { "200": { "description": "Series detail and recent observations. `series` carries series_id, title, frequency, frequency_short, units, units_short, seasonal_adjustment, observation_start, observation_end, last_updated, source_agency, release_id, release_name, geo_country_iso3, compliance_status, popularity, attribution_text, notes. `recent_observations` is up to 24 { date, value } points (most recent first). Includes the FRED non-endorsement meta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "series": { "type": "object", "properties": { "series_id": { "type": "string" }, "title": { "type": "string" }, "frequency": { "type": "string" }, "frequency_short": { "type": "string" }, "units": { "type": "string" }, "units_short": { "type": "string" }, "seasonal_adjustment": { "type": "string" }, "observation_start": { "type": "string" }, "observation_end": { "type": "string" }, "last_updated": { "type": "string" }, "source_agency": { "type": "string" }, "release_id": { "type": "integer" }, "release_name": { "type": "string" }, "geo_country_iso3": { "type": "string" }, "compliance_status": { "type": "string" }, "popularity": { "type": "integer" }, "attribution_text": { "type": "string" }, "notes": { "type": "string" } } }, "recent_observations": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" } } } }, "meta": { "type": "object", "properties": { "attribution": { "type": "string" }, "source": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/macro/series/{series_id} — example response", "value": { "success": true, "series": { "series_id": "DGS10", "title": "Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis", "frequency": "Daily", "frequency_short": "D", "units": "Percent", "units_short": "%", "seasonal_adjustment": "Not Seasonally Adjusted", "observation_start": "1962-01-02", "observation_end": "2026-06-26", "last_updated": "2026-06-27 15:18:04", "source_agency": "FRB", "release_id": 18, "release_name": "H.15 Selected Interest Rates", "geo_country_iso3": "USA", "compliance_status": "ok", "popularity": 91, "attribution_text": "This product uses data from the Federal Reserve Bank of St. Louis (FRED) but is not endorsed or certified by it.", "notes": "For further information regarding treasury constant maturity data, please refer to the H.15 Statistical Release notes and the Treasury Yield Curve Methodology." }, "recent_observations": [ { "date": "2026-06-26", "value": 4.27 }, { "date": "2026-06-25", "value": 4.31 } ], "meta": { "attribution": "This product uses data from the Federal Reserve Bank of St. Louis (FRED) but is not endorsed or certified by it.", "source": "Federal Reserve Bank of St. Louis (FRED)" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Series not found or not available (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/macro/observations": { "get": { "operationId": "list-macro-observations-v2", "summary": "List FRED observations", "tags": [ "Macro Finance" ], "description": "Point-in-time observations for a single series. Optional `as_of` selects the vintage known on/before that date (ALFRED — no look-ahead); otherwise the latest vintage is returned. When no dates are given, returns the most-recent observations across the full available history, bounded by `limit` — page further back via `next_cursor`; there is no fixed trailing window. Discover a valid series_id via GET /api/v2/macro/series. Requires a plan with Macro & economic data access (`can_use_macro`) — the Corporate & Supply Chain and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "series_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "FRED series ID (required). To discover valid IDs, call GET /api/v2/macro/series with no filters" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Observation window start YYYY-MM-DD. Defaults to the beginning of the series; with no start date the response returns the most-recent observations by `limit`, with older history reachable via `next_cursor`." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Observation window end YYYY-MM-DD." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Vintage date YYYY-MM-DD — return values as they were known on/before this date (point-in-time, no look-ahead)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "description": "Rows per page (1–100)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of observations for the series, most recent first. Each row: date, value, vintage (the realtime_start the value became known). Echoes series_id and includes the FRED non-endorsement meta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "series_id": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" }, "vintage": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": { "type": "string" } } }, "applied_filters": { "type": "object", "properties": { "series_id": { "type": "string" }, "date_start": { "type": "string" }, "as_of": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } }, "meta": { "type": "object", "properties": { "attribution": { "type": "string" }, "source": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/macro/observations — example response", "value": { "success": true, "series_id": "DGS10", "data": [ { "date": "2026-06-26", "value": 4.27, "vintage": "2026-06-27" }, { "date": "2026-06-25", "value": 4.31, "vintage": "2026-06-26" } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "25" }, "applied_filters": { "series_id": "DGS10", "date_start": "2023-06-30", "as_of": "2026-06-27", "ignored": {} }, "meta": { "attribution": "This product uses data from the Federal Reserve Bank of St. Louis (FRED) but is not endorsed or certified by it.", "source": "Federal Reserve Bank of St. Louis (FRED)" } } } } } } }, "400": { "description": "series_id is required (MISSING_PARAM)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/macro/releases": { "get": { "operationId": "list-macro-releases-v2", "summary": "List FRED releases", "tags": [ "Macro Finance" ], "description": "Rollup of the catalog by source agency and release, with series counts. Requires a plan with Macro & economic data access (`can_use_macro`) — the Corporate & Supply Chain and Global Intelligence plans.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match against the release name OR its (read-time-filled) source agency." }, { "name": "agency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BEA", "BLS", "CBOE", "Census", "DOL", "EIA", "FHFA", "FRB", "Freddie Mac", "Treasury", "U. Michigan" ] }, "description": "Source agency filter, matched case-insensitively against the read-time-filled agency (so blank-agency releases are still reachable). Validated against the same allowlist as `/api/v2/macro/series` — an unknown value returns `400 INVALID_ENUM` with `details.accepted_values`. See [Taxonomy & Codes — Macro Finance](/api-reference/taxonomy#macro-finance). Full value list: https://docs.gdeltcloud.com/reference/enums#macro_agency" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Rows per page (1–200). Defaults to 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset) from a prior response's `pagination.next_cursor`. `offset` is accepted as an alias." } ], "responses": { "200": { "description": "Agency/release rollup, ordered by series count. Each row: source_agency, release_name, series (count), top_popularity. Includes the FRED non-endorsement meta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "source_agency": { "type": "string" }, "display_agency": { "type": "string" }, "release_name": { "type": "string" }, "series": { "type": "integer" }, "top_popularity": { "type": "integer" } } } }, "applied_filters": { "type": "object", "properties": { "ignored": { "type": "object", "properties": {} } } }, "meta": { "type": "object", "properties": { "attribution": { "type": "string" }, "source": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/macro/releases — example response", "value": { "success": true, "data": [ { "source_agency": "BLS", "display_agency": "BLS", "release_name": "Employment Situation", "series": 9, "top_popularity": 88 }, { "source_agency": "FRB", "display_agency": "FRB", "release_name": "H.15 Selected Interest Rates", "series": 7, "top_popularity": 91 } ], "applied_filters": { "ignored": {} }, "meta": { "attribution": "This product uses data from the Federal Reserve Bank of St. Louis (FRED) but is not endorsed or certified by it.", "source": "Federal Reserve Bank of St. Louis (FRED)" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/screening/match": { "get": { "operationId": "screen-counterparty-v2", "summary": "Screen a counterparty", "description": "Recall-first restricted-party candidate retrieval with explicit match evidence. Retrieval similarity is not an identity probability and is exposed separately from match confidence.\n\n\n\nThese return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.\n\n- `country` → 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead: `GET /api/v2/lists/entries?country=RUS`.\n- `region` → 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead: `GET /api/v2/lists/entries?region=Europe`.\n- `continent` → 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead: `GET /api/v2/lists/entries?continent=Europe`.\n\n", "tags": [ "Screening and Reference" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Counterparty name. `name` is an alias. Also accepts: `name`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "PAO Sovcomflot", "x-aliases": [ "name" ] }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Strong entity or list identifier. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "e_23143daadfa8de68" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Historical list-membership date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20" }, { "name": "min_match_confidence", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.85 }, "description": "Minimum returned match confidence. `threshold` is the deprecated alias. Also accepts: `threshold`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0.85", "x-aliases": [ "threshold" ] }, { "name": "include_exposure", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Attach ownership-chain exposure context. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum matched entities returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Screen a counterparty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningMatchResponse" }, "examples": { "example": { "summary": "GET /api/v2/screening/match — example response", "value": { "success": true, "query": { "q": "Hikvision", "id": null, "as_of": "2026-06-29", "threshold": 0.85 }, "disclaimer": "Risk-intelligence signal derived from public restricted-party lists and proprietary exposure data, as of the date shown. Not a sanctions-compliance determination or a substitute for due diligence.", "coverage": "Public restricted-party lists ingested into ref.list_entries (institution-only).", "match_count": 1, "matches": [ { "entity_id": "e_7c2a4f1b8e9d3056", "name": "Hangzhou Hikvision Digital Technology Co., Ltd.", "score": 0.972, "confidence": "strong", "method": "fuzzy_name", "lists": [ { "source_key": "dod_1260h", "entry_uid": "1260h-2026-041", "name": "Hikvision Digital Technology Co., Ltd.", "entity_kind": "entity", "country_iso3": "CHN", "programs": [ "Section 1260H" ], "legal_basis": "Section 1260H, NDAA FY2021", "source_url": "https://www.defense.gov/News/Releases/", "ids": { "ticker": "002415.SZ" }, "first_seen_date": "2022-10-05", "last_seen_date": "2026-06-29", "match_score": 0.972 }, { "source_key": "fcc_covered", "entry_uid": "fcc-2021-007", "name": "Hikvision Digital Technology Co., Ltd.", "entity_kind": "entity", "country_iso3": "CHN", "programs": [ "FCC Covered List" ], "legal_basis": "Secure and Trusted Communications Networks Act of 2019", "source_url": "https://www.fcc.gov/supplychain/coveredlist", "ids": {}, "first_seen_date": "2021-03-12", "last_seen_date": "2026-06-29", "match_score": 0.948 } ], "exposure": { "lenses": [ "china", "state_owned" ], "direct": true, "lists": [ "dod_1260h", "fcc_covered" ], "china_edges": [ "list_1260h", "gem_parent" ] } } ] } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-plan-feature": "can_use_screening" } }, "/api/v2/exposure": { "get": { "operationId": "search-exposure-v2", "summary": "Ownership-chain exposure", "description": "Precomputed entity and facility exposure through sanctions, China, or state-ownership chains. Numeric stake filters apply to effective chain stake, never the direct asset-owner percentage alone.", "tags": [ "Screening and Reference" ], "parameters": [ { "name": "lens", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sanctions", "china", "state_owned" ], "default": "sanctions" }, "description": "Exposure lens. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#exposure_lens", "example": "sanctions" }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "assets", "entities" ], "default": "assets" }, "description": "Result unit. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#exposure_subject", "example": "assets" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "CHN" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Region expanded to countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "East Asia" }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Continent expanded to countries. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "Asia" }, { "name": "tracker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM tracker filter. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "oil_gas_extraction" }, { "name": "list", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csl_ofac_sdn", "csl_ofac_ssi", "csl_ofac_cmic", "csl_ofac_nsmbs", "csl_ofac_capta", "csl_bis_entity", "csl_bis_meu", "csl_bis_uvl", "csl_bis_dpl", "csl_state_debarred", "csl_state_isn", "dod_1260h", "un_consolidated", "uk_uksl", "state_owned", "cn_state" ] }, "description": "Contributing restricted-party list. `source` is an alias. Also accepts: `source`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#exposure_list", "example": "csl_ofac_sdn", "x-aliases": [ "source" ] }, { "name": "min_stake_pct", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Minimum effective ownership-chain stake. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "50" }, { "name": "direct_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Restrict to direct exposure. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "true" }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Resolved entity identifier. `entity_id` is an alias. Also accepts: `entity_id`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "e_2bf6cdc5bc0d9097", "x-aliases": [ "entity_id" ] }, { "name": "entity_search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fuzzy entity resolver query. `q` and `counterparty` are aliases. Also accepts: `q`, `counterparty`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "CNOOC", "x-aliases": [ "q", "counterparty" ] }, { "name": "gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM asset identifier. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "G100000001234" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "none", "country", "tracker" ], "default": "none" }, "description": "Aggregation dimension. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#exposure_group_by", "example": "none" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "capacity_desc", "stake_desc" ], "default": "capacity_desc" }, "description": "Result ordering. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#exposure_sort", "example": "capacity_desc" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum rows returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "25" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "opaque" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Legacy numeric offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Ownership-chain exposure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExposureResponse" }, "examples": { "example_1": { "summary": "Effective ownership-chain stake", "value": { "success": true, "lens": "sanctions", "subject": "assets", "data": [ { "gem_id": "G100001070620", "tracker": "GOGET", "country_iso3": "RUS", "capacity_mw": null, "exposed": true, "direct": false, "max_chain_depth": 1, "exposure_stake_pct": 10, "effective_stake_pct": 10, "stake_status": "known", "contributing_entity_ids": [ "e_2bf6cdc5bc0d9097" ], "contributing_lists": [ "state_owned" ], "paths": [ { "entity_id": "e_2bf6cdc5bc0d9097", "via": "E100002004816", "asset_owner_stake_pct": 100, "chain_ownership_pct": 10, "effective_stake_pct": 10, "stake_status": "known", "depth": 1, "gem_path": [ "E100002004816", "E100001014354" ] } ] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null }, "sort": "capacity_desc", "resolved_counterparties": [], "timings_ms": { "counterparty_search": 0 }, "applied_filters": { "lens": "sanctions", "subject": "assets", "entity_id": "e_2bf6cdc5bc0d9097" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-plan-feature": "can_use_exposure" } }, "/api/v2/lists": { "get": { "operationId": "lists-catalog-v2", "summary": "List catalog", "tags": [ "Screening and Reference" ], "description": "Catalog of the restricted-party list sources we ingest (issuer, jurisdiction, cadence, current entry counts). Requires a plan with Restricted-party screening access (`can_use_screening`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csl_ofac_sdn", "csl_ofac_ssi", "csl_ofac_cmic", "csl_ofac_nsmbs", "csl_ofac_capta", "csl_bis_entity", "csl_bis_meu", "csl_bis_uvl", "csl_bis_dpl", "csl_state_debarred", "csl_state_isn", "dod_1260h", "un_consolidated", "uk_uksl" ] }, "description": "Filter to one source_key. Full value list: https://docs.gdeltcloud.com/reference/enums#list_source_key" }, { "name": "jurisdiction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Issuer jurisdiction (US/EU/UN/GB/CN/AU)." }, { "name": "cadence", "in": "query", "required": false, "schema": { "type": "string" }, "description": "daily | episodic. Observed vocabulary, measured 2026-08-10 (2 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/lists — read `cadence` on each catalogue entry`. How often a screening list is refreshed. Read straight off the catalogue and matched CASE-SENSITIVELY with no validation, so `cadence=Daily` returns zero rows while `cadence=daily` returns twelve. The sibling `jurisdiction` filter was made case-insensitive for exactly this reason; `cadence` was not. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#list_cadence" } ], "responses": { "200": { "description": "List catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "source_key": { "type": "string" }, "list_name": { "type": "string" }, "issuer": { "type": "string" }, "jurisdiction": { "type": "string" }, "authority": { "type": "string" }, "source_url": { "type": "string" }, "cadence": { "type": "string" }, "loader": { "type": "string" }, "includes_individuals": { "type": "boolean" }, "last_loaded": { "type": "string" }, "entry_count": { "type": "integer" } } } }, "applied_filters": { "type": "object", "properties": { "jurisdiction": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/lists — example response", "value": { "success": true, "data": [ { "source_key": "csl_ofac_sdn", "list_name": "OFAC Specially Designated Nationals (SDN)", "issuer": "OFAC", "jurisdiction": "US", "authority": "31 CFR Chapter V", "source_url": "https://www.trade.gov/consolidated-screening-list", "cadence": "daily", "loader": "cron", "includes_individuals": false, "last_loaded": "2026-06-29 06:12:04", "entry_count": 8741 }, { "source_key": "dod_1260h", "list_name": "DoD Section 1260H Chinese Military Companies", "issuer": "DoD", "jurisdiction": "US", "authority": "Section 1260H, NDAA FY2021", "source_url": "https://www.defense.gov/News/Releases/", "cadence": "episodic", "loader": "script", "includes_individuals": false, "last_loaded": "2026-01-31 14:22:51", "entry_count": 134 } ], "applied_filters": { "jurisdiction": "US" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/lists/entries": { "get": { "operationId": "lists-entries-v2", "summary": "Search list entries", "tags": [ "Screening and Reference" ], "description": "Search restricted-party list ENTRIES (institution-only) — programmes, aliases, country, ids, with bitemporal as-of selection. Requires a plan with Restricted-party screening access (`can_use_screening`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csl_ofac_sdn", "csl_ofac_ssi", "csl_ofac_cmic", "csl_ofac_nsmbs", "csl_ofac_capta", "csl_bis_entity", "csl_bis_meu", "csl_bis_uvl", "csl_bis_dpl", "csl_state_debarred", "csl_state_isn", "dod_1260h", "un_consolidated", "uk_uksl" ] }, "description": "Restrict to one source_key. Full value list: https://docs.gdeltcloud.com/reference/enums#list_source_key" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Name search." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter on list entries. Accepts a country name, ISO-2, or ISO-3 via the shared `resolveCountryInput` layer (matched against the entry's `country_iso3`); an unresolvable value returns `400 INVALID_COUNTRY`." }, { "name": "program", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sanctions programme filter." }, { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Entries resolved to this entity_id." }, { "name": "active_on", "in": "query", "required": false, "schema": { "type": "string" }, "description": "As-of date (YYYY-MM-DD) for bitemporal selection." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." }, { "name": "sort", "in": "query", "required": false, "description": "Sort order for list entries. Full value list: https://docs.gdeltcloud.com/reference/enums#list_entries_sort", "schema": { "type": "string", "enum": [ "name", "recent" ], "default": "name" } } ], "responses": { "200": { "description": "Search list entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "entry_uid": { "type": "string" }, "source_key": { "type": "string" }, "name": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "entity_kind": { "type": "string" }, "country_iso3": { "type": "string" }, "programs": { "type": "array", "items": { "type": "string" } }, "legal_basis": { "type": "string" }, "source_url": { "type": "string" }, "ids": { "type": "object", "properties": { "csl_id": { "type": "string" }, "lei": { "type": "string" } } }, "first_seen_date": { "type": "string" }, "last_seen_date": { "type": "string" }, "active": { "type": "boolean" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "sort": { "type": "string" }, "applied_filters": { "type": "object", "properties": { "country": { "type": "string" }, "q": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/lists/entries — example response", "value": { "success": true, "data": [ { "entry_uid": "26156", "source_key": "csl_bis_entity", "name": "Huawei Technologies Co., Ltd.", "aliases": [ "Huawei Technologies", "华为技术有限公司", "Huawei" ], "entity_kind": "entity", "country_iso3": "CHN", "programs": [ "EAR Entity List" ], "legal_basis": "Supplement No. 4 to 15 CFR Part 744", "source_url": "https://www.bis.doc.gov/index.php/policy-guidance/lists-of-parties-of-concern/entity-list", "ids": { "csl_id": "26156", "lei": "529900PH9YTJ9N5BH261" }, "first_seen_date": "2019-05-16", "last_seen_date": "2026-06-29", "active": true }, { "entry_uid": "1260h-2026-041", "source_key": "dod_1260h", "name": "Hikvision Digital Technology Co., Ltd.", "aliases": [ "Hangzhou Hikvision Digital Technology", "杭州海康威视数字技术股份有限公司", "Hikvision" ], "entity_kind": "entity", "country_iso3": "CHN", "programs": [ "Section 1260H" ], "legal_basis": "Section 1260H, NDAA FY2021", "source_url": "https://www.defense.gov/News/Releases/", "ids": { "ticker": "002415.SZ" }, "first_seen_date": "2022-10-05", "last_seen_date": "2026-06-29", "active": true } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": null }, "sort": "name", "applied_filters": { "country": "CHN", "q": "huawei" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/lists/changes": { "get": { "operationId": "lists-changes-v2", "summary": "List change feed", "tags": [ "Screening and Reference" ], "description": "Append-only added/removed/changed diff feed for the restricted-party lists. Requires a plan with Restricted-party screening access (`can_use_screening`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csl_ofac_sdn", "csl_ofac_ssi", "csl_ofac_cmic", "csl_ofac_nsmbs", "csl_ofac_capta", "csl_bis_entity", "csl_bis_meu", "csl_bis_uvl", "csl_bis_dpl", "csl_state_debarred", "csl_state_isn", "dod_1260h", "un_consolidated", "uk_uksl" ] }, "description": "Restrict to one source_key. Full value list: https://docs.gdeltcloud.com/reference/enums#list_source_key" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." }, { "name": "change_type", "in": "query", "required": false, "description": "Filter the change feed to one kind of change. Full value list: https://docs.gdeltcloud.com/reference/enums#list_change_type", "schema": { "type": "string", "enum": [ "added", "removed", "changed" ] } } ], "responses": { "200": { "description": "List change feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "snapshot_date": { "type": "string" }, "source_key": { "type": "string" }, "change_type": { "type": "string" }, "entry_uid": { "type": "string" }, "name": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "days": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/lists/changes — example response", "value": { "success": true, "data": [ { "snapshot_date": "2026-06-27", "source_key": "csl_ofac_sdn", "change_type": "added", "entry_uid": "51284", "name": "Promsvyazbank Public Joint Stock Company" }, { "snapshot_date": "2026-06-25", "source_key": "csl_bis_entity", "change_type": "removed", "entry_uid": "24817", "name": "Shenzhen Anke High-Tech Co., Ltd." } ], "pagination": { "limit": 50, "cursor": null, "next_cursor": null }, "applied_filters": { "days": "7" } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/china/projects": { "get": { "operationId": "china-projects-v2", "summary": "China dev-finance projects", "tags": [ "China" ], "description": "China overseas development-finance projects (AidData GCDF) — amounts, sector, status, financiers; joinable to the live event stream by country. Requires a plan with China development finance access (`can_use_china`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Project title search." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "Kenya" }, "description": "Recipient country. Accepts a country name (`Kenya`), ISO-2 (`KE`), or ISO-3 (`KEN`) via the shared `resolveCountryInput` layer (comma-separated list allowed; combinable with `region`/`continent`). Alias `recipient_country` is accepted; an unresolvable value returns `400 INVALID_COUNTRY`. Full value list: https://docs.gdeltcloud.com/reference/enums#country" }, { "name": "sector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sector filter. Observed vocabulary, measured 2026-08-10 (24 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=sector`. AidData's OECD-DAC sector name, stored verbatim and matched case-insensitively. Ours to serve, not ours to define — it changes when AidData republishes GCDF. The filter does not validate, so an unlisted sector returns an empty 200. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_sector" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Recipient region — expanded to an ISO-3 country set and combinable with `country`/`continent`. Accepts the same plain-English region vocabulary as the events/stories `region` filter (e.g. `Africa`, `East Asia`, `South America`); an unresolvable value returns 400." }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Recipient continent — expanded to an ISO-3 country set. Accepts `Africa`, `Asia`, `Europe`, `North America`, `South America`, or `Oceania`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Project status, matched case-insensitively (e.g. `Completion`, `Implementation`, `Pipeline: Commitment`, `Suspended`, `Cancelled`). An unknown value returns 0 rows rather than a 400. Observed vocabulary, measured 2026-08-10 (6 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=status`. AidData's project status. Note the two `Pipeline: …` values contain a colon and a space — a picker that offers a slugified form will silently match nothing. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_status" }, { "name": "flow_class", "in": "query", "required": false, "schema": { "type": "string" }, "description": "OECD-style flow class, matched case-insensitively (e.g. `ODA-like`, `OOF-like`, `Vague (Official Finance)`). Unknown values return 0 rows. Observed vocabulary, measured 2026-08-10 (3 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=flow_class`. AidData's ODA-like / OOF-like concessionality class. Unvalidated at the serve layer. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_flow_class" }, { "name": "intent", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Funding intent, matched case-insensitively (e.g. `Development`, `Commercial`, `Representational`, `Mixed`). Unknown values return 0 rows. Observed vocabulary, measured 2026-08-10 (4 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=intent`. AidData's donor-intent classification. Unvalidated at the serve layer. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_intent" }, { "name": "financier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match a funding agency or co-financier (case-insensitive substring) — the marquee \"who funded it\" filter. Alias: `funder`." }, { "name": "min_amount_usd", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Constant-USD floor on the project amount; `0` is a no-op. Alias: `min_amount`." }, { "name": "geocoded_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, restrict to projects that carry geocoordinates." }, { "name": "year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2035 }, "description": "Minimum commitment year (1990–2035)." }, { "name": "year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2035 }, "description": "Maximum commitment year (1990–2035)." }, { "name": "completion_year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2050 }, "description": "Minimum project completion year (1990–2050), filtered on `completion_year`. Symmetric with `year_min`/`year_max` (which filter commitment year)." }, { "name": "completion_year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2050 }, "description": "Maximum project completion year (1990–2050), filtered on `completion_year`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "amount_desc", "recent" ] }, "description": "amount_desc | recent. Full value list: https://docs.gdeltcloud.com/reference/enums#china_projects_sort" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (opaque offset)." } ], "responses": { "200": { "description": "China dev-finance projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "project_id": { "type": "string" }, "title": { "type": "string" }, "country": { "type": "string" }, "country_iso3": { "type": "string" }, "region": { "type": "string" }, "sector": { "type": "string" }, "status": { "type": "string" }, "flow_type": { "type": "string" }, "flow_class": { "type": "string" }, "intent": { "type": "string" }, "commitment_year": { "type": "integer" }, "completion_year": { "type": "integer" }, "amount_usd_constant": { "type": "integer" }, "amount_usd_nominal": { "type": "integer" }, "funders": { "type": "array", "items": { "type": "string" } }, "co_financiers": { "type": "array", "items": {} }, "lat": { "type": "number" }, "lon": { "type": "number" }, "geo_precision": { "type": "string" }, "source_urls": { "type": "array", "items": { "type": "string" } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": { "type": "string" } } }, "sort": { "type": "string" }, "applied_filters": { "type": "object", "properties": { "financier": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/china/projects — example response", "value": { "success": true, "data": [ { "project_id": "61576", "title": "China Eximbank Provides $3.6 Billion Loan for Coca Codo Sinclair Hydroelectric Project", "country": "Ecuador", "country_iso3": "ECU", "region": "Americas", "sector": "Energy", "status": "Completion", "flow_type": "Loan", "flow_class": "ODA-like", "intent": "Development", "commitment_year": 2010, "completion_year": 2016, "amount_usd_constant": 2245100000, "amount_usd_nominal": 1682700000, "funders": [ "Export-Import Bank of China" ], "co_financiers": [], "lat": -0.130556, "lon": -77.535833, "geo_precision": "point", "source_urls": [ "https://www.celec.gob.ec/cocacodosinclair/", "https://www.reuters.com/article/ecuador-china-dam-idUSL1N1V40QJ" ] }, { "project_id": "58921", "title": "China Development Bank Provides $1.5 Billion Loan for Mombasa-Nairobi Standard Gauge Railway (Phase 1)", "country": "Kenya", "country_iso3": "KEN", "region": "Africa", "sector": "Transport and Storage", "status": "Completion", "flow_type": "Loan", "flow_class": "OOF-like", "intent": "Mixed", "commitment_year": 2014, "completion_year": 2017, "amount_usd_constant": 1612400000, "amount_usd_nominal": 1500000000, "funders": [ "China Development Bank" ], "co_financiers": [ "Export-Import Bank of China" ], "lat": -1.292066, "lon": 36.821946, "geo_precision": "ADM1", "source_urls": [ "https://www.krc.co.ke/standard-gauge-railway/" ] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "25" }, "sort": "amount_desc", "applied_filters": { "financier": "China Development Bank", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/china/projects/summary": { "get": { "operationId": "china-projects-summary-v2", "summary": "China dev-finance rollup", "tags": [ "China" ], "description": "Rollup of China overseas development finance by country, sector, status, commitment year, flow class, or funding intent — counts + total committed USD. Requires a plan with China development finance access (`can_use_china`) — the Corporate & Supply Chain plan and above.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Recipient country filter. Accepts a country name, ISO-2, or ISO-3 via the shared `resolveCountryInput` layer (comma-separated list allowed; combinable with `region`/`continent`); an unresolvable value returns `400 INVALID_COUNTRY`." }, { "name": "sector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sector filter. Observed vocabulary, measured 2026-08-10 (24 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=sector`. AidData's OECD-DAC sector name, stored verbatim and matched case-insensitively. Ours to serve, not ours to define — it changes when AidData republishes GCDF. The filter does not validate, so an unlisted sector returns an empty 200. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_sector" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Project title search (alias `q`)." }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Recipient region — expanded to an ISO-3 country set and combinable with `country`/`continent`. Same plain-English region vocabulary as the events/stories `region` filter; an unresolvable value returns 400." }, { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Recipient continent — `Africa`, `Asia`, `Europe`, `North America`, `South America`, or `Oceania`." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Project status, matched case-insensitively (e.g. `Completion`, `Implementation`, `Pipeline: Commitment`). Unknown values return 0 rows rather than a 400. Observed vocabulary, measured 2026-08-10 (6 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=status`. AidData's project status. Note the two `Pipeline: …` values contain a colon and a space — a picker that offers a slugified form will silently match nothing. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_status" }, { "name": "flow_class", "in": "query", "required": false, "schema": { "type": "string" }, "description": "OECD-style flow class, matched case-insensitively (e.g. `ODA-like`, `OOF-like`). Observed vocabulary, measured 2026-08-10 (3 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=flow_class`. AidData's ODA-like / OOF-like concessionality class. Unvalidated at the serve layer. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_flow_class" }, { "name": "intent", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Funding intent, matched case-insensitively (e.g. `Development`, `Commercial`, `Mixed`). Observed vocabulary, measured 2026-08-10 (4 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/china/projects/summary?group_by=intent`. AidData's donor-intent classification. Unvalidated at the serve layer. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#china_intent" }, { "name": "financier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match a funding agency or co-financier (case-insensitive substring). Alias: `funder`." }, { "name": "min_amount_usd", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Constant-USD floor on the project amount; `0` is a no-op. Alias: `min_amount`." }, { "name": "geocoded_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, restrict to projects that carry geocoordinates." }, { "name": "year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2035 }, "description": "Minimum commitment year (1990–2035)." }, { "name": "year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2035 }, "description": "Maximum commitment year (1990–2035)." }, { "name": "completion_year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2050 }, "description": "Minimum project completion year (1990–2050)." }, { "name": "completion_year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1990, "maximum": 2050 }, "description": "Maximum project completion year (1990–2050)." }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "country", "sector", "status", "year", "flow_class", "intent" ], "default": "country" }, "description": "Bucket dimension. Each row is keyed by the active dimension (see the response schema). Full value list: https://docs.gdeltcloud.com/reference/enums#china_projects_group_by" }, { "name": "summary_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Max buckets returned (1–500, default 100), ordered by total committed USD then project count." } ], "responses": { "200": { "description": "China dev-finance rollup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "group_by": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "Each row is keyed by the active group_by dimension: country_iso3 (plus a readable country label) for group_by=country, commitment_year for group_by=year, or sector / status / flow_class / intent for those dimensions. Only the key(s) for the selected dimension are present.", "properties": { "country_iso3": { "type": "string", "description": "Bucket key when group_by=country." }, "country": { "type": "string", "nullable": true, "description": "Readable recipient-country name accompanying country_iso3 when group_by=country (null for AidData regional groupings)." }, "commitment_year": { "type": "integer", "description": "Bucket key when group_by=year." }, "sector": { "type": "string", "description": "Bucket key when group_by=sector." }, "status": { "type": "string", "description": "Bucket key when group_by=status." }, "flow_class": { "type": "string", "description": "Bucket key when group_by=flow_class." }, "intent": { "type": "string", "description": "Bucket key when group_by=intent." }, "project_count": { "type": "integer" }, "amount_usd_total": { "type": "integer" } } } }, "applied_filters": { "type": "object", "properties": { "sector": { "type": "string" }, "group_by": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/china/projects/summary — example response", "value": { "success": true, "group_by": "country", "data": [ { "country_iso3": "PAK", "country": "Pakistan", "project_count": 142, "amount_usd_total": 47218900000 }, { "country_iso3": "AGO", "country": "Angola", "project_count": 97, "amount_usd_total": 42960300000 } ], "applied_filters": { "sector": "Energy", "group_by": "country", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/transits": { "get": { "operationId": "list-maritime-transits-v2", "summary": "Chokepoint transit activity", "tags": [ "Maritime" ], "description": "Hourly vessel-flow rollup for maritime chokepoints, derived from terrestrial AIS. Each row is one chokepoint·hour with vessel counts and average speed. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nForward-accruing: signals begin at launch (June 2026) — there is no historical backfill. Derived-only: no raw position track is exposed. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 7 days when no dates are given.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to one chokepoint (one of the 11 monitored straits). Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30). Defaults to 7." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of chokepoint·hour rows, most recent first. Each row: chokepoint, hour, vessels, moving_vessels, avg_sog (average speed over ground, knots), positions (AIS message count). Standard envelope: { success, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "chokepoint": { "type": "string" }, "hour": { "type": "string" }, "vessels": { "type": "integer" }, "moving_vessels": { "type": "integer" }, "avg_sog": { "type": "number" }, "positions": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "chokepoint": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/transits — example response", "value": { "success": true, "data": [ { "chokepoint": "hormuz", "hour": "2026-06-14 09:00:00", "vessels": 142, "moving_vessels": 118, "avg_sog": 9.4, "positions": 1873 }, { "chokepoint": "bab_el_mandeb", "hour": "2026-06-14 09:00:00", "vessels": 87, "moving_vessels": 79, "avg_sog": 11.2, "positions": 1104 } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-06-08", "date_end": "2026-06-14", "chokepoint": "hormuz", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/vessels": { "get": { "operationId": "list-maritime-vessels-v2", "summary": "Current vessels (last-known)", "tags": [ "Maritime" ], "description": "Current vessels with their last-known position and identity, derived from terrestrial AIS. Positions are LAST-KNOWN ONLY — there is no raw position-track endpoint. This is current state, so it takes no date window. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nForward-accruing: vessel state begins at launch (June 2026). Terrestrial AIS only (no satellite).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to vessels whose last-known position is in this chokepoint. Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search vessels by name (case-insensitive substring, ngram-indexed), IMO, MMSI, or call sign." }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box filter: minLon,minLat,maxLon,maxLat (e.g. 103,1,105,2)." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius search; combine with radius_km. Results include distance_km, sorted nearest-first. Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id (resolved via gem.assets_view) — returns vessels within radius_km of that LNG terminal / platform / port. The cross-source 'vessels near energy infrastructure' join." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 50 (near) or 25 (near_gem_id); clamped 1–2000." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of vessels, most recently seen first (or nearest-first when near / near_gem_id is set). Each row: mmsi, imo, name, ship_type, ship_type_code, flag (ISO-3), call_sign, length_m, width_m, draught_m, lat, lon, chokepoint, sog (speed over ground, knots), last_time, gem_id (Global Energy Monitor link when matched), and distance_km (km from the near / near_gem_id center, only present when one is set). Standard envelope: { success, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "mmsi": { "type": "integer" }, "imo": { "type": "string" }, "name": { "type": "string" }, "ship_type": { "type": "string" }, "ship_type_code": { "type": "integer" }, "flag": { "type": "string" }, "call_sign": { "type": "string" }, "length_m": { "type": "integer" }, "width_m": { "type": "integer" }, "draught_m": { "type": "number" }, "chokepoint": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "sog": { "type": "number" }, "last_time": { "type": "string" }, "gem_id": { "type": "string" }, "distance_km": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "chokepoint": { "type": "string" }, "near": { "type": "string" }, "radius_km": { "type": "integer" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/vessels — example response", "value": { "success": true, "data": [ { "mmsi": 636019825, "imo": "9006681", "name": "AL GHARRAFA", "ship_type": "LNG Tanker", "ship_type_code": 80, "flag": "LBR", "call_sign": "A8XY9", "length_m": 315, "width_m": 50, "draught_m": 12.4, "chokepoint": "hormuz", "lat": 26.5731, "lon": 56.2489, "sog": 12.7, "last_time": "2026-06-14 08:42:11", "gem_id": "G100000110234", "distance_km": 18.3 }, { "mmsi": 538008914, "imo": "9388893", "name": "MARAN GAS APOLLONIA", "ship_type": "LNG Tanker", "ship_type_code": 80, "flag": "MHL", "call_sign": "V7DA3", "length_m": 290, "width_m": 46, "draught_m": 11.1, "chokepoint": "hormuz", "lat": 26.6102, "lon": 56.3017, "sog": 0.2, "last_time": "2026-06-14 07:55:48", "gem_id": null, "distance_km": 24.7 } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "chokepoint": "hormuz", "near": "26.5,56.25", "radius_km": 50, "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/carriers/{imo}": { "get": { "operationId": "get-maritime-carrier-v2", "summary": "Vessel by IMO", "tags": [ "Maritime" ], "description": "One vessel by IMO number: identity, last-known position, and the matched Global Energy Monitor LNG carrier (when one exists). Position is LAST-KNOWN ONLY — no raw track. Returns 404 when no vessel identity exists for the IMO. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nForward-accruing: position history begins at launch (June 2026). Terrestrial AIS only (no satellite).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "imo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "IMO number of the vessel (e.g. 9006681)." } ], "responses": { "200": { "description": "Vessel detail. `identity` carries imo, mmsi, name, ship_type, ship_type_code, call_sign, flag (ISO-3), length_m, width_m, draught_m, gem_id. `last_position` is the last-known { lat, lon, chokepoint, last_time, sog } or null. `gem_carrier` is the matched Global Energy Monitor LNG carrier { gem_id, name, imo_number } or null. Envelope: { success, imo, identity, last_position, gem_carrier }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "imo": { "type": "string" }, "identity": { "type": "object", "properties": { "imo": { "type": "string" }, "mmsi": { "type": "integer" }, "name": { "type": "string" }, "ship_type": { "type": "string" }, "ship_type_code": { "type": "integer" }, "call_sign": { "type": "string" }, "flag": { "type": "string" }, "length_m": { "type": "integer" }, "width_m": { "type": "integer" }, "draught_m": { "type": "number" }, "gem_id": { "type": "string" } } }, "last_position": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "chokepoint": { "type": "string" }, "last_time": { "type": "string" }, "sog": { "type": "number" } } }, "gem_carrier": { "type": "object", "properties": { "gem_id": { "type": "string" }, "name": { "type": "string" }, "imo_number": { "type": "string" } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/carriers/{imo} — example response", "value": { "success": true, "imo": "9006681", "identity": { "imo": "9006681", "mmsi": 636019825, "name": "AL GHARRAFA", "ship_type": "LNG Tanker", "ship_type_code": 80, "call_sign": "A8XY9", "flag": "LBR", "length_m": 315, "width_m": 50, "draught_m": 12.4, "gem_id": "G100000110234" }, "last_position": { "lat": 26.5731, "lon": 56.2489, "chokepoint": "hormuz", "last_time": "2026-06-14 08:42:11", "sog": 12.7 }, "gem_carrier": { "gem_id": "G100000110234", "name": "Al Gharrafa", "imo_number": "9006681.0" } } } } } } }, "400": { "description": "Invalid IMO (INVALID_IMO)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Vessel not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/dwell": { "get": { "operationId": "list-maritime-dwell-v2", "summary": "Chokepoint dwell episodes", "tags": [ "Maritime" ], "description": "Dwell episodes — completed arrival→departure stays at maritime chokepoints, derived from terrestrial AIS. Each row is one vessel's stay with its dwell duration. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nForward-accruing: episodes begin accruing at launch (June 2026) — no historical backfill. Derived-only: no raw position track. Terrestrial AIS only (no satellite). Filtered by departure time; date windows are capped at 30 days and default to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to one chokepoint. Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ongoing", "completed" ] }, "description": "`ongoing` = the vessel is still inside the chokepoint at the rollup edge (its `dwell_hours` is elapsed-so-far and `departure` is an as-of timestamp, not final); `completed` = the vessel has departed. Omit for both. An unknown value returns 400 INVALID_ENUM. Full value list: https://docs.gdeltcloud.com/reference/enums#maritime_dwell_status" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Departure-window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Departure-window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30). Defaults to 7." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of dwell episodes, by departure time (most recent first). Each row: imo, mmsi, chokepoint, arrival, departure, dwell_hours. Standard envelope: { success, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "imo": { "type": "string" }, "mmsi": { "type": "integer" }, "chokepoint": { "type": "string" }, "arrival": { "type": "string" }, "departure": { "type": "string" }, "dwell_hours": { "type": "number" }, "status": { "type": "string", "description": "`ongoing` (still inside the chokepoint at the rollup edge; `departure`/`dwell_hours` are as-of) or `completed` (the vessel has departed)." } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "chokepoint": { "type": "string" }, "status": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/dwell — example response", "value": { "success": true, "data": [ { "imo": "9006681", "mmsi": 636019825, "chokepoint": "hormuz", "arrival": "2026-06-11 22:18:40", "departure": "2026-06-13 06:51:09", "dwell_hours": 32.5 }, { "imo": "9388893", "mmsi": 538008914, "chokepoint": "hormuz", "arrival": "2026-06-12 14:02:33", "departure": "2026-06-12 19:47:55", "dwell_hours": 5.8 } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-06-08", "date_end": "2026-06-14", "chokepoint": "hormuz", "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/gaps": { "get": { "operationId": "list-maritime-gaps-v2", "summary": "AIS-dark gaps", "tags": [ "Maritime" ], "description": "AIS-dark gaps — intervals where a vessel stopped broadcasting AIS then reappeared, derived from terrestrial AIS coverage. Each row is one gap with the last-known position before it went dark. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nForward-accruing: gaps begin accruing at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite); a gap reflects loss of terrestrial reception, not necessarily a deliberate dark event. Filtered by gap-end time; date windows are capped at 30 days and default to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to gaps whose last-known chokepoint is this one. Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "min_gap_hours", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "default": 6 }, "description": "Minimum gap duration in hours. Defaults to 6." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gap-end-window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gap-end-window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30). Defaults to 7." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of AIS-dark gaps, longest first. Each row: imo, mmsi, gap_start, gap_end, gap_hours, last_lat, last_lon, chokepoint (last-known before going dark). Standard envelope: { success, data, pagination, applied_filters }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "imo": { "type": "string" }, "mmsi": { "type": "integer" }, "gap_start": { "type": "string" }, "gap_end": { "type": "string" }, "gap_hours": { "type": "number" }, "last_lat": { "type": "number" }, "last_lon": { "type": "number" }, "chokepoint": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "chokepoint": { "type": "string" }, "min_gap_hours": { "type": "integer" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/gaps — example response", "value": { "success": true, "data": [ { "imo": "9388893", "mmsi": 538008914, "gap_start": "2026-06-10 02:11:09", "gap_end": "2026-06-11 19:43:27", "gap_hours": 41.5, "last_lat": 26.4412, "last_lon": 56.5108, "chokepoint": "hormuz" }, { "imo": null, "mmsi": 477553000, "gap_start": "2026-06-12 08:30:55", "gap_end": "2026-06-12 21:14:02", "gap_hours": 12.7, "last_lat": 13.2204, "last_lon": 43.4891, "chokepoint": "bab_el_mandeb" } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-06-08", "date_end": "2026-06-14", "chokepoint": "hormuz", "min_gap_hours": 6, "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/activity": { "get": { "operationId": "list-maritime-activity-v2", "summary": "Area activity over time", "tags": [ "Maritime" ], "description": "Aggregate vessel activity over an area, bucketed by hour or day — distinct vessels, total + moving positions, and average/max speed per bucket. Generalizes /transits to arbitrary geography (chokepoint, bounding box, or proximity). The \"is this area's traffic anomalous vs the baseline\" view. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nHistorical / baseline surface: reads raw AIS positions directly (not the derived rollups). Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 14 days. Bucket auto-selects hour for spans ≤2 days, otherwise day.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to one chokepoint. Omit to use bbox / near / near_gem_id, or for global. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first axis order, e.g. 56,26,57,27)." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius area; combine with radius_km (default 50 km). Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id center — traffic within radius_km of that LNG terminal / platform (default 25 km). The cross-source 'traffic near energy infrastructure' join." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 50 (near) or 25 (near_gem_id); clamped 1–2000." }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hour", "day" ] }, "description": "Time bucket. Auto-selects hour for spans ≤2 days, otherwise day. Full value list: https://docs.gdeltcloud.com/reference/enums#maritime_activity_bucket" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30). Defaults to 14." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "minimum": 1, "maximum": 1000 }, "description": "Buckets per page (1–1000)." } ], "responses": { "200": { "description": "Bucketed activity, most recent first. Envelope: { success, bucket ('hour'|'day'), data, pagination, applied_filters }. Each data row: bucket (timestamp), vessels (distinct mmsi), positions (AIS message count), moving_positions (sog > 1), avg_sog, max_sog (knots).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bucket": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "vessels": { "type": "integer" }, "positions": { "type": "integer" }, "moving_positions": { "type": "integer" }, "avg_sog": { "type": "number" }, "max_sog": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "chokepoint": { "type": "string" }, "bucket": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/activity — example response", "value": { "success": true, "bucket": "day", "data": [ { "bucket": "2026-06-14 00:00:00", "vessels": 318, "positions": 24117, "moving_positions": 19842, "avg_sog": 8.7, "max_sog": 22.4 }, { "bucket": "2026-06-13 00:00:00", "vessels": 341, "positions": 26508, "moving_positions": 21733, "avg_sog": 9.1, "max_sog": 23.8 } ], "pagination": { "limit": 200, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-06-01", "date_end": "2026-06-14", "chokepoint": "hormuz", "bucket": "day", "ignored": {} } } } } } } }, "400": { "description": "Invalid parameter (e.g. INVALID_BBOX, INVALID_NEAR, INVALID_RADIUS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/density": { "get": { "operationId": "list-maritime-density-v2", "summary": "Spatial density grid", "tags": [ "Maritime" ], "description": "Spatial density grid (heatmap) of position and vessel counts per lat/lon cell within an area. Shows where traffic concentrates. AREA REQUIRED — pass bbox, near, or near_gem_id. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nHistorical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 7 days; defaults to the trailing 1 day.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first axis order). One of bbox / near / near_gem_id is required." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius area; combine with radius_km (default 50 km). One of bbox / near / near_gem_id is required. Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id center — concentration of traffic within radius_km of that asset (default 25 km). One of bbox / near / near_gem_id is required." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 50 (near) or 25 (near_gem_id); clamped 1–2000." }, { "name": "cell_deg", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0.01, "maximum": 1, "default": 0.05 }, "description": "Grid cell size in degrees (0.01–1). Smaller = finer heatmap. Defaults to 0.05." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤7-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Trailing N-day window (1–7). Defaults to 1." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 500, "minimum": 1, "maximum": 5000 }, "description": "Grid cells per page (1–5000), densest first." } ], "responses": { "200": { "description": "Density grid, densest cells first. Envelope: { success, cell_deg, data, pagination, applied_filters }. Each data row: cell_lat, cell_lon (cell SW/lower corner, degrees), positions (AIS message count), vessels (distinct mmsi).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cell_deg": { "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "cell_lat": { "type": "number" }, "cell_lon": { "type": "number" }, "positions": { "type": "integer" }, "vessels": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "cell_deg": { "type": "number" }, "bbox": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/density — example response", "value": { "success": true, "cell_deg": 0.05, "data": [ { "cell_lat": 26.55, "cell_lon": 56.25, "positions": 4821, "vessels": 73 }, { "cell_lat": 26.6, "cell_lon": 56.3, "positions": 3947, "vessels": 61 } ], "pagination": { "limit": 500, "cursor": null, "next_cursor": null }, "applied_filters": { "date_start": "2026-06-13", "date_end": "2026-06-14", "cell_deg": 0.05, "bbox": "54.0,25.5,57.5,27.5", "ignored": {} } } } } } } }, "400": { "description": "Area required or invalid parameter (AREA_REQUIRED, INVALID_BBOX, INVALID_NEAR, INVALID_RADIUS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/tracks": { "get": { "operationId": "list-maritime-tracks-v2", "summary": "Raw position points in an area", "tags": [ "Maritime" ], "description": "⚠️ RAW position points (the actual AIS track) inside an area over time — each row a single fix (time, position, speed, course, nav status). AREA REQUIRED — pass chokepoint, bbox, near, or near_gem_id. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one giant response. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nHistorical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 7 days; defaults to the trailing 1 day.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "One chokepoint as the area. One of chokepoint / bbox / near / near_gem_id is required. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first axis order). One of chokepoint / bbox / near / near_gem_id is required." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius area; combine with radius_km (default 50 km). Rows include distance_km. One of chokepoint / bbox / near / near_gem_id is required. Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id center — points within radius_km of that asset (default 25 km). Rows include distance_km. One of chokepoint / bbox / near / near_gem_id is required." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 50 (near) or 25 (near_gem_id); clamped 1–2000." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤7-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Trailing N-day window (1–7). Defaults to 1." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 1000, "minimum": 1, "maximum": 5000 }, "description": "Position points per page (1–5000)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque keyset cursor on (time, mmsi). Pass back a prior response's next_cursor to fetch the next page; do not request one giant response." } ], "responses": { "200": { "description": "A page of raw position points, time-ordered ascending. Envelope: { success, data, pagination, applied_filters }. Each data row: time, mmsi, imo, lat, lon, sog, cog, nav_status, chokepoint, and distance_km (km from the near / near_gem_id center, only when one is set). pagination.next_cursor is an opaque token — follow it to page through a long window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "mmsi": { "type": "integer" }, "imo": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "sog": { "type": "number" }, "cog": { "type": "number" }, "nav_status": { "type": "string" }, "chokepoint": { "type": "string" }, "distance_km": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": { "type": "string" } } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "chokepoint": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/tracks — example response", "value": { "success": true, "data": [ { "time": "2026-06-13 00:01:48", "mmsi": 636019825, "imo": "9006681", "lat": 26.5419, "lon": 56.2731, "sog": 12.9, "cog": 299.1, "nav_status": "under_way", "chokepoint": "hormuz", "distance_km": 21.4 }, { "time": "2026-06-13 00:01:52", "mmsi": 538008914, "imo": "9388893", "lat": 26.6088, "lon": 56.3142, "sog": 0.1, "cog": 0, "nav_status": "at_anchor", "chokepoint": "hormuz", "distance_km": 28.9 } ], "pagination": { "limit": 1000, "cursor": null, "next_cursor": "MjAyNi0wNi0xMyAwMDowMTo1Mnw1MzgwMDg5MTQ=" }, "applied_filters": { "date_start": "2026-06-12", "date_end": "2026-06-13", "chokepoint": "hormuz", "ignored": {} } } } } } } }, "400": { "description": "Area required or invalid parameter (AREA_REQUIRED, INVALID_BBOX, INVALID_NEAR, INVALID_RADIUS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/vessels/{imo}/track": { "get": { "operationId": "get-maritime-vessel-track-v2", "summary": "One vessel's track over time", "tags": [ "Maritime" ], "description": "⚠️ RAW position track for a single vessel by IMO — the literal 'this ship over time': every AIS fix (time, position, speed, course, heading, nav status) across the window, time-ordered. Keyset-paginated: follow the opaque next_cursor to stitch a long window into pages rather than one giant response. Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nHistorical / baseline surface: reads raw AIS positions directly. Forward-accruing: positions begin at launch (June 2026) — no historical backfill. Terrestrial AIS only (no satellite). Date windows are capped at 30 days; defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "imo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "IMO number of the vessel (e.g. 9006681)." }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start YYYY-MM-DD (≤30-day window)." }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end YYYY-MM-DD." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Trailing N-day window (1–30). Defaults to 7." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 1000, "minimum": 1, "maximum": 5000 }, "description": "Position points per page (1–5000)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque keyset cursor on (time, mmsi). Pass back a prior response's next_cursor to fetch the next page; do not request one giant response." } ], "responses": { "200": { "description": "A page of the vessel's raw position track, time-ordered ascending. Envelope: { success, imo, data, pagination, applied_filters }. Each data row: time, mmsi, lat, lon, sog, cog, heading, nav_status, chokepoint. pagination.next_cursor is an opaque token — follow it to page through a long window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "imo": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "mmsi": { "type": "integer" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "sog": { "type": "number" }, "cog": { "type": "number" }, "heading": { "type": "integer" }, "nav_status": { "type": "string" }, "chokepoint": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": { "type": "string" } } }, "applied_filters": { "type": "object", "properties": { "date_start": { "type": "string" }, "date_end": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/vessels/{imo}/track — example response", "value": { "success": true, "imo": "9006681", "data": [ { "time": "2026-06-12 03:14:07", "mmsi": 636019825, "lat": 25.9831, "lon": 56.7042, "sog": 13.1, "cog": 298.4, "heading": 301, "nav_status": "under_way", "chokepoint": "hormuz" }, { "time": "2026-06-12 04:46:52", "mmsi": 636019825, "lat": 26.4127, "lon": 56.2188, "sog": 12.6, "cog": 305.2, "heading": 307, "nav_status": "under_way", "chokepoint": "hormuz" } ], "pagination": { "limit": 1000, "cursor": null, "next_cursor": "MjAyNi0wNi0xMiAwNDo0Njo1Mnw2MzYwMTk4MjU=" }, "applied_filters": { "date_start": "2026-06-05", "date_end": "2026-06-12", "ignored": {} } } } } } } }, "400": { "description": "Missing/invalid IMO (MISSING_PARAM)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/ports": { "get": { "operationId": "list-maritime-ports-v2", "summary": "Ports reference", "tags": [ "Maritime" ], "description": "The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft, channel depth, and container / oil / LNG terminal facilities. Filter by country, harbor size, terminal type, name, or proximity to a point / GEM energy asset. This is reference data (no date window). Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nWhen a proximity center is set (`near`, `near_gem_id`), each row carries `distance_km` and results sort nearest-first. Standard envelope: `{ success, data, pagination, applied_filters }`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive match on port name, alternate name, or UN/LOCODE." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter on ports. Accepts a country name, ISO-2, or ISO-3 (e.g. `Netherlands`, `NL`, `NLD`) via the shared `resolveCountryInput` layer; an unresolvable value returns `400 INVALID_COUNTRY`. Full value list: https://docs.gdeltcloud.com/reference/enums#country" }, { "name": "min_harbor_size", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "very_small", "small", "medium", "large" ] }, "description": "Minimum harbor size (inclusive of larger sizes). Full value list: https://docs.gdeltcloud.com/reference/enums#min_harbor_size" }, { "name": "lng_terminal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only ports with an LNG terminal." }, { "name": "oil_terminal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only ports with an oil terminal." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius search; combine with radius_km (default 100). Results carry distance_km, sorted nearest-first. Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id — returns ports within radius_km of that LNG terminal / platform / port (cross-source join)." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 100; clamped 1–2000." }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first, e.g. -6,35,5,44)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Rows per page (1–500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor (offset) from a prior response's next_cursor." } ], "responses": { "200": { "description": "A page of ports. Each row: port_id, name, alt_name, unlocode, country (ISO-3), country_name, region, water_body, lat, lon, harbor_size, harbor_type, harbor_use, max_vessel_draft_m, channel_depth_m, lng_terminal / oil_terminal / container booleans, and distance_km (only when a proximity center is set).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "port_id": { "type": "string" }, "name": { "type": "string" }, "alt_name": { "type": "string", "nullable": true }, "unlocode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "country_name": { "type": "string" }, "region": { "type": "string" }, "water_body": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "harbor_size": { "type": "string" }, "harbor_type": { "type": "string" }, "harbor_use": { "type": "string" }, "max_vessel_draft_m": { "type": "number" }, "channel_depth_m": { "type": "number" }, "lng_terminal": { "type": "boolean" }, "oil_terminal": { "type": "boolean" }, "container": { "type": "boolean" }, "distance_km": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": {}, "next_cursor": {} } }, "applied_filters": { "type": "object", "properties": { "search": { "type": "string" }, "country": { "type": "string" }, "min_harbor_size": { "type": "string" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/ports?lng_terminal=true — example response", "value": { "success": true, "data": [ { "port_id": "NLRTM", "name": "Rotterdam", "alt_name": "Rotterdam", "unlocode": "NLRTM", "country": "NLD", "country_name": "Netherlands", "region": "Western Europe", "water_body": "North Sea", "lat": 51.95, "lon": 4.14, "harbor_size": "Large", "harbor_type": "Coastal Natural", "harbor_use": "Commercial", "max_vessel_draft_m": 24.4, "channel_depth_m": 24.4, "lng_terminal": true, "oil_terminal": true, "container": true } ], "pagination": { "limit": 100, "cursor": null, "next_cursor": null }, "applied_filters": { "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/port-pulse": { "get": { "operationId": "list-maritime-port-pulse-v2", "summary": "Port disruption pulse", "tags": [ "Maritime" ], "description": "Port-level disruption intelligence — geo-fuses the WPI ports reference with GDELT events near each port (within `event_radius_km` over the last `days`): relevant-event volume, conflict signal, a 7d-vs-baseline anomaly ratio, recent headlines, nearby flagged-energy-asset exposure, and AIS-coverage context. Scope by country, terminal type, name, or proximity; with no scope it defaults to strategic ports (LNG/oil terminals + large harbors). Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nEach row scores a `pulse_level` (critical / elevated / active / quiet) and rows are risk-ranked. Envelope: `{ success, data, summary, applied_filters }`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country filter on port-pulse. Accepts a country name, ISO-2, or ISO-3 (e.g. `Ukraine`, `UA`, `UKR`) via the shared `resolveCountryInput` layer; an unresolvable value returns `400 INVALID_COUNTRY`." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive match on port name, alternate name, or UN/LOCODE." }, { "name": "lng_terminal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only ports with an LNG terminal." }, { "name": "oil_terminal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only ports with an oil terminal." }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "example": "51.5,-0.12" }, "description": "Point 'lat,lon' for a radius search; combine with radius_km (default 200). Format: lat,lon — pass the radius separately in radius_km." }, { "name": "near_gem_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "GEM energy-asset gem_id — scope to ports within radius_km of that asset (cross-source join)." }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Radius in km for near / near_gem_id. Default 200; clamped 1–2000." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 14 }, "description": "GDELT event window in days (1–30). Defaults to 14." }, { "name": "event_radius_km", "in": "query", "required": false, "schema": { "type": "number", "minimum": 5, "maximum": 500, "default": 50 }, "description": "How close an event must be to a port to count it (5–500 km). Defaults to 50." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 }, "description": "Number of ports to score (1–50). Defaults to 20." } ], "responses": { "200": { "description": "Risk-ranked ports with their pulse. Each row: port_id, name, unlocode, country, lat, lon, harbor_size, lng_terminal / oil_terminal, relevant_events, conflict_events, events_last_7d, anomaly_ratio, energy_exposure, pulse_level, ais_coverage, and up to 3 recent_events. A summary block totals the window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "port_id": { "type": "string" }, "name": { "type": "string" }, "unlocode": { "type": "string", "nullable": true }, "country": { "type": "string" }, "country_name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "harbor_size": { "type": "string" }, "lng_terminal": { "type": "boolean" }, "oil_terminal": { "type": "boolean" }, "relevant_events": { "type": "integer" }, "conflict_events": { "type": "integer" }, "events_last_7d": { "type": "integer" }, "anomaly_ratio": { "type": "number", "nullable": true, "description": "Last-7d event volume vs the windowed weekly baseline; null when there is no baseline." }, "energy_exposure": { "type": "object", "properties": { "assets_nearby": { "type": "integer" }, "state_owned": { "type": "integer" }, "sanctions": { "type": "integer" }, "china": { "type": "integer" } } }, "pulse_level": { "type": "string", "enum": [ "critical", "elevated", "active", "quiet" ] }, "ais_coverage": { "type": "string" }, "recent_events": { "type": "array", "items": { "type": "object", "properties": { "headline": { "type": "string" }, "family": { "type": "string" }, "event_date": { "type": "string" }, "distance_km": { "type": "integer" }, "cluster_id": { "type": "string" }, "cluster_date": { "type": "string" } } } } } } }, "summary": { "type": "object", "properties": { "ports": { "type": "integer" }, "window_days": { "type": "integer" }, "event_radius_km": { "type": "number" }, "ports_with_conflict": { "type": "integer" }, "ports_active": { "type": "integer" } } }, "applied_filters": { "type": "object", "properties": { "country": { "type": "string" }, "days": { "type": "integer" }, "event_radius_km": { "type": "number" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/port-pulse?country=UKR — example response", "value": { "success": true, "data": [ { "port_id": "UAODS", "name": "Odesa", "unlocode": "UAODS", "country": "UKR", "country_name": "Ukraine", "lat": 46.49, "lon": 30.74, "harbor_size": "Medium", "lng_terminal": false, "oil_terminal": true, "relevant_events": 37, "conflict_events": 12, "events_last_7d": 9, "anomaly_ratio": 1.35, "energy_exposure": { "assets_nearby": 2, "state_owned": 1, "sanctions": 0, "china": 0 }, "pulse_level": "critical", "ais_coverage": "no_ais", "recent_events": [ { "headline": "Port infrastructure struck in overnight attack", "family": "conflict", "event_date": "2026-06-13", "distance_km": 4, "cluster_id": "c_abc123", "cluster_date": "2026-06-13" } ] } ], "summary": { "ports": 6, "window_days": 14, "event_radius_km": 60, "ports_with_conflict": 4, "ports_active": 5 }, "applied_filters": { "country": "UKR", "days": 14, "event_radius_km": 60, "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/maritime/chokepoint-watch": { "get": { "operationId": "list-maritime-chokepoint-watch-v2", "summary": "Chokepoint risk watch", "tags": [ "Maritime" ], "description": "The maritime risk layer — fuses each chokepoint's AIS coverage confidence (live / sparse / dark) and 24h/7d transit activity with GDELT conflict events (last 7 days) in its bordering countries, plus nearby flagged-energy-asset exposure. Surfaces the 'blind spot': high conflict signal but no vessel coverage. Derived rollups + events only (no raw positions). Requires a plan with Maritime intelligence access (`can_use_maritime`) — the Corporate & Supply Chain plan and above.\n\nEach row scores a `risk_level` (critical / elevated / watch / quiet) and rows are risk-ranked. Envelope: `{ success, data, summary, applied_filters }`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "chokepoint", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hormuz", "bab_el_mandeb", "malacca", "suez", "panama", "bosphorus", "gibraltar", "dover", "kerch", "taiwan", "danish_straits" ] }, "description": "Restrict to one chokepoint (one of the 11 monitored straits). Omit for all. Full value list: https://docs.gdeltcloud.com/reference/enums#chokepoint" }, { "name": "blind_spots_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true → only chokepoints that are a blind spot (dark AIS coverage AND conflict signal in the bordering countries)." }, { "name": "min_conflict", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Only chokepoints with at least N GDELT conflict events in the last 7 days." } ], "responses": { "200": { "description": "Risk-ranked chokepoints. Each row: chokepoint, bordering countries, coverage (confidence + 24h/7d vessel counts + last_seen), conflict_events_7d, total_events_7d, blind_spot, risk_level, up to 3 recent_conflict_events, and energy_exposure. A summary block totals coverage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "chokepoint": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "properties": { "confidence": { "type": "string", "enum": [ "live", "sparse", "dark" ] }, "vessels_24h": { "type": "integer" }, "vessels_7d": { "type": "integer" }, "moving_24h": { "type": "integer" }, "positions_24h": { "type": "integer" }, "last_seen": { "type": "string", "nullable": true } } }, "conflict_events_7d": { "type": "integer" }, "total_events_7d": { "type": "integer" }, "blind_spot": { "type": "boolean" }, "risk_level": { "type": "string", "enum": [ "critical", "elevated", "watch", "quiet" ] }, "recent_conflict_events": { "type": "array", "items": { "type": "object", "properties": { "headline": { "type": "string" }, "event_date": { "type": "string" }, "cluster_id": { "type": "string" }, "cluster_date": { "type": "string" }, "country": { "type": "string" } } } }, "energy_exposure": { "type": "object", "properties": { "assets_nearby": { "type": "integer" }, "state_owned": { "type": "integer" }, "sanctions": { "type": "integer" }, "china": { "type": "integer" } } } } } }, "summary": { "type": "object", "properties": { "chokepoints": { "type": "integer" }, "live": { "type": "integer" }, "dark": { "type": "integer" }, "blind_spots": { "type": "integer" }, "window": { "type": "string" } } }, "applied_filters": { "type": "object", "properties": { "chokepoint": { "type": "string" }, "blind_spots_only": { "type": "boolean" }, "min_conflict": { "type": "number" }, "ignored": { "type": "object", "properties": {} } } } } }, "examples": { "example": { "summary": "GET /api/v2/maritime/chokepoint-watch?blind_spots_only=true — example response", "value": { "success": true, "data": [ { "chokepoint": "bab_el_mandeb", "countries": [ "YEM", "DJI", "ERI" ], "coverage": { "confidence": "dark", "vessels_24h": 0, "vessels_7d": 0, "moving_24h": 0, "positions_24h": 0, "last_seen": null }, "conflict_events_7d": 18, "total_events_7d": 44, "blind_spot": true, "risk_level": "critical", "recent_conflict_events": [ { "headline": "Vessel targeted off the Yemeni coast", "event_date": "2026-06-13", "cluster_id": "c_def456", "cluster_date": "2026-06-13", "country": "YEM" } ], "energy_exposure": { "assets_nearby": 3, "state_owned": 1, "sanctions": 1, "china": 0 } } ], "summary": { "chokepoints": 1, "live": 0, "dark": 1, "blind_spots": 1, "window": "7d conflict events · 24h/7d vessel coverage" }, "applied_filters": { "blind_spots_only": true, "ignored": {} } } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v2/intelligence/gpr": { "get": { "operationId": "get-intelligence-gpr-v2", "summary": "Atlas GPR — geopolitical risk vs a place’s own normal", "description": "Vintaged Atlas GPR readings for one explicit geographic level and place. Every accepted query parameter is declared here; undeclared geographic shortcuts such as `country=` fail with UNKNOWN_PARAM rather than returning the World series.", "tags": [ "Atlas Intelligence" ], "parameters": [ { "name": "construction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "own_coverage", "world_corpus" ], "default": "own_coverage" }, "description": "Index construction. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_gpr_construction", "example": "own_coverage" }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "events", "attention", "fullspectrum", "gpr" ], "default": "events" }, "description": "GPR lens. `lens` is the legacy alias. Also accepts: `lens`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_gpr_variant", "example": "events", "x-aliases": [ "lens" ] }, { "name": "component", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "threats", "acts", "verbal", "material" ], "default": "all" }, "description": "Variant-scoped decomposition component. `decompose` is the legacy alias. Also accepts: `decompose`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. The legal values DEPEND ON `variant`: `variant=events` → `all`, `threats`, `acts`, `verbal`, `material`; `variant=attention` → `all`; `variant=fullspectrum` → `all`, `threats`, `acts`, `verbal`, `material`; `variant=gpr` → `all`, `threats`, `acts`. The enum is the union across every `variant`. The events lens (and its `fullspectrum` storage alias) carries all five; the `gpr` lens is built from the threat/act partition only, so `verbal` and `material` do not exist for it; the attention lens is a single undecomposed series, so `all` is its only component. Measured against prod: 6 of the 15 pairs a flat 5-value enum implies cannot return a row. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_gpr_component", "example": "all", "x-aliases": [ "decompose" ] }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gpr", "pulse", "attention_share" ], "default": "gpr" }, "description": "Returned GPR measure. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_gpr_metric", "example": "gpr" }, { "name": "weighting", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "attention", "gdp" ], "default": "attention" }, "description": "Aggregate weighting. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_weighting", "example": "attention" }, { "name": "level", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "world", "continent", "region", "country" ], "default": "world" }, "description": "Geographic aggregation level. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_level", "example": "country" }, { "name": "geo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Place identifier appropriate for `level`; `id` is the legacy alias. Also accepts: `id`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "NGA", "x-aliases": [ "id" ] }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Trailing display window in days, 1–370. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "90" }, { "name": "date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "First observation date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-06-01" }, { "name": "date_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Last observation date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-21" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "One observation date; overrides the range. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20" }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Point-in-time vintage. `realtime_start` and `vintage` are aliases. Also accepts: `realtime_start`, `vintage`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "2026-08-20", "x-aliases": [ "realtime_start", "vintage" ] }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "description": "Maximum observations returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "100" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "100" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Legacy numeric pagination offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "0" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The index series, most recent first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtlasGprResponse" } } } }, "400": { "description": "Invalid enum or date. `details.accepted_values` lists what is accepted." } }, "x-plan-feature": "can_use_intelligence" } }, "/api/v2/intelligence/posture": { "get": { "operationId": "get-atlas-posture", "summary": "Atlas Posture — a place’s structural + dynamic risk posture", "description": "A composite posture score over a trailing window, blending a DYNAMIC axis (measured from coded events) with a STRUCTURAL axis (annual World Bank WDI/WGI and V-Dem indicators).\n\n**Read `trend` carefully.** Its `delta_vs_prior_window` measures the DYNAMIC axis, while `score` is the blended headline — and the structural axis is annual, so it is frozen within any window Posture serves. `basis` states this and `headline_delta_equivalent` gives what the headline actually moved. Both windows are measured on the requested weighting, so the trend differences two periods rather than two estimators.", "tags": [ "Atlas Intelligence" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Internal = events whose whole actor set is one country; external = events spanning two or more. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_posture_scope", "schema": { "type": "string", "enum": [ "all", "internal", "external" ], "default": "all" } }, { "name": "weighting", "in": "query", "required": false, "description": "Roll-up weighting for aggregate geographies. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_weighting", "schema": { "type": "string", "enum": [ "attention", "gdp" ], "default": "attention" } }, { "name": "level", "in": "query", "required": false, "description": "Geographic resolution. `world` needs no `geo`; every other level requires one. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_level", "schema": { "type": "string", "enum": [ "world", "continent", "region", "country" ], "default": "world" } }, { "name": "geo", "in": "query", "required": false, "description": "The place, when level is continent/region/country: an ISO-3166 alpha-3 code, or a region / continent name. An unknown value returns 400 INVALID_ENUM listing what that level accepts.", "schema": { "type": "string" }, "example": "UKR" }, { "name": "window", "in": "query", "required": false, "description": "Trailing days of the series to return. Not the measurement window. Full value list: https://docs.gdeltcloud.com/reference/enums#atlas_posture_window", "schema": { "type": "integer", "minimum": 1, "maximum": 370, "default": 7, "enum": [ "7d", "30d", "90d" ] } }, { "name": "date_start", "in": "query", "required": false, "description": "Explicit series start (overrides `window`).", "schema": { "type": "string", "format": "date" } }, { "name": "date_end", "in": "query", "required": false, "description": "Explicit series end.", "schema": { "type": "string", "format": "date" } }, { "name": "date", "in": "query", "required": false, "description": "A single observation date instead of a range.", "schema": { "type": "string", "format": "date" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time read: reproduce the index as it was KNOWN on this date, with no look-ahead.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 370, "default": 100 } } ], "responses": { "200": { "description": "Posture score, pillars, and trend." }, "400": { "description": "Invalid enum or date." } } } }, "/api/v2/intelligence/coverage": { "get": { "operationId": "get-atlas-coverage", "summary": "Atlas coverage — where the index can and cannot be read", "description": "The honest coverage atlas: which series exist, how much evidence stands behind each, and where they fall below the floor. Read this BEFORE treating a `null` reading as calm — below the floor means unknown, not quiet.\n\n**`level` is not a parameter of this endpoint.** The Coverage Atlas is COUNTRY-grain by construction: it answers \"which countries are dense enough to serve a country-level Pulse/Posture reading\", and its query is pinned to `level = 'country'`. There is no world/continent/region variant to select — the spec advertised `level=world|continent|region|country` and the service never parsed it, so every value returned the identical country-grain payload with a 200. For a different grain use `/api/v2/intelligence/gpr`, which does take `level`.", "tags": [ "Atlas Intelligence" ], "parameters": [ { "name": "geo", "in": "query", "required": false, "description": "The place, when level is continent/region/country: an ISO-3166 alpha-3 code, or a region / continent name. An unknown value returns 400 INVALID_ENUM listing what that level accepts.", "schema": { "type": "string" }, "example": "UKR" }, { "name": "window", "in": "query", "required": false, "description": "Trailing days of the series to return. Not the measurement window.", "schema": { "type": "integer", "minimum": 1, "maximum": 370, "default": 7 } }, { "name": "date_start", "in": "query", "required": false, "description": "Explicit series start (overrides `window`).", "schema": { "type": "string", "format": "date" } }, { "name": "date_end", "in": "query", "required": false, "description": "Explicit series end.", "schema": { "type": "string", "format": "date" } }, { "name": "date", "in": "query", "required": false, "description": "A single observation date instead of a range.", "schema": { "type": "string", "format": "date" } }, { "name": "as_of", "in": "query", "required": false, "description": "Point-in-time read: reproduce the index as it was KNOWN on this date, with no look-ahead.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 370, "default": 100 } } ], "responses": { "200": { "description": "Per-series coverage and floor status." } } } }, "/api/v2/briefs": { "post": { "operationId": "create-brief-v2", "summary": "Create Brief", "description": "Create and kick off a Monitoring Brief. Returns **202 immediately** — a Brief takes ~5–10 minutes; poll `GET /api/v2/briefs/{id}` for status and content. Requires a plan with Briefs access; metered separately from query units.", "tags": [ "Briefs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope_text" ], "properties": { "scope_text": { "type": "string", "minLength": 8, "maxLength": 2400, "description": "One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs.", "example": "Monitor Red Sea maritime disruption risk to shipping across Yemen, the Red Sea, and the Gulf of Aden." }, "time_window": { "type": "string", "enum": [ "6h", "24h", "72h", "7d", "30d" ], "default": "24h", "description": "Recent window the Brief analyses. How far back the brief looks for evidence. Full value list: https://docs.gdeltcloud.com/reference/enums#brief_time_window" }, "baseline_window": { "type": "string", "enum": [ "7d", "14d", "30d" ], "description": "Earlier comparison window for change detection. The comparison period a reading is called normal or abnormal against. It is separate from `time_window` on purpose: a 24h brief still needs weeks of history to know what 24 hours of this looks like. Full value list: https://docs.gdeltcloud.com/reference/enums#brief_baseline_window" }, "audience": { "type": "string", "enum": [ "executive", "analyst", "operator" ], "default": "executive", "description": "Who the brief is written for. It changes the register and what is foregrounded, never the evidence. Full value list: https://docs.gdeltcloud.com/reference/enums#brief_audience" }, "depth": { "type": "string", "enum": [ "skim", "standard", "detailed" ], "default": "standard", "description": "How much the brief does. Not a quality setting — a `skim` is complete and cited, just narrower. Distinct from the numeric `depth` on the entity-hierarchy endpoint, which counts ownership levels. Full value list: https://docs.gdeltcloud.com/reference/enums#brief_depth" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO-3 country codes to scope the Brief.", "example": [ "YEM", "SAU" ] }, "regions": { "type": "array", "items": { "type": "string" } }, "sectors": { "type": "array", "items": { "type": "string" } }, "search_topics": { "type": "array", "items": { "type": "string" }, "description": "Free-text focus terms/phrases that bias retrieval.", "example": [ "port congestion", "tanker insurance" ] }, "actors": { "type": "array", "items": { "type": "string" }, "description": "Named actors to emphasize.", "example": [ "Houthi", "Maersk" ] }, "entities": { "type": "array", "items": { "type": "string" }, "description": "Named people or organizations to emphasize." }, "locations": { "type": "array", "items": { "type": "string" }, "description": "Plain-English sub-country locations." }, "assets": { "type": "array", "items": { "type": "string" }, "description": "Named facilities or infrastructure." }, "public_link": { "type": "boolean", "default": false, "description": "When true, also mint a public shareable report URL." }, "title": { "type": "string", "description": "Optional; auto-generated from scope_text when omitted." }, "brief_type": { "type": "string", "default": "monitoring_brief", "description": "Optional; defaults to monitoring_brief, the only generally-available type.", "enum": [ "monitoring_brief" ] } } } } } }, "responses": { "202": { "description": "Brief generation started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "queued" }, "brief_type": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "string" }, "web_url": { "type": "string" }, "public_url": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, "examples": { "accepted": { "value": { "id": "brief_123", "status": "queued", "brief_type": "monitoring_brief", "title": "Red Sea maritime disruption watch", "created_at": "2026-06-08T14:00:00Z", "web_url": "https://gdeltcloud.com/briefs/brief_123", "public_url": null, "message": "Brief generation started." } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Briefs are not available on your plan (`BRIEF_ACCESS_DENIED`), or the included Brief allotment is exhausted (`BRIEF_LIMIT_REACHED`)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://gdeltcloud.com/api/v2/briefs\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"scope_text\":\"Monitor Red Sea maritime disruption risk across Yemen and the Gulf of Aden.\",\"time_window\":\"7d\",\"baseline_window\":\"30d\",\"audience\":\"executive\",\"countries\":[\"YEM\",\"SAU\"]}'" } ] }, "get": { "operationId": "list-briefs-v2", "summary": "List Briefs", "description": "List the caller's Monitoring Briefs with status and report URLs. Still-running Briefs are reconciled first. Requires a plan with Briefs access.", "tags": [ "Briefs" ], "responses": { "200": { "description": "The caller's Briefs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "briefs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brief_type": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "error_message": { "type": "string", "nullable": true }, "public_url": { "type": "string", "nullable": true }, "web_url": { "type": "string" } } } } } }, "examples": { "briefs": { "value": { "briefs": [ { "id": "brief_123", "title": "Red Sea maritime disruption watch", "brief_type": "monitoring_brief", "status": "ready", "created_at": "2026-06-08T14:00:00Z", "updated_at": "2026-06-08T14:08:00Z", "error_message": null, "public_url": null, "web_url": "https://gdeltcloud.com/briefs/brief_123" } ] } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Briefs are not available on your plan (`BRIEF_ACCESS_DENIED`), or the included Brief allotment is exhausted (`BRIEF_LIMIT_REACHED`)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/briefs\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/briefs/{id}": { "get": { "operationId": "get-brief-v2", "summary": "Fetch Brief", "description": "Fetch one Monitoring Brief: status, the original input, the structured `document` (Monitoring Brief content), `citations`, the evidence `appendix`, and report URLs. A still-running Brief is reconciled first. Requires a plan with Briefs access.", "tags": [ "Briefs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Brief id from create or list." } ], "responses": { "200": { "description": "The Brief.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "brief_type": { "type": "string" }, "status": { "type": "string", "description": "queued → generating → building → ready, or failed." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "error_message": { "type": "string", "nullable": true }, "input": { "type": "object", "nullable": true }, "document": { "type": "object", "description": "Structured Monitoring Brief content.", "nullable": true }, "citations": { "type": "array", "items": { "type": "object" } }, "appendix": { "type": "object", "description": "Evidence chain / tool-call ledger.", "nullable": true }, "public_url": { "type": "string", "nullable": true }, "web_url": { "type": "string" } } }, "examples": { "ready": { "value": { "id": "brief_123", "status": "ready", "title": "Red Sea maritime disruption watch", "brief_type": "monitoring_brief", "created_at": "2026-06-08T14:00:00Z", "updated_at": "2026-06-08T14:08:00Z", "error_message": null, "input": { "time_window": "7d", "audience": "executive" }, "document": { "bottom_line": "Disruption risk remains elevated." }, "citations": [], "appendix": [], "public_url": null, "web_url": "https://gdeltcloud.com/briefs/brief_123" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Briefs are not available on your plan (`BRIEF_ACCESS_DENIED`), or the included Brief allotment is exhausted (`BRIEF_LIMIT_REACHED`)." }, "404": { "description": "Brief not found (or not owned by the caller)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://gdeltcloud.com/api/v2/briefs/$BRIEF_ID\" \\\n -H \"Authorization: Bearer $GDELT_API_KEY\"" } ] } }, "/api/v2/meta/enums": { "get": { "operationId": "get-meta-enums-v2", "summary": "Value vocabularies, machine-readable", "description": "Every vocabulary the API validates against, with the value-space of each — `closed` (the complete authoritative set, safe to switch on), `observed` (a dated measurement of what the corpus currently holds, never an allowlist) and `identifier` (a key with a format and a resolver, never enumerated). Carries a `sha256` you can pin and diff in CI to detect a vocabulary change before it reaches your code. Requires a key so use stays attributable, and is NOT metered — checking a value before spending a query unit should not cost a query unit.", "tags": [ "Meta" ], "parameters": [], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } }, "examples": { "default": { "summary": "Example response", "value": { "success": true, "data": [] } } } } } }, "400": { "description": "Invalid or unsupported parameter (see `code` and `details`)" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Plan does not include this surface" }, "404": { "description": "Not found" }, "429": { "description": "Quota or rate limit exceeded" }, "500": { "description": "Server error" } } } }, "/api/v2/meta/endpoints": { "get": { "operationId": "get-meta-endpoints-v2", "summary": "Endpoint contracts, machine-readable", "description": "The contract-governed endpoints and every parameter each one accepts — names, aliases, bounds, defaults, the vocabulary a value is validated against, and the params deliberately rejected with what to use instead. Served from the same descriptors the API imports at request time, so it cannot describe behaviour the server does not have. Not metered.", "tags": [ "Meta" ], "parameters": [ { "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return one endpoint instead of all of them. Accepts either the descriptor id (`events-list`) or the path (`/api/v2/events`). An unknown value returns `404 NOT_FOUND` with the available ids in `details.available`. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.", "example": "/api/v2/events" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } }, "examples": { "default": { "summary": "Example response", "value": { "success": true, "data": [] } } } } } }, "400": { "description": "Invalid or unsupported parameter (see `code` and `details`)" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Plan does not include this surface" }, "404": { "description": "Not found" }, "429": { "description": "Quota or rate limit exceeded" }, "500": { "description": "Server error" } } } }, "/api/v2/meta/query-units": { "get": { "operationId": "get-meta-query-units-v2", "summary": "What a call costs, and what your plan allows", "description": "The query-unit cost model and this key's current allowance and consumption — so a client can decide whether to make a call before making it, rather than discovering the limit as a 429. Not metered.", "tags": [ "Meta" ], "parameters": [], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } }, "examples": { "default": { "summary": "Example response", "value": { "success": true, "data": [] } } } } } }, "400": { "description": "Invalid or unsupported parameter (see `code` and `details`)" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Plan does not include this surface" }, "404": { "description": "Not found" }, "429": { "description": "Quota or rate limit exceeded" }, "500": { "description": "Server error" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "gdelt_sk_...", "description": "GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`." } }, "parameters": { "dateStart": { "name": "date_start", "in": "query", "description": "Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias `start_date` is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.", "schema": { "type": "string", "format": "date", "example": "2026-04-11" }, "example": "2026-04-11" }, "dateEnd": { "name": "date_end", "in": "query", "description": "Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias `end_date` is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.", "schema": { "type": "string", "format": "date", "example": "2026-04-17" }, "example": "2026-04-17" }, "eventFamily": { "name": "event_family", "in": "query", "deprecated": true, "description": "Deprecated legacy filter. Prefer `category`, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.", "schema": { "$ref": "#/components/schemas/EventFamily" } }, "category": { "name": "category", "in": "query", "description": "Stable linked Event product category. Use a Conflict event type such as `Battles`, `Protests`, or `Explosions/Remote violence`, or one CAMEO+ domain such as `POLITICAL`, `INFRASTRUCTURE`, or `CRIME`; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use `story_category` only for legacy Story-cluster categories such as `conflict_security`. Full list: [Taxonomy & Codes](/api-reference/taxonomy).", "schema": { "type": "string", "example": "Battles" }, "example": "Battles" }, "subcategory": { "name": "subcategory", "in": "query", "description": "More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent `category` and must belong to at least one selected category. For Conflict categories, use sub-event types such as `Armed clash`, `Peaceful protest`, or `Air/drone strike`. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: [Taxonomy & Codes](/api-reference/taxonomy).", "schema": { "type": "string", "example": "Armed clash" }, "example": "Armed clash" }, "domain": { "name": "domain", "in": "query", "description": "Deprecated legacy CAMEO+ domain enum. Prefer `category`/`categories` for new integrations; retained for backwards compatibility. Full list: [Taxonomy & Codes](/api-reference/taxonomy).", "schema": { "$ref": "#/components/schemas/Domain" }, "deprecated": true }, "hasFatalities": { "name": "has_fatalities", "in": "query", "description": "Set `true` for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.", "schema": { "type": "boolean", "example": true }, "example": true }, "sort": { "name": "sort", "in": "query", "description": "`significance` is the default analyst ranking. Use `recent` when freshness matters more than importance.", "schema": { "$ref": "#/components/schemas/Sort", "example": "significance" }, "example": "significance" }, "limit": { "name": "limit", "in": "query", "description": "Number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25 }, "example": 25 }, "cursor": { "name": "cursor", "in": "query", "description": "Pagination cursor from `pagination.next_cursor`.", "schema": { "type": "string" } }, "limitDetail": { "name": "limit", "in": "query", "description": "Number of linked records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "example": 10 }, "example": 10 }, "energyTracker": { "name": "tracker", "in": "query", "required": false, "schema": { "type": "string", "example": "coal_plants,solar", "enum": [ "iron_steel_plants", "cement_plants", "chemical_plants", "iron_ore_mines", "coal_plants", "coal_mines", "coal_terminals", "oil_gas_plants", "oil_gas_extraction", "lng_terminals", "nuclear", "geothermal", "bioenergy", "hydropower", "solar", "wind", "gas_pipelines", "oil_pipelines", "lng_carriers" ] }, "description": "Comma-separated GEM trackers. Valid values: coal_plants, coal_mines, coal_terminals, oil_gas_plants, oil_gas_extraction, lng_terminals, nuclear, geothermal, bioenergy, hydropower, solar, wind, gas_pipelines, oil_pipelines, lng_carriers. Omit for all trackers. All trackers: [Taxonomy & Codes — Energy](/api-reference/taxonomy#energy-vocabularies). Full value list: https://docs.gdeltcloud.com/reference/enums#gem_heavy_industry_tracker The enum above is the UNION across every endpoint that shares this parameter: `iron_steel_plants`, `cement_plants`, `chemical_plants`, `iron_ore_mines` — ACCEPTED ONLY ON `/api/v2/energy/assets`, `/api/v2/energy/assets/summary`. Elsewhere they return 400.", "example": "coal_plants,solar" }, "energyCountry": { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "example": "United States" }, "description": "Country filter, resolved through the shared `resolveCountryInput` layer: a country name (`United States`), ISO-2 (`US`), ISO-3 (`USA`), or legacy alias all work. Filters primary or secondary country for cross-border assets; combinable with `region`/`continent` and an unresolvable value returns `400 INVALID_COUNTRY`. Full value list: https://docs.gdeltcloud.com/reference/enums#country", "example": "United States" }, "energyRegion": { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "example": "Middle East", "enum": [ "Africa", "Asia", "Middle East", "Northern Africa", "Western Africa", "Eastern Africa", "Middle Africa", "Southern Africa", "Europe", "Eastern Europe", "South Asia", "Southeast Asia", "East Asia", "Central Asia", "North America", "Central America", "Caribbean", "South America", "Oceania" ] }, "description": "Plain English region. Expands to the same ISO-3 country list used by V2 Events.", "example": "Middle East" }, "energyContinent": { "name": "continent", "in": "query", "required": false, "schema": { "type": "string", "example": "Asia", "enum": [ "Africa", "Asia", "Europe", "North America", "South America", "Oceania" ] }, "description": "Plain English continent. Expands to the same ISO-3 country list used by V2 Events.", "example": "Asia" }, "energyStatus": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "example": "operating,construction", "enum": [ "operating", "construction", "proposed", "permitted", "cancelled", "mothballed", "retired", "active", "underground gas storage", "on order", "mixed status", "announced", "pre-construction", "pre-permit", "in-development", "discovered", "exploration", "shelved", "cancelled - inferred 4 y", "shelved - inferred 2 y", "abandoned", "idle", "idled", "decommissioning" ] }, "description": "Comma-separated GEM status values. Common values include operating, construction, pre-construction, permitted, announced, proposed, shelved, cancelled, retired, and mothballed. See [Taxonomy & Codes — Energy](/api-reference/taxonomy#energy-vocabularies). Full value list: https://docs.gdeltcloud.com/reference/enums#energy_status", "example": "operating" }, "energyOperatingOnly": { "name": "operating_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Shorthand for status=operating.", "example": true }, "energyTier": { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "example": "main,utility" }, "description": "Comma-separated within-tracker tier values such as main, utility, distributed, below_threshold, closed, or sub_threshold. Observed vocabulary, measured 2026-08-10 (5 distinct values). Values outside it are accepted, not rejected. Discover current values: `GET /api/v2/energy/assets/summary?group_by=tier`. GEM's own coverage tier for an asset row (main sheet vs below-threshold vs closed, and the utility/distributed split on solar). The serve layer accepts it as a free comma list and does not validate it, so an unknown tier returns an empty 200 rather than a 400 — which is why it is published as a measurement rather than as an allowlist. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#energy_tier", "example": "main" }, "energyFuel": { "name": "fuel", "in": "query", "required": false, "schema": { "type": "string", "example": "coal,solar", "enum": [ "gas", "oil", "bioenergy", "coal", "solar", "wind", "nuclear", "hydropower", "geothermal" ] }, "description": "Comma-separated fuel values. Matches the tracker-native fuel string or normalized cross-tracker fuel where populated. See [Taxonomy & Codes — Energy](/api-reference/taxonomy#energy-vocabularies). Full value list: https://docs.gdeltcloud.com/reference/enums#energy_fuel", "example": "coal" }, "energyCapacityMwMin": { "name": "capacity_mw_min", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Minimum MW capacity. Meaningful for power-generation trackers only.", "example": 100 }, "energyCapacityMwMax": { "name": "capacity_mw_max", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Maximum MW capacity. Meaningful for power-generation trackers only.", "example": 5000 }, "energyStartYearMin": { "name": "start_year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1700, "maximum": 2200 }, "description": "Minimum asset start year.", "example": 2000 }, "energyStartYearMax": { "name": "start_year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1700, "maximum": 2200 }, "description": "Maximum asset start year.", "example": 2030 }, "energyRetiredYearMin": { "name": "retired_year_min", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1700, "maximum": 2200 }, "description": "Minimum asset retired year.", "example": 2000 }, "energyRetiredYearMax": { "name": "retired_year_max", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1700, "maximum": 2200 }, "description": "Maximum asset retired year.", "example": 2030 }, "energyEntity": { "name": "entity", "in": "query", "required": false, "schema": { "type": "string", "example": "ArcelorMittal" }, "description": "Canonical owner selector — the same `entity` value works across endpoints. Pass a spine entity id (e_...) for an EXACT match against an asset's owners, operators, or parents, or any name for a case-insensitive fuzzy owner-name match. Preferred over the legacy `owner_search` param.", "example": "ArcelorMittal" }, "energyOwnerSearch": { "name": "owner_search", "in": "query", "required": false, "deprecated": true, "schema": { "type": "string", "example": "ExxonMobil" }, "description": "Legacy — prefer the canonical `entity` param (still fully supported). Case-insensitive substring match against the raw owner string.", "example": "ExxonMobil" }, "energyOwnerEntityId": { "name": "owner_entity_id", "in": "query", "required": false, "schema": { "type": "string", "example": "E100002021305" }, "description": "GEM Entity ID. Returns assets where the entity appears in owners, operators, or parents.", "example": "E100002021305" }, "energyBbox": { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "example": "30,-105,33,-100" }, "description": "Viewport filter formatted as lat_min,lon_min,lat_max,lon_max.", "example": "30,-105,33,-100" }, "energyNear": { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,\\d+(\\.\\d+)?$", "example": "31.16,-102.9,50" }, "description": "Proximity filter formatted as lat,lon,radius_km.", "example": "31.16,-102.9,50" }, "energySearch": { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "example": "Ranch Energy" }, "description": "Case-insensitive substring match against asset name.", "example": "Ranch Energy" }, "energyAssetClass": { "name": "asset_class", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fixed", "mobile", "all" ], "default": "fixed" }, "description": "Asset class. The default fixed excludes mobile LNG carriers; use mobile or all for vessels. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_asset_class", "example": "fixed" }, "energySort": { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "capacity_desc", "capacity_asc", "start_year_desc", "start_year_asc", "recent", "name" ], "default": "capacity_desc" }, "description": "List sort order. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_sort", "example": "capacity_desc" }, "energyLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Number of asset cards to return.", "example": 25 }, "energyCursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "example": "25" }, "description": "Pagination cursor from pagination.next_cursor.", "example": "25" }, "energyGroupBy": { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "country", "region", "continent", "tracker", "status", "start_year_decade", "fuel", "tier" ], "default": "tracker" }, "description": "Summary aggregation dimension. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_group_by", "example": "tracker" }, "energySummaryLimit": { "name": "summary_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Number of summary buckets to return.", "example": 50 }, "energyMapLimit": { "name": "map_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 50, "maximum": 1000, "default": 300 }, "description": "Fine-mode pin limit. Alias of fine_grained_limit.", "example": 300 }, "energyFineGrainedLimit": { "name": "fine_grained_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 50, "maximum": 1000, "default": 300 }, "description": "Fine-mode pin limit. Alias of map_limit.", "example": 300 }, "civilianTargeting": { "name": "civilian_targeting", "in": "query", "description": "Filter Conflict-linked evidence by ACLED civilian_targeting. `true` keeps records where civilians are the primary target; `false` excludes those records.", "schema": { "type": "boolean" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "FacilityOwner": { "type": "object", "description": "An owner / operator of a facility. entity_id is the spine e_ id (null for owner-name-only rows, e.g. maritime ports carry no owner and some GEM owners resolve a name but not a spine id yet).", "properties": { "entity_id": { "type": "string", "nullable": true, "description": "Spine entity_id — join key to /api/v2/entities and the cross-source graph.", "example": "e_a4db9cd53edee666" }, "name": { "type": "string", "nullable": true, "example": "Alibaba" } } }, "FacilityCard": { "type": "object", "properties": { "facility_id": { "type": "string", "description": "Identifier for this row: canonical `s_…` site id in the default site view, or source registry-unit `f_…` id with `granularity=unit`." }, "canonical_site_id": { "type": "string", "description": "Canonical `s_…` physical-site id shared by every registry unit at the site." }, "granularity": { "type": "string", "enum": [ "site", "unit" ] }, "unit_id": { "type": "string", "nullable": true, "description": "Source registry-unit `f_…` id on unit rows; null on canonical site rows." }, "unit_count": { "type": "number", "description": "Distinct source registry units represented by this row." }, "unit_ids": { "type": "array", "items": { "type": "string" }, "description": "Source registry-unit ids represented by this site or unit row." }, "unit_statuses": { "type": "array", "items": { "type": "object", "properties": { "facility_id": { "type": "string", "description": "Source registry-unit `f_…` id." }, "status_source": { "type": "string", "nullable": true, "description": "Status exactly as published by the source registry." }, "status": { "type": "string", "nullable": true, "description": "Normalized lower-case lifecycle status; null when unknown." } }, "required": [ "facility_id", "status_source", "status" ] }, "description": "Per-unit source and normalized status evidence." }, "status_breakdown": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "description": "Normalized lower-case lifecycle status; null means unknown." }, "unit_count": { "type": "number" } }, "required": [ "status", "unit_count" ] }, "description": "Registry-unit counts by normalized lifecycle status." }, "name": { "type": "string" }, "name_local": { "type": "string" }, "facility_type": { "type": "string" }, "facility_class": { "type": "string", "nullable": true }, "source_silo": { "type": "string" }, "gem_tracker": { "type": "string" }, "country_iso3": { "type": "string", "nullable": true }, "secondary_country_iso3": { "type": "string" }, "lat": { "type": "number", "nullable": true }, "lon": { "type": "number", "nullable": true }, "geom_wkt": { "type": "string" }, "address": { "type": "string" }, "unlocode": { "type": "string" }, "status": { "type": "string", "nullable": true, "description": "`mixed` when represented units disagree; otherwise a normalized lower-case lifecycle status. Null means unknown." }, "status_source": { "type": "string", "nullable": true, "description": "Single raw source status when all represented units agree; null otherwise." }, "status_sources": { "type": "array", "items": { "type": "string" }, "description": "Distinct raw status spellings published by the source registry." }, "capacity_mw": { "type": "number", "nullable": true }, "owners": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "nullable": true, "description": "Terminal spine `e_…` id. Null when the source names an owner that has not resolved to the spine." }, "name": { "type": "string", "nullable": true } }, "required": [ "entity_id", "name" ] }, "description": "Atomic owner records; ids and names are never separate positional arrays." }, "attributes": { "description": "Source-specific physical-asset attributes." }, "first_seen_date": { "type": "string" }, "last_seen_date": { "type": "string" }, "detail_url": { "type": "string" }, "owner_portfolio_url": { "type": "string" } }, "required": [ "facility_id", "canonical_site_id", "granularity", "unit_id", "unit_count", "unit_ids", "unit_statuses", "status_breakdown", "name", "facility_type", "facility_class", "source_silo", "country_iso3", "lat", "lon", "status", "status_source", "status_sources", "capacity_mw", "owners", "attributes", "detail_url" ] }, "FacilityPagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true, "description": "Pass back as `cursor` for the next page." } } }, "GovCrossSource": { "type": "object", "description": "Cross-source fusion for the primary resolved entity — its footprint beyond this endpoint (foreign-agent status, SEC filer, facilities owned) + headline flags. Null when there is no cross-source signal.", "properties": { "entity_id": { "type": "string", "description": "Spine `e_…` id — the same handle `/api/v2/events`, `/api/v2/stories` and `/api/v2/exposure` accept, so a government-exposure row joins straight to the news layer.", "example": "e_a4db9cd53edee666" }, "federal_awards": { "type": "object", "nullable": true, "properties": { "awards": { "type": "integer" }, "total_obligated": { "type": "number" } } }, "foreign_agent": { "type": "object", "nullable": true, "description": "This entity AS a US registrant (foreign agent).", "properties": { "registrations": { "type": "integer" }, "foreign_principals": { "type": "integer" }, "sanctioned_principals": { "type": "integer", "description": "Foreign principals it represents that are on a sanctions list." }, "countries": { "type": "array", "items": { "type": "string" } } } }, "foreign_principal_of": { "type": "object", "nullable": true, "description": "This entity AS a foreign principal — the US firms registered to represent it.", "properties": { "us_registrants": { "type": "integer" } } }, "sec_filer": { "type": "boolean" }, "facilities_owned": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "Headline cross-flags: federal_contractor_and_foreign_agent, foreign_agent_for_sanctioned_entity." } } }, "GovAwardsResponse": { "type": "object", "description": "Entity federal-award exposure — USAspending prime awards keyed on SAM.gov UEI, resolved to the entity spine.", "properties": { "query": { "type": "object", "properties": { "entity": { "type": "string", "nullable": true }, "uei": { "type": "string", "nullable": true }, "recipient": { "type": "string", "nullable": true }, "limit": { "type": "integer" } } }, "summary": { "type": "object", "properties": { "recipients": { "type": "integer", "description": "Distinct recipient UEIs across all matching awards." }, "total_awards": { "type": "integer", "description": "Total matching awards (not capped by limit)." }, "total_obligated": { "type": "number", "description": "Sum of obligations across all matching awards, in USD." }, "recipient_rollups": { "type": "array", "items": { "type": "object", "properties": { "recipient_uei": { "type": "string" }, "recipient_name": { "type": "string" }, "entity_id": { "type": "string", "description": "Resolved spine entity id; empty string when the recipient did not resolve to the spine." }, "award_count": { "type": "integer" }, "total_obligated": { "type": "number", "description": "Sum of award obligations for this UEI, in USD." }, "agency_count": { "type": "integer" }, "top_agencies": { "type": "array", "items": { "type": "string" }, "description": "Up to 10 distinct awarding agencies for this UEI." }, "first_action_date": { "type": "string", "format": "date" }, "last_action_date": { "type": "string", "format": "date" } } }, "description": "Per-UEI rollup, top 25 by obligated USD." } } }, "awards": { "type": "array", "items": { "type": "object", "properties": { "award_id": { "type": "string", "description": "USAspending award unique key (the permalink id)." }, "recipient_name": { "type": "string" }, "recipient_uei": { "type": "string" }, "entity_id": { "type": "string", "description": "Resolved spine entity id; empty string when unresolved." }, "award_amount": { "type": "number", "description": "Obligated amount for this award, in USD." }, "awarding_agency": { "type": "string" }, "awarding_sub_agency": { "type": "string" }, "award_group": { "type": "string", "description": "contract | grant | loan | direct_payment | other." }, "award_type": { "type": "string" }, "action_date": { "type": "string", "format": "date", "description": "Latest action date for the award." }, "end_date": { "type": "string", "description": "Period-of-performance end date; empty string when unknown." }, "source_url": { "type": "string", "description": "USAspending permalink for the award." } } }, "description": "Recent award timeline (up to limit), newest first." }, "meta": { "type": "object", "properties": { "source": { "type": "string" }, "attributions": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "source_url": { "type": "string" }, "license": { "type": "string" }, "note": { "type": "string" } } } }, "note": { "type": "string", "nullable": true, "description": "Present only when the result set is empty." } } }, "cross_source": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/GovCrossSource" } ] } } }, "GovFaraResponse": { "type": "object", "description": "US foreign-influence links (FARA) — US registrants ↔ foreign principals, resolved to the entity spine and crossed with our screening lists.", "properties": { "query": { "type": "object", "properties": { "entity": { "type": "string", "nullable": true }, "registrant": { "type": "string", "nullable": true }, "foreign_principal": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "adversary_only": { "type": "boolean" }, "sanctioned_only": { "type": "boolean" }, "active_only": { "type": "boolean" }, "limit": { "type": "integer" } } }, "summary": { "type": "object", "properties": { "links": { "type": "integer" }, "registrants": { "type": "integer" }, "foreign_principals": { "type": "integer" }, "countries": { "type": "integer" }, "adversary_links": { "type": "integer" }, "sanctioned_links": { "type": "integer" }, "active_links": { "type": "integer" } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "registration_number": { "type": "string" }, "registrant_name": { "type": "string" }, "registrant_entity_id": { "type": "string", "description": "Resolved spine id of the US registrant; empty when unresolved." }, "foreign_principal": { "type": "string" }, "foreign_principal_entity_id": { "type": "string", "description": "Resolved spine id of the foreign principal; empty when unresolved." }, "country": { "type": "string" }, "country_adversary": { "type": "integer", "description": "1 if the country is in the adversary set." }, "fp_sanctioned": { "type": "integer", "description": "1 if the foreign principal is on a sanctions/restricted list." }, "fp_sanction_lists": { "type": "array", "items": { "type": "string" }, "description": "Screening list source_keys matched (csl_ofac_sdn / csl_bis_entity / dod_1260h / …)." }, "fp_sanction_programs": { "type": "array", "items": { "type": "string" }, "description": "Sanction programs (RUSSIA-EO14024 / CMIC-EO13959 / 1260H / …)." }, "fp_registration_date": { "type": "string", "description": "Foreign-principal registration date; empty when unknown." }, "fp_termination_date": { "type": "string", "description": "Termination date; empty when still active." }, "is_active": { "type": "integer", "description": "1 if the registration is still active." }, "source_url": { "type": "string", "description": "FARA registrant permalink." } } } }, "meta": { "type": "object", "properties": { "source": { "type": "string" }, "attributions": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "source_url": { "type": "string" }, "license": { "type": "string" }, "note": { "type": "string" } } } }, "note": { "type": "string", "nullable": true } } }, "cross_source": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/GovCrossSource" } ] } } }, "FacilitiesListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityCard" } }, "pagination": { "$ref": "#/components/schemas/FacilityPagination" }, "applied_filters": { "type": "object", "description": "Echo of the resolved filters." } } }, "FacilityDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "facility": { "$ref": "#/components/schemas/FacilityCard" }, "merge_history": { "type": "array", "description": "Reversible cross-silo merge rows (empty at launch)." } } }, "EventFamily": { "type": "string", "enum": [ "conflict", "cameoplus" ] }, "Domain": { "type": "string", "enum": [ "POLITICAL", "ECONOMIC", "CORPORATE", "TECHNOLOGY", "INFRASTRUCTURE", "HEALTH", "DEMOGRAPHIC", "INFORMATION", "ENVIRONMENT", "CRIME" ] }, "Sort": { "type": "string", "enum": [ "significance", "recent" ], "default": "significance" }, "GroupBy": { "type": "string", "enum": [ "date", "country", "region", "continent", "category", "subcategory" ] }, "Geo": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "continent": { "type": "string", "nullable": true }, "admin1": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } }, "GeoContext": { "type": "object", "description": "Explains broad geography matches. geo is the event/story location; actor_origin_countries explains matches where the requested country, region, or continent came from actor origin instead.", "properties": { "location_country": { "type": "string", "nullable": true }, "actor_origin_countries": { "type": "array", "items": { "type": "string" } } } }, "Article": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "domain_avatar_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort source-domain avatar/favicon URL for UI rendering." }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort sharing image for the source article, where the publisher provided one. Absent rather than null when none was found." }, "article_date": { "type": "string", "format": "date", "nullable": true }, "rank": { "type": "integer", "nullable": true }, "role": { "type": "string", "nullable": true } } }, "EntityRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the entity. Prefers the SPINE id (`e_…`) — the registry-of-record key that unifies an entity across news, filings, GLEIF, GEM and the screening lists. Falls back to the previous identifier (a Wikipedia URL, or an `llm:` id) where no spine bridge exists yet, so an entity always has an id. Use `id_space` to tell which you received; values upgrade to `spine` on their own as coverage grows." }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "wikipedia_url": { "type": "string", "format": "uri", "nullable": true }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort Wikipedia thumbnail URL for UI rendering." }, "avatar_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort compact avatar URL, usually the same as image_url." }, "id_space": { "type": "string", "enum": [ "spine", "wikipedia", "llm" ], "description": "Which id-space `id` came from. `spine` means it is the unified `e_` id and can be joined to /api/v2/entities, /exposure, /filings, /gov/awards and the screening lists. Branch on this rather than sniffing the id's prefix." }, "entity_id": { "type": "string", "nullable": true, "description": "The spine `e_` id when this entity bridges to the registry, otherwise null. Equal to `id` when `id_space` is `spine`. Null is honest about where the bridge has not reached — it never means the entity does not exist." } } }, "EventCard": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "nullable": true }, "primary_story_url": { "type": "string", "nullable": true }, "family": { "type": "string", "enum": [ "conflict", "cameoplus" ] }, "title": { "type": "string", "nullable": true }, "title_source": { "type": "string", "enum": [ "coder_title", "cluster_label", "event_description", "actor_pair", "actor", "sub_event_type", "event_type_in_location", "event_type", "domain_in_location", "domain", "fallback" ] }, "summary": { "type": "string", "nullable": true }, "event_date": { "type": "string" }, "observed_at": { "type": "string", "nullable": true }, "event_date_basis": { "type": "string", "enum": [ "explicit_date", "relative_date", "publication_day_inference", "ongoing_event_update" ], "nullable": true }, "event_date_evidence": { "type": "string", "nullable": true }, "coded_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true }, "processed_at": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true, "description": "Taxonomy subcategory IDENTIFIER — a CAMEO+ code (e.g. \"EC04\", \"042\") or, for the conflict family, the ACLED sub-event type (e.g. \"Peaceful protest\"). This is exactly what the `subcategory` filter accepts. For the human-readable name, read `subcategory_label`." }, "subcategory_label": { "type": "string", "nullable": true, "description": "Human-readable name for `subcategory` (e.g. \"Trade Policy Action\"). NULL when the code is not one the taxonomy declares — see `taxonomy_status`. Not a filter value; filter on `subcategory`." }, "taxonomy_status": { "type": "string", "enum": [ "coded", "detail_missing", "undeclared_code" ] }, "domain": { "type": "string", "nullable": true }, "event_code": { "type": "string", "nullable": true }, "geo": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "continent": { "type": "string", "nullable": true }, "admin1": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "geo_precision": { "type": "number", "nullable": true }, "geo_precision_label": { "type": "string", "nullable": true } }, "required": [ "country", "region", "continent", "admin1", "location", "latitude", "longitude", "geo_precision", "geo_precision_label" ] }, "geo_context": { "type": "object", "properties": { "location_country": { "type": "string", "nullable": true }, "actor_origin_countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "location_country", "actor_origin_countries" ] }, "actors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "country": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "source", "target", "actor1", "actor2" ], "description": "The part this actor played. CAMEO+ events are directed: `source` acted, `target` was acted upon. Conflict (ACLED) events are undirected and use `actor1`/`actor2`, which imply no initiator. The two pairs never mix on one card — `family` determines which you get." }, "primary": { "type": "boolean", "description": "True for the coder's PRIMARY actor in this role — the one entity the event is chiefly about on that side, and the one carried in the `source_actor` / `target_actor` columns and filters. False for a co-actor: another entity in the same role in the same action. `actors[]` is ordered primaries-first, and there is at most one `primary: true` per role." } }, "required": [ "name", "country", "role", "primary" ] } }, "metrics": { "type": "object", "properties": { "significance": { "type": "number" }, "severity_tier": { "type": "string" }, "goldstein_scale": { "type": "number", "nullable": true, "description": "Goldstein conflict-cooperation scale, -10 to +10. NULL is DETERMINISTIC, not sparse coverage: it is populated for CAMEO+ POLITICAL events and for every conflict (ACLED) event, and is NULL for the other nine CAMEO+ domains because Goldstein is not defined there. Measured on one production day that is 100% / 100% / 0%, i.e. ~42% of all events — complete wherever the scale means anything." }, "magnitude": { "type": "number", "nullable": true }, "systemic_importance": { "type": "number", "nullable": true }, "propagation_potential": { "type": "number", "nullable": true }, "market_sensitivity": { "type": "number", "nullable": true }, "confidence": { "type": "number", "nullable": true }, "article_count": { "type": "number", "nullable": true, "description": "Canonical Story article count. NULL when the Event has no canonical Story measurement; never fabricated from source URL count." }, "evidence_source_count": { "type": "number", "description": "Distinct source URLs attached directly to the Event evidence." }, "supporting_story_count": { "type": "number", "description": "Number of canonical Story references attached to the Event." }, "metric_inputs": { "description": "The EVIDENCE BEHIND THE SCORES — for each metric, the sub-factor values the coder read off the article and the reason it gave for each, keyed by metric. This is what makes a metric auditable rather than something to trust: the published formula turns these inputs into the served value, so you can recompute it yourself. Shape is `{: {: value, why: \"…\"}}`. Present on most CAMEO+ events; OMITTED where no sub-factor evidence was recorded, which is not the same as none existing — events coded before the field was stored carry nothing, and a backfill has not run. Sub-factor definitions and the formulas: https://docs.gdeltcloud.com/reference/metrics" }, "metric_version": { "type": "string" } }, "required": [ "significance", "severity_tier", "goldstein_scale", "magnitude", "systemic_importance", "propagation_potential", "market_sensitivity", "confidence", "article_count", "evidence_source_count", "supporting_story_count" ] }, "has_fatalities": { "type": "boolean", "nullable": true }, "fatalities": { "type": "number", "nullable": true }, "fatalities_basis": { "type": "string", "enum": [ "reported_exact", "reported_minimum", "reported_range", "estimated", "none_reported" ], "nullable": true }, "fatalities_corroboration": { "type": "string", "enum": [ "multi_source_independent", "single_source", "party_to_conflict_claim", "contested", "none_reported" ], "nullable": true }, "fatalities_evidence": { "type": "string", "nullable": true }, "fatalities_supporting_source_count": { "type": "number", "nullable": true }, "injured": { "type": "number", "nullable": true }, "civilians_killed": { "type": "number", "nullable": true }, "civilians_injured": { "type": "number", "nullable": true }, "civilian_targeting": { "type": "boolean", "nullable": true }, "civilian_targeting_label": { "type": "string", "nullable": true }, "story_refs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "story_date": { "type": "string", "nullable": true }, "article_count": { "type": "number" } }, "required": [ "id", "url", "title", "story_date", "article_count" ] } }, "entity_refs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "top_articles": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "domain_avatar_url": { "type": "string", "nullable": true }, "rank": { "type": "number" } }, "required": [ "url", "title", "domain", "domain_avatar_url", "rank" ] } }, "language_breakdown": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "count": { "type": "number" } }, "required": [ "language", "count" ] } }, "top_language": { "type": "string", "nullable": true }, "story_date": { "type": "string" }, "search_score": { "type": "number", "nullable": true, "description": "Semantic relevance for a `search=` request. NULL when the request had no `search=`, and NULL on a `match_type: \"name\"` hit — a literal match has no computed distance. Higher is closer; set your own floor rather than assuming one." }, "match_type": { "type": "string", "enum": [ "semantic", "name" ], "description": "How this row was retrieved by `search=`: `semantic` (embedding similarity, carries a `search_score`) or `name` (literal match, `search_score` is null). Absent entirely on non-search requests." }, "entity_link": { "type": "object", "properties": { "entity": { "type": "string", "description": "The entity handle AS RESOLVED — the canonical id the scope actually used, which is not necessarily the string you sent (`entities=` takes the first member; ids are decoded and collapsed through the arbiter). Echoed so a caller passing several handles can tell which one answered." }, "mode": { "type": "string", "enum": [ "material", "actor", "coverage" ], "description": "The requested entity-match policy. `material` is the default; `coverage` is the explicit broad-co-occurrence mode." }, "via": { "type": "string", "enum": [ "attribution", "actor", "story" ], "description": "HOW the row was reached: independently adjudicated material attribution, deterministic coded actor evidence, or broad story co-occurrence." }, "role": { "type": "string", "nullable": true }, "decision": { "type": "string", "enum": [ "accepted", "deterministic", "coverage" ] }, "materiality_confidence": { "type": "number", "nullable": true }, "resolution_confidence": { "type": "number", "nullable": true }, "resolution_method": { "type": "string", "nullable": true }, "evidence": { "nullable": true }, "story_id": { "type": "string", "description": "The story that carried the entity — retrieve it at `/api/v2/stories/{story_id}` to read the evidence yourself. This is the most recent story linking the entity to this event. In ~0.2% of cases (measured over 3 production days: 17 of 8,295) the story has since been merged away, and that endpoint answers `STORY_MERGED` carrying the surviving id." }, "story_date": { "type": "string", "description": "The story's cluster date, `YYYY-MM-DD`. Pass it as `date=` alongside `story_id` — the story endpoints are date-partitioned and resolving the date costs an extra lookup without it." } }, "required": [ "entity", "mode", "via", "role", "decision", "materiality_confidence", "resolution_confidence", "resolution_method", "evidence", "story_date" ] }, "incident": { "type": "object", "properties": { "uid": { "type": "string", "description": "The incident key. Group or `uniqExact` on this instead of `event_uid` to count INCIDENTS rather than coded stories. Equal to `event_uid` unless a judge confirmed this event duplicates another, in which case it is the surviving event of the group. ALWAYS read `resolution` before trusting it: on an `unadjudicated` row this value is a fallback, not a verdict." }, "resolution": { "type": "string", "enum": [ "unadjudicated", "self", "llm" ], "description": "How `uid` was decided. `unadjudicated` — this event was never compared to anything, and `uid` defaults to `event_uid`. `self` — compared and found unique. `llm` — an independent adversarial judge confirmed a duplicate and `uid` names the survivor. Coverage is deliberately partial and visible: only events that were candidates for a duplicate are ever adjudicated." }, "confidence": { "type": "number", "nullable": true, "description": "The judge's confidence in the merge, 0–1, and NULL unless `resolution` is `llm`. For a group of three or more this is the WEAKEST link that holds the group together, not the average — a group joined transitively is only as good as its worst edge." } }, "required": [ "uid", "resolution", "confidence" ] } }, "required": [ "id", "url", "primary_story_url", "family", "title", "title_source", "summary", "event_date", "observed_at", "event_date_basis", "event_date_evidence", "coded_at", "updated_at", "processed_at", "category", "subcategory", "subcategory_label", "taxonomy_status", "domain", "event_code", "geo", "geo_context", "actors", "metrics", "has_fatalities", "fatalities", "fatalities_basis", "fatalities_corroboration", "fatalities_evidence", "fatalities_supporting_source_count", "injured", "civilians_killed", "civilians_injured", "civilian_targeting", "civilian_targeting_label", "story_refs", "entity_refs", "top_articles", "language_breakdown", "top_language", "search_score", "incident" ] }, "StoryCard": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "story_date": { "type": "string" }, "updated_at": { "type": "string", "nullable": true }, "processed_at": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "category_code": { "type": "string", "nullable": true }, "subcategory": { "type": "string", "nullable": true }, "geo": { "type": "object", "properties": { "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "continent": { "type": "string", "nullable": true }, "admin1": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "geo_precision": { "type": "number", "nullable": true }, "geo_precision_label": { "type": "string", "nullable": true } }, "required": [ "country", "region", "continent", "admin1", "location", "latitude", "longitude", "geo_precision", "geo_precision_label" ] }, "geo_provenance": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "representative_linked_event" ] }, "event_id": { "type": "string" } }, "required": [ "method", "event_id" ], "nullable": true }, "geo_context": { "type": "object", "properties": { "location_country": { "type": "string", "nullable": true }, "actor_origin_countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "location_country", "actor_origin_countries" ] }, "metrics": { "type": "object", "properties": { "significance": { "type": "number" }, "article_count": { "type": "number" }, "linked_event_count": { "type": "number" }, "max_linked_event_significance": { "type": "number" }, "civilian_targeting_event_count": { "type": "number" } }, "required": [ "significance", "article_count", "linked_event_count", "max_linked_event_significance", "civilian_targeting_event_count" ] }, "has_events": { "type": "boolean" }, "has_fatalities": { "type": "boolean", "nullable": true }, "has_civilian_targeting": { "type": "boolean" }, "fatalities": { "type": "number", "nullable": true }, "linked_events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true } }, "required": [ "id", "title" ] } }, "entity_refs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "matched_categories": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label" ] } }, "top_articles": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "rank": { "type": "number" } }, "required": [ "url", "title", "domain", "rank" ] } }, "language_breakdown": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "count": { "type": "number" } }, "required": [ "language", "count" ] } }, "top_language": { "type": "string", "nullable": true }, "entity_link": { "type": "object", "properties": { "entity": { "type": "string", "description": "The entity handle AS RESOLVED — the canonical id the scope actually used, which is not necessarily the string you sent (`entities=` takes the first member; ids are decoded and collapsed through the arbiter). Echoed so a caller passing several handles can tell which one answered." }, "mode": { "type": "string", "enum": [ "material", "actor", "coverage" ], "description": "The requested entity-match policy. `material` is the default; `coverage` is the explicit broad-co-occurrence mode." }, "via": { "type": "string", "enum": [ "attribution", "actor", "story" ], "description": "HOW the row was reached: independently adjudicated material attribution, deterministic coded actor evidence, or broad story co-occurrence." }, "role": { "type": "string", "nullable": true }, "decision": { "type": "string", "enum": [ "accepted", "deterministic", "coverage" ] }, "materiality_confidence": { "type": "number", "nullable": true }, "resolution_confidence": { "type": "number", "nullable": true }, "resolution_method": { "type": "string", "nullable": true }, "evidence": { "nullable": true }, "story_id": { "type": "string", "description": "The story that carried the entity — retrieve it at `/api/v2/stories/{story_id}` to read the evidence yourself. This is the most recent story linking the entity to this event. In ~0.2% of cases (measured over 3 production days: 17 of 8,295) the story has since been merged away, and that endpoint answers `STORY_MERGED` carrying the surviving id." }, "story_date": { "type": "string", "description": "The story's cluster date, `YYYY-MM-DD`. Pass it as `date=` alongside `story_id` — the story endpoints are date-partitioned and resolving the date costs an extra lookup without it." } }, "required": [ "entity", "mode", "via", "role", "decision", "materiality_confidence", "resolution_confidence", "resolution_method", "evidence", "story_date" ] }, "search_score": { "type": "number", "nullable": true, "description": "Semantic relevance for a `search=` request. NULL when the request had no `search=`, and NULL on a `match_type: \"name\"` hit — a literal match has no computed distance. Higher is closer; set your own floor rather than assuming one." }, "match_type": { "type": "string", "enum": [ "semantic", "name" ], "description": "How this row was retrieved by `search=`: `semantic` (embedding similarity, carries a `search_score`) or `name` (literal match, `search_score` is null). Absent entirely on non-search requests." } }, "required": [ "id", "url", "title", "story_date", "updated_at", "processed_at", "category", "category_code", "subcategory", "geo", "geo_provenance", "geo_context", "metrics", "has_events", "has_fatalities", "has_civilian_targeting", "fatalities", "linked_events", "entity_refs", "matched_categories", "top_articles", "language_breakdown", "top_language", "search_score" ] }, "EntityCard": { "type": "object", "description": "One canonical Entity, deduplicated by Wikipedia URL across raw_name variants on the public list surface. Low-quality matches (disambiguation pages, common nouns, extraction artifacts) are filtered server-side. GDELT-derived per-article metrics (mention_count, avg_salience) are not part of the public contract — story_count, article_count, and event_count are the canonical activity signals. Entity detail can include cached Entity Tone metadata when include_tone=true; missing tone is reported as not_available, not neutral.", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri", "nullable": true }, "name": { "type": "string", "description": "Canonical display name — the most-mentioned raw_name variant pointing at this Wikipedia URL." }, "type": { "type": "string", "nullable": true, "enum": [ "person", "organization" ] }, "wikipedia_url": { "type": "string", "format": "uri", "nullable": true }, "latest_date": { "type": "string", "format": "date", "nullable": true, "description": "Most recent date the Entity appeared in a Story or Event within the requested window." }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort Wikipedia thumbnail URL for UI rendering." }, "avatar_url": { "type": "string", "format": "uri", "nullable": true, "description": "Best-effort compact avatar URL, usually the same as image_url." }, "wikipedia": { "type": "object", "nullable": true, "description": "Compact Wikipedia enrichment when available, including thumbnail_url, description, page_url, and summary on detail responses.", "additionalProperties": true }, "metrics": { "type": "object", "description": "Aggregated activity counts over the requested window, summed across all raw_name variants that map to this Wikipedia URL.", "properties": { "article_count": { "type": "integer", "description": "Total articles in matched Stories and Events mentioning the entity." }, "story_count": { "type": "integer", "description": "Distinct GDELT Cloud Stories (cluster_ids) the entity appeared in." }, "event_count": { "type": "integer", "description": "Distinct coded Events (Conflict + CAMEO+) linked to the entity." } } }, "story_refs": { "type": "array", "items": { "type": "object" } }, "event_refs": { "type": "array", "items": { "type": "object" } }, "entity_tone": { "type": "object", "nullable": true, "description": "Present on Entity detail when include_tone=true and the caller is allowed to access preview tone metadata. tone_status may be scored, reviewable, partial, or not_available.", "properties": { "tone_status": { "type": "string", "enum": [ "scored", "reviewable", "partial", "not_available" ] }, "coverage": { "type": "object", "additionalProperties": true }, "latest_series": { "type": "array", "items": { "type": "object" } }, "by_language": { "type": "array", "description": "Per-language tone breakdown over ALL scored Stories in the window. Embedded on Entity detail (include_tone=true); on the tone endpoints it appears when the request passes group_by=language. Each item: language (ISO code), mean_tone, mean_risk, confidence, scored_story_count (scored Stories covered in that language), article_count (TOTAL articles in that language — real coverage volume, not the bounded evidence sample), and a daily series. Lets you compare how an entity is covered across languages (e.g. markedly more negative in one language than another). Mean tone is computed over every scored Story, not a sample.", "items": { "type": "object", "properties": { "language": { "type": "string" }, "mean_tone": { "type": "number", "nullable": true }, "mean_risk": { "type": "number", "nullable": true }, "confidence": { "type": "number", "nullable": true }, "scored_story_count": { "type": "integer" }, "article_count": { "type": "integer" }, "series": { "type": "array", "items": { "type": "object" } } } } }, "analytics_url": { "type": "string", "nullable": true }, "methodology": { "type": "object", "additionalProperties": true } } }, "cooccurrences": { "type": "array", "description": "Co-occurring entities — people/organizations that appear in the same Stories as this entity within the window, ranked by shared-Story count. Returned on Entity detail. Each item: name, type (person|organization), wikipedia_url, story_count (shared Stories), source ('news'), url (entity page).", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "nullable": true, "enum": [ "person", "organization" ] }, "wikipedia_url": { "type": "string", "nullable": true }, "story_count": { "type": "integer" }, "source": { "type": "string" }, "url": { "type": "string", "nullable": true } } } }, "timeline": { "type": "array", "description": "Per-day activity for the entity over the window (Entity detail). Each item: date, article_count, mention_count.", "items": { "type": "object" } }, "source_mix": { "type": "array", "description": "Top news domains covering the entity over the window (Entity detail). Each item: domain, article_count, story_count.", "items": { "type": "object" } }, "map_pins": { "type": "array", "description": "Geo-located Events linked to the entity (Entity detail), for map rendering. Each item: event_uid, event_family, event_date, title, country, category, latitude, longitude.", "items": { "type": "object" } }, "sources": { "type": "object", "nullable": true, "description": "Per-source entitlement control-plane on Entity detail: for each data source (news, events, tone, gem, sec, sanctions, china, epoch_ai, facilities, gov, share_of_voice) whether the caller's plan is entitled, plus availability for entitled sources. Non-entitled sources report a uniform locked state and omit availability (no availability leak). The corresponding section objects (news, events, tone, sec, ...) appear at the top level only for entitled sources.", "additionalProperties": true } } }, "EventSummaryBucket": { "type": "object", "description": "One grouped Event summary bucket. Includes legacy flat fields plus nested metrics/metric_stats with min/avg/max aggregate statistics for the generated inputs used in Event significance scoring. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves.", "properties": { "key": { "type": "string", "nullable": true }, "group_by": { "type": "string" }, "event_count": { "type": "integer" }, "conflict_event_count": { "type": "integer" }, "cameoplus_event_count": { "type": "integer" }, "fatality_event_count": { "type": "integer" }, "fatalities": { "type": "integer" }, "fatality_event_rate": { "type": "number" }, "country_count": { "type": "integer" }, "region_count": { "type": "integer" }, "article_count": { "type": "integer" }, "avg_article_count": { "type": "number" }, "max_article_count": { "type": "integer" }, "avg_significance": { "type": "number" }, "max_significance": { "type": "number" }, "min_significance": { "type": "number" }, "avg_goldstein_scale": { "type": "number", "nullable": true }, "metrics": { "type": "object", "description": "Nested aggregate statistics for significance and its generated input metrics.", "additionalProperties": true, "example": { "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 }, "goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 }, "goldstein_severity": { "avg": 4.2, "min": 0.5, "max": 8 }, "cameoplus": { "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 }, "systemic_importance": { "avg": 0.52, "min": 0.11, "max": 0.9 }, "propagation_potential": { "avg": 0.47, "min": 0.07, "max": 0.81 }, "market_sensitivity": { "avg": 0.31, "min": 0.03, "max": 0.75 } }, "confidence": { "avg": 0.83, "min": 0.44, "max": 0.98 }, "article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 }, "fatalities": { "events": 2, "rate": 0.1667, "total": 6 } } }, "metric_stats": { "type": "object", "description": "Alias of metrics for clients that prefer an explicit statistical field name.", "additionalProperties": true }, "min_article_count": { "type": "integer" }, "min_goldstein_scale": { "type": "number", "nullable": true }, "max_goldstein_scale": { "type": "number", "nullable": true }, "avg_goldstein_severity": { "type": "number", "nullable": true }, "min_goldstein_severity": { "type": "number", "nullable": true }, "max_goldstein_severity": { "type": "number", "nullable": true }, "avg_magnitude": { "type": "number", "nullable": true }, "min_magnitude": { "type": "number", "nullable": true }, "max_magnitude": { "type": "number", "nullable": true }, "avg_systemic_importance": { "type": "number", "nullable": true }, "min_systemic_importance": { "type": "number", "nullable": true }, "max_systemic_importance": { "type": "number", "nullable": true }, "avg_propagation_potential": { "type": "number", "nullable": true }, "min_propagation_potential": { "type": "number", "nullable": true }, "max_propagation_potential": { "type": "number", "nullable": true }, "avg_market_sensitivity": { "type": "number", "nullable": true }, "min_market_sensitivity": { "type": "number", "nullable": true }, "max_market_sensitivity": { "type": "number", "nullable": true }, "avg_confidence": { "type": "number", "nullable": true }, "min_confidence": { "type": "number", "nullable": true }, "max_confidence": { "type": "number", "nullable": true } } }, "StorySummaryBucket": { "type": "object", "properties": { "key": { "type": "string" }, "group_by": { "type": "string" }, "label": { "type": "string" }, "story_count": { "type": "number", "nullable": true }, "article_count": { "type": "number", "nullable": true }, "avg_article_count": { "type": "number", "nullable": true }, "min_article_count": { "type": "number", "nullable": true }, "max_article_count": { "type": "number", "nullable": true }, "stories_with_events": { "type": "number", "nullable": true }, "story_only_count": { "type": "number", "nullable": true }, "linked_event_count": { "type": "number", "nullable": true }, "min_linked_event_count": { "type": "number", "nullable": true }, "avg_linked_event_count": { "type": "number", "nullable": true }, "max_linked_event_count": { "type": "number", "nullable": true }, "stories_with_fatalities": { "type": "number", "nullable": true }, "fatalities": { "type": "number", "nullable": true }, "fatality_story_rate": { "type": "number", "nullable": true }, "country_count": { "type": "number", "nullable": true }, "region_count": { "type": "number", "nullable": true }, "avg_significance": { "type": "number", "nullable": true }, "max_significance": { "type": "number", "nullable": true }, "min_significance": { "type": "number", "nullable": true }, "metrics": { "type": "object", "properties": { "significance": { "type": "object", "properties": { "avg": { "type": "number", "nullable": true }, "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true } }, "required": [ "avg", "min", "max" ] }, "article_count": { "type": "object", "properties": { "total": { "type": "number", "nullable": true }, "avg": { "type": "number", "nullable": true }, "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true } }, "required": [ "total", "avg", "min", "max" ] }, "linked_events": { "type": "object", "properties": { "count": { "type": "object", "properties": { "total": { "type": "number", "nullable": true }, "avg": { "type": "number", "nullable": true }, "min": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true }, "stories_with_events": { "type": "number", "nullable": true }, "story_only_count": { "type": "number", "nullable": true } }, "required": [ "total", "avg", "min", "max", "stories_with_events", "story_only_count" ] } }, "required": [ "count" ] }, "fatalities": { "type": "object", "properties": { "stories": { "type": "number", "nullable": true }, "rate": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true } }, "required": [ "stories", "rate", "total" ] } }, "required": [ "significance", "article_count", "linked_events", "fatalities" ] } }, "required": [ "key", "group_by", "story_count", "article_count", "avg_article_count", "min_article_count", "max_article_count", "stories_with_events", "story_only_count", "linked_event_count", "min_linked_event_count", "avg_linked_event_count", "max_linked_event_count", "stories_with_fatalities", "fatalities", "fatality_story_rate", "country_count", "region_count", "avg_significance", "max_significance", "min_significance", "metrics" ] }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "next_cursor": { "type": "string", "nullable": true } } }, "PaginatedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object", "description": "Recoverable validation context when available, such as param, invalid_value, accepted_values, nearest_values, and a corrected example.", "additionalProperties": true } } }, "EnergyOwnerEntry": { "type": "object", "additionalProperties": false, "required": [ "name", "entity_id", "stake_pct" ], "properties": { "name": { "type": "string" }, "entity_id": { "type": "string", "nullable": true, "description": "Global Energy Monitor ownership id — **NOT** a spine `e_…` id, despite the shared field name with `FacilityOwner.entity_id`. It keys `/api/v2/energy/owners/{entity_id}` and nothing else: passing it to `/api/v2/events?entity=`, `/api/v2/stories` or `/api/v2/exposure` returns an empty 200 rather than an error. To reach the news layer, resolve the owner NAME through `GET /api/v2/search` and use the `e_…` id that returns.", "example": "E100002021305" }, "stake_pct": { "type": "number", "nullable": true } } }, "EnergyCapacity": { "type": "object", "additionalProperties": false, "required": [ "value", "unit", "mw", "mw_secondary" ], "properties": { "value": { "type": "number", "nullable": true }, "unit": { "type": "string" }, "mw": { "type": "number", "nullable": true, "description": "Populated only for power-generation trackers." }, "mw_secondary": { "type": "number", "nullable": true } } }, "EnergyAssetGeo": { "type": "object", "additionalProperties": false, "required": [ "country", "country_iso3", "secondary_country_iso3", "region", "subregion", "continent", "state_province", "city", "lat", "lon", "location_accuracy" ], "properties": { "country": { "type": "string", "nullable": true }, "country_iso3": { "type": "string", "nullable": true }, "secondary_country_iso3": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "subregion": { "type": "string", "nullable": true }, "continent": { "type": "string", "nullable": true }, "state_province": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "lat": { "type": "number", "nullable": true }, "lon": { "type": "number", "nullable": true }, "location_accuracy": { "type": "string", "nullable": true } } }, "EnergyAssetCard": { "type": "object", "additionalProperties": false, "required": [ "id", "gem_id", "tracker", "tier", "asset_class", "name", "name_local", "name_other", "status", "status_detail", "start_year", "retired_year", "fuel", "capacity", "geo", "owners_raw", "owners", "operators_raw", "operators", "parents_raw", "parents", "wiki_url", "last_updated", "detail_url", "api_url" ], "properties": { "id": { "type": "string" }, "gem_id": { "type": "string", "description": "Global Energy Monitor ASSET id, unique only within its `tracker` — the pair `(tracker, gem_id)` is the key for `/api/v2/energy/assets/{tracker}/{gem_id}`. Distinct from an owner id and from a spine `e_…` id; it identifies a site, not an organisation.", "example": "G100000103819" }, "tracker": { "type": "string", "enum": [ "coal_plants", "coal_mines", "coal_terminals", "oil_gas_plants", "oil_gas_extraction", "lng_terminals", "nuclear", "geothermal", "bioenergy", "hydropower", "solar", "wind", "gas_pipelines", "oil_pipelines", "lng_carriers" ] }, "tier": { "type": "string", "nullable": true }, "asset_class": { "type": "string" }, "name": { "type": "string" }, "name_local": { "type": "string", "nullable": true }, "name_other": { "type": "string", "nullable": true }, "status": { "type": "string" }, "status_detail": { "type": "string", "nullable": true }, "start_year": { "type": "integer", "nullable": true }, "retired_year": { "type": "integer", "nullable": true }, "fuel": { "type": "string", "nullable": true }, "capacity": { "$ref": "#/components/schemas/EnergyCapacity" }, "geo": { "$ref": "#/components/schemas/EnergyAssetGeo" }, "owners_raw": { "type": "string", "nullable": true }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerEntry" } }, "operators_raw": { "type": "string", "nullable": true }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerEntry" } }, "parents_raw": { "type": "string", "nullable": true }, "parents": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerEntry" } }, "wiki_url": { "type": "string", "nullable": true }, "last_updated": { "type": "string", "nullable": true }, "detail_url": { "type": "string" }, "api_url": { "type": "string" } } }, "EnergyPagination": { "type": "object", "additionalProperties": false, "required": [ "limit", "cursor", "next_cursor" ], "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "next_cursor": { "type": "string", "nullable": true } } }, "EnergyBboxEcho": { "type": "object", "additionalProperties": false, "required": [ "latMin", "lonMin", "latMax", "lonMax" ], "properties": { "latMin": { "type": "number" }, "lonMin": { "type": "number" }, "latMax": { "type": "number" }, "lonMax": { "type": "number" } } }, "EnergyNearEcho": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon", "radiusKm" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "radiusKm": { "type": "number" } } }, "EnergyListFiltersEcho": { "type": "object", "additionalProperties": false, "required": [ "tracker", "country_iso3", "status", "tier", "fuel", "capacity_mw_min", "capacity_mw_max", "start_year_min", "start_year_max", "owner_search", "owner_entity_id", "bbox", "near", "search", "operating_only", "asset_class" ], "properties": { "tracker": { "type": "array", "items": { "type": "string" } }, "country_iso3": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "array", "items": { "type": "string" } }, "fuel": { "type": "array", "items": { "type": "string" } }, "capacity_mw_min": { "type": "number", "nullable": true }, "capacity_mw_max": { "type": "number", "nullable": true }, "start_year_min": { "type": "number", "nullable": true }, "start_year_max": { "type": "number", "nullable": true }, "owner_search": { "type": "string", "nullable": true }, "owner_entity_id": { "type": "string", "nullable": true, "description": "The owner filter as applied, echoed back. On this family it is a **GEM ownership id**, not the spine alias the same parameter name carries on `/api/v2/facilities`.", "example": "E100002021305" }, "bbox": { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "latMin", "lonMin", "latMax", "lonMax" ], "properties": { "latMin": { "type": "number" }, "lonMin": { "type": "number" }, "latMax": { "type": "number" }, "lonMax": { "type": "number" } } }, "near": { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "lat", "lon", "radiusKm" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "radiusKm": { "type": "number" } } }, "search": { "type": "string", "nullable": true }, "operating_only": { "type": "boolean" }, "asset_class": { "type": "string", "enum": [ "fixed", "mobile", "all" ] } } }, "EnergyAssetsListResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data", "pagination", "sort", "filters_echo" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyAssetCard" } }, "pagination": { "$ref": "#/components/schemas/EnergyPagination" }, "sort": { "type": "string" }, "filters_echo": { "$ref": "#/components/schemas/EnergyListFiltersEcho" }, "applied_filters": { "type": "object" } } }, "EnergyAssetSummaryBucket": { "type": "object", "additionalProperties": false, "required": [ "bucket", "bucket_kind", "asset_count", "capacity_mw_total", "capacity_mw_avg", "capacity_mw_max", "capacity_mw_min", "status_counts" ], "properties": { "bucket": { "type": "string", "nullable": true }, "bucket_kind": { "type": "string" }, "asset_count": { "type": "number" }, "capacity_mw_total": { "type": "number" }, "capacity_mw_avg": { "type": "number", "nullable": true }, "capacity_mw_max": { "type": "number", "nullable": true }, "capacity_mw_min": { "type": "number", "nullable": true }, "status_counts": { "type": "object", "additionalProperties": false, "required": [ "operating", "construction", "proposed", "cancelled", "retired" ], "properties": { "operating": { "type": "number" }, "construction": { "type": "number" }, "proposed": { "type": "number" }, "cancelled": { "type": "number" }, "retired": { "type": "number" } } } } }, "EnergyAssetsSummaryResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "group_by", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "group_by": { "type": "string", "enum": [ "country", "region", "continent", "tracker", "status", "start_year_decade", "fuel", "tier" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyAssetSummaryBucket" } }, "applied_filters": { "type": "object" } } }, "EnergyMapFiltersEcho": { "type": "object", "additionalProperties": false, "required": [ "tracker", "country_iso3", "status", "tier", "fuel", "operating_only", "asset_class" ], "properties": { "tracker": { "type": "array", "items": { "type": "string" } }, "country_iso3": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "array", "items": { "type": "string" } }, "fuel": { "type": "array", "items": { "type": "string" } }, "operating_only": { "type": "boolean" }, "asset_class": { "type": "string", "enum": [ "fixed", "mobile", "all" ] } } }, "EnergyMapAggregatePoint": { "type": "object", "additionalProperties": false, "required": [ "kind", "country_iso3", "country", "lat", "lon", "asset_count", "capacity_mw_total", "top_tracker", "trackers" ], "properties": { "kind": { "type": "string", "enum": [ "aggregate" ] }, "country_iso3": { "type": "string" }, "country": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "asset_count": { "type": "number" }, "capacity_mw_total": { "type": "number" }, "top_tracker": { "type": "string" }, "trackers": { "type": "array", "items": { "type": "string" } } } }, "EnergyMapFinePoint": { "type": "object", "additionalProperties": false, "required": [ "kind", "gem_id", "tracker", "name", "country_iso3", "country", "lat", "lon", "status", "capacity_mw", "capacity_value", "capacity_unit", "fuel" ], "properties": { "kind": { "type": "string", "enum": [ "fine" ] }, "gem_id": { "type": "string", "description": "Global Energy Monitor asset id for this map pin. Unique within its `tracker` only — carry the tracker alongside it to fetch the asset.", "example": "G100000103819" }, "tracker": { "type": "string" }, "name": { "type": "string" }, "country_iso3": { "type": "string" }, "country": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "status": { "type": "string" }, "capacity_mw": { "type": "number", "nullable": true }, "capacity_value": { "type": "number", "nullable": true }, "capacity_unit": { "type": "string" }, "fuel": { "type": "string" } } }, "EnergyAssetsMapResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "mode", "data", "filters_echo" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "mode": { "type": "string", "enum": [ "aggregate", "fine" ] }, "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/EnergyMapAggregatePoint" }, { "$ref": "#/components/schemas/EnergyMapFinePoint" } ] } }, "filters_echo": { "$ref": "#/components/schemas/EnergyMapFiltersEcho" }, "applied_filters": { "type": "object" } } }, "EnergyAssetDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data", "raw" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EnergyAssetCard" }, "raw": { "type": "object", "additionalProperties": true } } }, "EnergyOwnerPortfolioTracker": { "type": "object", "additionalProperties": false, "required": [ "tracker", "asset_count", "capacity_mw_total", "operating_count", "planned_count", "inactive_count" ], "properties": { "tracker": { "type": "string" }, "asset_count": { "type": "number" }, "capacity_mw_total": { "type": "number" }, "operating_count": { "type": "number" }, "planned_count": { "type": "number" }, "inactive_count": { "type": "number" } } }, "EnergyOwnerPortfolioSummary": { "type": "object", "additionalProperties": false, "required": [ "asset_count", "capacity_mw_total", "by_tracker" ], "properties": { "asset_count": { "type": "number" }, "capacity_mw_total": { "type": "number" }, "by_tracker": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerPortfolioTracker" } } } }, "EnergyOwnerExposureSummary": { "type": "object", "additionalProperties": false, "required": [ "lens", "exposed", "direct", "via_entity_ids", "lists", "china_edges" ], "properties": { "lens": { "type": "string", "enum": [ "sanctions", "china", "state_owned" ] }, "exposed": { "type": "boolean" }, "direct": { "type": "boolean" }, "via_entity_ids": { "type": "array", "items": { "type": "string" } }, "lists": { "type": "array", "items": { "type": "string" } }, "china_edges": { "type": "array", "items": { "type": "string" } } } }, "EnergyOwnerCard": { "type": "object", "additionalProperties": true, "required": [ "entity_id", "full_name", "name", "entity_type", "legal_entity_type", "gem_parents", "gem_parent_ids", "external_ids", "dataset_version", "source_file" ], "properties": { "entity_id": { "type": "string", "description": "Global Energy Monitor ownership id — the key for this endpoint, not a spine `e_…` id. See `EnergyOwnerEntry.entity_id` for how to cross into the news layer.", "example": "E100002021305" }, "full_name": { "type": "string" }, "name": { "type": "string" }, "name_local": { "type": "string", "nullable": true }, "name_other": { "type": "string", "nullable": true }, "abbreviation": { "type": "string", "nullable": true }, "entity_type": { "type": "string" }, "legal_entity_type": { "type": "string" }, "publicly_listed": { "type": "boolean", "nullable": true }, "home_page": { "type": "string", "nullable": true }, "registration_country": { "type": "string" }, "registration_country_iso3": { "type": "string" }, "registration_subdivision": { "type": "string", "nullable": true }, "headquarters_country": { "type": "string" }, "headquarters_country_iso3": { "type": "string" }, "headquarters_subdivision": { "type": "string", "nullable": true }, "gem_parents": { "type": "array", "items": { "type": "string" } }, "gem_parent_ids": { "type": "array", "items": { "type": "string" } }, "external_ids": { "type": "object", "additionalProperties": { "type": "string" } }, "dataset_version": { "type": "string" }, "source_file": { "type": "string" }, "ingested_at": { "type": "string" }, "portfolio_url": { "type": "string", "nullable": true }, "detail_url": { "type": "string", "nullable": true }, "portfolio_summary": { "$ref": "#/components/schemas/EnergyOwnerPortfolioSummary" }, "exposure_summary": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerExposureSummary" } } } }, "EnergyOwnersListResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyOwnerCard" } }, "pagination": { "$ref": "#/components/schemas/EnergyPagination" }, "applied_filters": { "type": "object" } } }, "EnergyOwnerDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/EnergyOwnerCard" } } }, "AtlasGprResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "series_id": { "type": "string", "example": "atlas.pulse.country.ukr.fullspectrum.all" }, "level": { "type": "string" }, "geo_id": { "type": "string" }, "methodology_version": { "type": "string", "example": "atlas-pulse-1.2.0" }, "construction": { "type": "object", "nullable": true, "description": "Present only on `construction=world_corpus`, describing the formula in force.", "properties": { "name": { "type": "string", "enum": [ "world_corpus" ] }, "formula": { "type": "string" }, "denominator": { "type": "string", "enum": [ "global_corpus_size" ] }, "window_days": { "type": "integer", "example": 14 }, "severity_weighting": { "type": "string" } } }, "baseline": { "type": "object", "nullable": true, "description": "The frozen reference the returned rows were measured against.", "properties": { "version": { "type": "string" }, "mean_anchor": { "type": "integer", "enum": [ 100 ] }, "window": { "type": "array", "items": { "type": "string", "format": "date" }, "minItems": 2, "maxItems": 2 }, "fixed": { "type": "boolean", "description": "The base window is frozen, not trailing." }, "coder_version": { "type": "string", "description": "Which coder generation this reference describes." }, "n_obs": { "type": "integer" }, "base_events": { "type": "integer", "nullable": true, "description": "Evidence behind the reference. Null when not yet measured — never a measured zero." }, "bands_usable": { "type": "boolean", "description": "False when the ladder cannot keep its frequency promise; bands are then withheld." }, "provisional": { "type": "boolean" } } }, "coverage_floor": { "type": "number" }, "coverage_floor_basis": { "type": "string", "example": "single_day" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AtlasGprPoint" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "next_cursor": { "type": "string", "nullable": true } } } } }, "AtlasGprPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "pulse": { "type": "number", "nullable": true, "description": "`own_coverage` construction: the index. Null below the coverage floor — never 0." }, "gpr": { "type": "number", "nullable": true, "description": "`world_corpus` construction: the index. Null below the evidence floor — never 0." }, "multiplier": { "type": "string", "nullable": true, "example": "1.5×" }, "band": { "type": "string", "nullable": true, "enum": [ "Subdued", "Normal", "Elevated", "Surging", "Extreme" ], "description": "Own-history deviation, NOT a level word. Null where the ladder cannot support one." }, "band_notation": { "type": "string", "nullable": true, "example": "L3" }, "band_status": { "type": "string", "nullable": true, "enum": [ "degenerate_baseline" ], "description": "Why a reading that cleared the floor still carries no band." }, "tension_share": { "type": "number", "nullable": true, "description": "`own_coverage`: qualifying ÷ the place’s own coverage." }, "corpus_share": { "type": "number", "nullable": true, "description": "`world_corpus`: qualifying ÷ ALL coded events worldwide over the window." }, "world_events": { "type": "integer", "nullable": true, "description": "The corpus size the share was measured against." }, "qualifying_events": { "type": "integer" }, "coverage_events": { "type": "integer", "description": "The place’s own coverage. Reported; never a denominator on `world_corpus`." }, "insufficient_data": { "type": "boolean" }, "insufficient_reason": { "type": "string", "nullable": true, "enum": [ "no_baseline", "base_window_below_floor", "window_incomplete" ] }, "precision": { "type": "object", "nullable": true, "description": "Coverage published as PRECISION — present whether or not the reading cleared.", "properties": { "days_in_window": { "type": "integer" }, "window_days": { "type": "integer" }, "base_events": { "type": "integer", "nullable": true }, "base_event_floor": { "type": "integer" } } }, "baseline_coder_version": { "type": "string", "nullable": true, "description": "The coder generation whose baseline normalized THIS row. A series spanning a change is not one comparable series." }, "source_mix": { "type": "object", "properties": { "effective_source_count": { "type": "integer", "nullable": true }, "new_source_share": { "type": "number", "nullable": true }, "status": { "type": "string", "enum": [ "measured", "not_measured" ], "description": "`not_measured` means the diagnostics pass has not run — the nulls are honest, not a measured zero." } } }, "data_origin": { "type": "string", "nullable": true, "enum": [ "live", "backfill" ] }, "vintage": { "type": "string", "nullable": true, "format": "date" } } }, "ListResponseMeta": { "type": "object", "description": "Where these rows came from and how current they are. Present on every response, including empty ones.", "required": [ "row_source", "settled_at", "row_source_reason" ], "properties": { "row_source": { "type": "string", "enum": [ "live", "settled" ], "description": "`live` — computed from the warehouse at request time. `settled` — read from a pre-built daily snapshot. The rows, their order and their fields are the same either way." }, "settled_at": { "type": "string", "nullable": true, "description": "When the snapshot that answered was built — the OLDEST one in the window you asked for, so it understates rather than overstates. Null on the live path, which has no snapshot to date. This is a build time, not a point-in-time you can request: `as_of` is not supported on this endpoint." }, "row_source_reason": { "type": "string", "enum": [ "settled", "not_settled", "filter_not_supported" ], "description": "`settled` — the snapshot answered. `not_settled` — this window is not fully snapshotted. `filter_not_supported` — a filter you sent cannot be answered from a snapshot, so the request was computed live." } } }, "ScreeningMatchResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "object", "properties": { "q": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "as_of": { "type": "string", "nullable": true }, "min_match_confidence": { "type": "number" }, "threshold": { "type": "number" }, "threshold_deprecated": { "type": "boolean" } }, "required": [ "q", "id", "as_of", "min_match_confidence" ] }, "disclaimer": { "type": "string" }, "coverage": { "type": "string" }, "match_count": { "type": "number" }, "confirmed_match_count": { "type": "number" }, "screen_status": { "type": "string", "enum": [ "matches", "no_match_found", "inconclusive" ], "description": "Conclusive match, no covered candidate found, or unresolved candidate evidence. no_match_found is not compliance clearance." }, "rejected_candidate_count": { "type": "number" }, "rejected_candidates": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "retrieval_method": { "type": "string", "enum": [ "strong_id", "exact_name", "exact_alias", "fuzzy_name", "semantic" ] }, "retrieval_score": { "type": "number" }, "decision": { "type": "string", "enum": [ "no_match" ] }, "decision_evidence": { "type": "string" }, "script_handling": { "type": "string", "enum": [ "same_script", "transliteration", "translation", "identifier", "unknown" ] } }, "required": [ "entity_id", "name", "retrieval_method", "retrieval_score", "decision", "decision_evidence", "script_handling" ] } }, "truncated": { "type": "boolean" }, "truncation_note": { "type": "string" }, "total_matched_entities": { "type": "number" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "score": { "type": "number", "description": "Deprecated compatibility copy of retrieval_score; not an identity probability." }, "confidence": { "type": "string", "enum": [ "strong", "probable", "review" ], "description": "Compatibility retrieval band. Do not use it as an identity verdict; use decision and match_confidence." }, "method": { "type": "string", "enum": [ "strong_id", "exact_name", "exact_alias", "fuzzy_name", "semantic" ], "description": "Deprecated compatibility copy of retrieval_method." }, "retrieval_method": { "type": "string", "enum": [ "strong_id", "exact_name", "exact_alias", "fuzzy_name", "semantic" ], "description": "How the candidate was retrieved. Fuzzy and semantic retrieval expand recall and are independently adjudicated." }, "retrieval_score": { "type": "number", "description": "Retrieval ranking score only; it is not calibrated identity confidence." }, "match_confidence": { "type": "number", "nullable": true, "description": "Calibrated identity confidence. Currently 1 for deterministic verified identifiers/exact names and null for uncalibrated gray candidates." }, "decision": { "type": "string", "enum": [ "match", "review" ] }, "adjudication_status": { "type": "string", "enum": [ "deterministic", "independent_judge", "not_run" ] }, "judge_decision": { "type": "string", "enum": [ "accepted", "rejected", "inconclusive" ] }, "judge_confidence_unscaled": { "type": "number", "nullable": true }, "confidence_calibration": { "type": "string", "enum": [ "deterministic", "pending_heldout_calibration" ] }, "script_handling": { "type": "string", "enum": [ "same_script", "transliteration", "translation", "identifier", "unknown" ], "description": "How cross-script identity evidence was handled. unknown means no supported determination was made." }, "decision_evidence": { "type": "string" }, "lists": { "type": "array", "items": { "type": "object", "properties": { "source_key": { "type": "string" }, "entry_uid": { "type": "string" }, "name": { "type": "string" }, "entity_kind": { "type": "string" }, "country_iso3": { "type": "string", "nullable": true }, "programs": { "type": "array", "items": { "type": "string" } }, "legal_basis": { "type": "string", "nullable": true }, "source_url": { "type": "string", "nullable": true }, "ids": {}, "first_seen_date": { "type": "string" }, "last_seen_date": { "type": "string" }, "match_score": { "type": "number", "description": "Candidate-retrieval similarity for this list row; not an identity probability." } }, "required": [ "source_key", "entry_uid", "name", "entity_kind", "country_iso3", "programs", "legal_basis", "source_url", "ids", "first_seen_date", "last_seen_date", "match_score" ] } }, "exposure": { "nullable": true } }, "required": [ "entity_id", "name", "score", "confidence", "method", "retrieval_method", "retrieval_score", "match_confidence", "decision", "adjudication_status", "judge_decision", "judge_confidence_unscaled", "confidence_calibration", "script_handling", "decision_evidence", "lists", "exposure" ] } }, "note": { "type": "string" } }, "required": [ "success", "query", "disclaimer", "coverage", "match_count", "confirmed_match_count", "screen_status", "matches" ] }, "ExposureResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "lens": { "type": "string", "enum": [ "sanctions", "china", "state_owned" ] }, "subject": { "type": "string", "enum": [ "assets", "entities" ] }, "subject_note": { "type": "string" }, "group_by": { "type": "string" }, "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "gem_id": { "type": "string" }, "tracker": { "type": "string" }, "country_iso3": { "type": "string", "nullable": true }, "capacity_mw": { "type": "number", "nullable": true }, "exposed": { "type": "boolean" }, "direct": { "type": "boolean" }, "max_chain_depth": { "type": "number" }, "exposure_stake_pct": { "type": "number", "nullable": true, "description": "Compatibility name for `effective_stake_pct`; null when chain stake is unknown." }, "effective_stake_pct": { "type": "number", "nullable": true, "description": "Effective stake for the requested entity scope; null when any required ownership percentage is unknown." }, "stake_status": { "type": "string", "enum": [ "known", "partial", "unknown" ] }, "contributing_entity_ids": { "type": "array", "items": { "type": "string" } }, "contributing_lists": { "type": "array", "items": { "type": "string" } }, "paths": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "description": "Terminal spine entity that triggered the selected exposure lens." }, "via": { "type": "string", "description": "GEM ownership entity that directly owns the asset." }, "asset_owner_stake_pct": { "type": "number", "nullable": true }, "chain_ownership_pct": { "type": "number", "nullable": true, "description": "Ownership percentage from the direct asset owner through the ancestor chain." }, "effective_stake_pct": { "type": "number", "nullable": true, "description": "Asset-owner stake multiplied by the complete known chain percentage." }, "stake_status": { "type": "string", "enum": [ "known", "unknown" ] }, "depth": { "type": "number" }, "gem_path": { "type": "array", "items": { "type": "string" }, "description": "GEM ownership-entity path from direct asset owner to the flagged ancestor." } }, "required": [ "entity_id", "via", "asset_owner_stake_pct", "chain_ownership_pct", "effective_stake_pct", "stake_status", "depth", "gem_path" ] } } }, "required": [ "gem_id", "tracker", "country_iso3", "capacity_mw", "exposed", "direct", "max_chain_depth", "exposure_stake_pct", "effective_stake_pct", "stake_status", "contributing_entity_ids", "contributing_lists", "paths" ] }, { "type": "object", "properties": { "entity_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "country_iso3": { "type": "string", "nullable": true }, "direct": { "type": "boolean" }, "via_entity_ids": { "type": "array", "items": { "type": "string" } }, "lists": { "type": "array", "items": { "type": "string" } }, "china_edges": { "type": "array", "items": { "type": "string" } } }, "required": [ "entity_id", "name", "country_iso3", "direct", "via_entity_ids", "lists", "china_edges" ] }, { "type": "object", "properties": { "tracker": { "type": "string" }, "country_iso3": { "type": "string" }, "asset_count": { "type": "number" }, "capacity_mw_total": { "type": "number" }, "direct_count": { "type": "number" } }, "required": [ "asset_count", "capacity_mw_total", "direct_count" ] } ] } }, "pagination": {}, "sort": { "type": "string" }, "resolved_counterparties": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "alias": { "type": "string", "nullable": true }, "country_iso3": { "type": "string", "nullable": true }, "entity_type": { "type": "string" }, "score": { "type": "number" }, "match_type": { "type": "string" }, "match_reason": { "type": "string" } }, "required": [ "entity_id", "name", "alias", "country_iso3", "entity_type", "score", "match_type", "match_reason" ] } }, "timings_ms": { "type": "object", "properties": { "counterparty_search": { "type": "number" } }, "required": [ "counterparty_search" ] }, "applied_filters": {} }, "required": [ "success", "lens", "subject", "data", "resolved_counterparties", "timings_ms", "applied_filters" ] } } }, "tags": [ { "name": "Events", "description": "Coded CAMEO+ / conflict events — search, fetch, and summarize." }, { "name": "Stories", "description": "Clustered narratives (stories) and their articles." }, { "name": "Entities", "description": "People & organizations — resolve a name to an entity, then fetch its profile and tone." }, { "name": "Unified Search", "description": "One fuzzy lookup across every id-space — start here with a name, take the entity id, then reuse it on every other surface. This is the resolver the rest of the API assumes you called first." }, { "name": "Media Intelligence", "description": "Press-coverage tone over time and share of voice against a peer set. Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social signal is an admin-only preview." }, { "name": "Facilities", "description": "Unified physical-asset directory — GEM energy assets, World Port Index ports and Epoch AI data centers on one keyed surface, resolved to spine owners. Requires the `can_use_facilities` entitlement." }, { "name": "Geography", "description": "Admin-1 geography lookups." }, { "name": "Government", "description": "US federal awards (USAspending) and foreign-influence registrations (DOJ NSD FARA), resolved onto the entity spine. Requires the `can_use_gov` entitlement." }, { "name": "Filings", "description": "SEC EDGAR filings, XBRL financials, and relations extracted from filing text. Requires the `can_use_filings` entitlement." }, { "name": "Reference Data", "description": "The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif` entitlement." }, { "name": "Energy", "description": "Global Energy Monitor assets + ownership registry." }, { "name": "AI Compute", "description": "Epoch AI datasets — models, hardware, data centers, companies and chip sales. Requires the `can_use_epoch_ai` entitlement." }, { "name": "Macro Finance", "description": "FRED economic time series — catalog, point-in-time observations and releases. Requires the `can_use_macro` entitlement." }, { "name": "Screening and Reference", "description": "Restricted-party lists, name screening and ownership-chain exposure. Requires the `can_use_screening` / `can_use_exposure` entitlement. Analytical coverage, not an audit-grade compliance control." }, { "name": "China", "description": "China overseas development finance (AidData GCDF). Requires the `can_use_china` entitlement." }, { "name": "Maritime", "description": "AIS-derived vessel flow — chokepoint transits, last-known vessel positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so coverage thins in open ocean. Requires the `can_use_maritime` entitlement." }, { "name": "Atlas Intelligence", "description": "Geopolitical-risk and posture indices computed from GDELT Cloud’s own coded events, normalized to each place’s own frozen baseline." }, { "name": "Briefs", "description": "Source-backed monitoring briefs." }, { "name": "Meta", "description": "Machine-readable discovery: the value vocabularies, the endpoint contracts, and the query-unit cost model. Unmetered, so a client can check before it spends." } ], "x-generated": { "by": "nextjs_/scripts/registry/emit-openapi.ts", "from": "nextjs_/constitution/api", "generated_paths": 17, "shared_enum_params_enriched": 6, "registered_vocabulary_params_bound": 87, "phantom_params_bound": 2, "undeclared_params_bound": 6, "tags": 19, "total_paths": 77, "note": "Paths for registry-declared endpoints are GENERATED from the same descriptors the server enforces at request time. Remaining paths are hand-authored and preserved verbatim until their family is adopted. Do not hand-edit a generated path; run `pnpm gen:contract`." }, "x-tagGroups": [ { "name": "Core", "tags": [ "Events", "Stories", "Entities", "Unified Search", "Media Intelligence", "Facilities", "Geography" ] }, { "name": "Open Feeds", "tags": [ "Government", "Filings", "Reference Data", "Energy", "AI Compute", "Macro Finance", "Screening and Reference", "China", "Maritime" ] }, { "name": "Intel", "tags": [ "Atlas Intelligence", "Briefs", "Meta" ] } ] }