GDELT — Tool Reference
No keyword search. Rolling recent GDELT metadata, geography and tone.
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# coverage_timeline read
Get chronological matching-article volume and average tone with per-bucket ingestion completeness.
Full description
Get chronological matching-article volume, average tone and bucket completeness. Time-only aggregation returns every aligned UTC bucket (maximum 1344). Empty buckets have zero articles and null average tone; coverage_complete false marks buckets intersecting ingestion gaps, not necessarily true zeros. Complete buckets may omit coverage_complete; no true field is synthesized. data.truncated may also be absent for this complete bounded timeline. No keyword/full-text search: only exact metadata filters. Geography filters are article-level, not keyword-proximate. Overall freshness, gaps, mapping coverage and warnings remain in meta. This aggregate has no per-bucket article URLs; use list_articles with the same filters/range for attribution. toolkit_notices highlights incomplete/stale data even with nonempty results; meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Tone averages may be biased in either direction when ingestion is incomplete. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
bucket | "15m" | "1h" | "1d" | Yes | UTC bucket size; start/end must align exactly. At most 1344 periods, returned chronologically without a limit parameter. |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"bucket": {
"description": "UTC bucket size; start/end must align exactly. At most 1344 periods, returned chronologically without a limit parameter.",
"enum": [
"15m",
"1h",
"1d"
],
"title": "Bucket",
"type": "string"
}
},
"required": [
"start",
"end",
"bucket"
],
"title": "TimelineParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
},
"_TimelineData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_TimelineItem"
},
"maxItems": 1344,
"title": "Items",
"type": "array"
},
"truncated": {
"const": false,
"default": false,
"description": "Optional for time-only aggregations, which include every bounded bucket. Omission is preserved.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items"
],
"title": "_TimelineData",
"type": "object"
},
"_TimelineItem": {
"additionalProperties": true,
"properties": {
"dimensions": {
"additionalProperties": {
"type": "string"
},
"title": "Dimensions",
"type": "object"
},
"article_count": {
"minimum": 0,
"title": "Article Count",
"type": "integer"
},
"average_tone": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Tone"
},
"coverage_complete": {
"default": true,
"description": "Explicit false marks a gap-intersecting bucket. Fully covered buckets may omit this field; no true field is synthesized by the toolkit.",
"title": "Coverage Complete",
"type": "boolean"
}
},
"required": [
"dimensions",
"article_count",
"average_tone"
],
"title": "_TimelineItem",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"$ref": "#/$defs/_TimelineData"
}
},
"required": [
"meta",
"data"
],
"title": "TimelineResult",
"type": "object"
} # event_geo_points read
Rank coded action or actor locations of filtered GDELT events by distinct-event count.
Full description
Rank the coded locations of filtered events for one geography role. role selects where GDELT placed the action, or the location attached to Actor1 or Actor2. These are machine-coded and can be wrong: a coded action location is not a verified target, impact or incident site. Items count distinct events (grain distinct_event) and their qualifying mention rows, with coordinates. Events without a mappable (coordinate-bearing) location for the role are not mapped, so an empty result does not mean no events matched; list_events shows whether any do. No tool returns a unique total across the range: list_events returns at most 100 ranked events, and event_timeline counts an event once in every bucket where it is mentioned. Filters and confidence work as in list_events; raising min_confidence removes many low-confidence false codings. No polygons. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window. |
min_confidence | integer | No | Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value. Default: 50 |
action_country | array<string> | No | Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia). Default: [] |
actor1_country | array<string> | No | Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS). Default: [] |
actor2_country | array<string> | No | Three-letter CAMEO country codes of Actor2. Default: [] |
event_root_code | array<string> | No | Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight). Default: [] |
event_code | array<string> | No | Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions). Default: [] |
role | "action" | "actor1" | "actor2" | Yes | Which coded geography to map: where GDELT placed the action, or the location attached to Actor1 or Actor2. None of these is a verified target or impact location. |
limit | integer | No | Maximum ranked points. Truncation is reported; no pagination. Default: 25 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window.",
"format": "date-time",
"title": "End",
"type": "string"
},
"min_confidence": {
"default": 50,
"description": "Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value.",
"maximum": 100,
"minimum": 0,
"title": "Min Confidence",
"type": "integer"
},
"action_country": {
"default": [],
"description": "Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Action Country",
"type": "array"
},
"actor1_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor1 Country",
"type": "array"
},
"actor2_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor2.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor2 Country",
"type": "array"
},
"event_root_code": {
"default": [],
"description": "Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Root Code",
"type": "array"
},
"event_code": {
"default": [],
"description": "Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Code",
"type": "array"
},
"role": {
"description": "Which coded geography to map: where GDELT placed the action, or the location attached to Actor1 or Actor2. None of these is a verified target or impact location.",
"enum": [
"action",
"actor1",
"actor2"
],
"title": "Role",
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum ranked points. Truncation is reported; no pagination.",
"maximum": 1000,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"start",
"end",
"role"
],
"title": "EventGeoParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_EventCoverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "True only when all six feed/stream pairs are complete for the range. False means results are partial.",
"title": "Complete",
"type": "boolean"
},
"feeds": {
"description": "One entry per feed/stream pair (six today: GKG, Events, EventMentions x English, translated).",
"items": {
"$ref": "#/$defs/_EventFeedCoverage"
},
"maxItems": 30,
"minItems": 1,
"title": "Feeds",
"type": "array"
},
"event_id_conflicts": {
"description": "Event IDs recorded in both streams; their canonical record may not be the one a mention meant.",
"minimum": 0,
"title": "Event Id Conflicts",
"type": "integer"
}
},
"required": [
"complete",
"feeds",
"event_id_conflicts"
],
"title": "_EventCoverage",
"type": "object"
},
"_EventFeedCoverage": {
"additionalProperties": true,
"properties": {
"feed": {
"description": "gkg, events or event_mentions; new backend feeds are accepted.",
"title": "Feed",
"type": "string"
},
"stream": {
"title": "Stream",
"type": "string"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"failed_files": {
"minimum": 0,
"title": "Failed Files",
"type": "integer"
},
"pending_files": {
"minimum": 0,
"title": "Pending Files",
"type": "integer"
},
"buffered_files": {
"description": "Pending files still inside the stream's ingest buffer: expected lag, not a gap.",
"minimum": 0,
"title": "Buffered Files",
"type": "integer"
},
"slots_without_listing": {
"description": "Slots GKG lists that this event feed does not; upstream-absent or not yet discovered.",
"minimum": 0,
"title": "Slots Without Listing",
"type": "integer"
},
"complete": {
"title": "Complete",
"type": "boolean"
}
},
"required": [
"feed",
"stream",
"listed_files",
"available_files",
"failed_files",
"pending_files",
"buffered_files",
"slots_without_listing",
"complete"
],
"title": "_EventFeedCoverage",
"type": "object"
},
"_EventGeoData": {
"additionalProperties": true,
"properties": {
"grain": {
"const": "distinct_event",
"title": "Grain",
"type": "string"
},
"items": {
"items": {
"$ref": "#/$defs/_EventGeoItem"
},
"maxItems": 1000,
"title": "Items",
"type": "array"
},
"truncated": {
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"grain",
"items",
"truncated"
],
"title": "_EventGeoData",
"type": "object"
},
"_EventGeoItem": {
"additionalProperties": true,
"properties": {
"role": {
"enum": [
"action_location",
"actor1_location",
"actor2_location"
],
"title": "Role",
"type": "string"
},
"feature_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Feature Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"adm1_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Adm1 Code"
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"title": "Latitude"
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"title": "Longitude"
},
"events": {
"minimum": 0,
"title": "Events",
"type": "integer"
},
"mention_rows": {
"minimum": 0,
"title": "Mention Rows",
"type": "integer"
}
},
"required": [
"role",
"feature_id",
"name",
"country_code",
"adm1_code",
"latitude",
"longitude",
"events",
"mention_rows"
],
"title": "_EventGeoItem",
"type": "object"
},
"_EventRangeMeta": {
"additionalProperties": true,
"description": "Meta for list, timeline and geo results, which must carry the reference count.",
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"time_basis": {
"const": "mention_observation",
"title": "Time Basis",
"type": "string"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_EventCoverage"
},
"event_references": {
"$ref": "#/$defs/_EventReferences",
"description": "Range-wide, not filter-specific: events mentioned in the range without an event record. Required for list, timeline and geo results."
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including extraction-confidence and role-geography caveats.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"time_basis",
"serving_horizon",
"coverage",
"event_references",
"warnings"
],
"title": "_EventRangeMeta",
"type": "object"
},
"_EventReferences": {
"additionalProperties": true,
"properties": {
"min_confidence": {
"title": "Min Confidence",
"type": "integer"
},
"referenced_events": {
"minimum": 0,
"title": "Referenced Events",
"type": "integer"
},
"unresolved_event_references": {
"description": "Range-wide (not filter-specific) count of mentioned events without an event record: older_than_window + missing_within_window.",
"minimum": 0,
"title": "Unresolved Event References",
"type": "integer"
},
"older_than_window": {
"description": "Events first recorded before the rolling Event window; mentioned but not included in event results.",
"minimum": 0,
"title": "Older Than Window",
"type": "integer"
},
"missing_within_window": {
"description": "Events recorded inside the window whose Events file is missing, failed, pending or not yet ingested.",
"minimum": 0,
"title": "Missing Within Window",
"type": "integer"
},
"unresolved_percent": {
"maximum": 100,
"minimum": 0,
"title": "Unresolved Percent",
"type": "number"
},
"cross_stream_references": {
"description": "Events mentioned from the other stream than the one that recorded them (normal; resolved by ID).",
"minimum": 0,
"title": "Cross Stream References",
"type": "integer"
},
"event_window_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Window Start"
}
},
"required": [
"min_confidence",
"referenced_events",
"unresolved_event_references",
"older_than_window",
"missing_within_window",
"unresolved_percent",
"cross_stream_references",
"event_window_start"
],
"title": "_EventReferences",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_EventRangeMeta"
},
"data": {
"$ref": "#/$defs/_EventGeoData"
}
},
"required": [
"meta",
"data"
],
"title": "EventGeoResult",
"type": "object"
} # event_timeline read
Get distinct-event and mention-row counts per hour or day for filtered GDELT CAMEO events.
Full description
Get distinct matching events and mention rows per UTC hour or day. Every aligned bucket in range is returned, including zeros. data.metric is distinct_events: an event counts once per bucket in which it has at least one qualifying mention. mention_rows is reported separately and must not be described as event volume. Buckets use mention-observation time. Filters and confidence work as in list_events. Zeros during incomplete coverage are not evidence of absence; check meta.coverage and toolkit_notices. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window. |
min_confidence | integer | No | Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value. Default: 50 |
action_country | array<string> | No | Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia). Default: [] |
actor1_country | array<string> | No | Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS). Default: [] |
actor2_country | array<string> | No | Three-letter CAMEO country codes of Actor2. Default: [] |
event_root_code | array<string> | No | Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight). Default: [] |
event_code | array<string> | No | Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions). Default: [] |
bucket | "1h" | "1d" | No | UTC bucket size; start/end must align exactly. At most 1344 periods; every bucket in range is returned chronologically. Default: "1d" |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window.",
"format": "date-time",
"title": "End",
"type": "string"
},
"min_confidence": {
"default": 50,
"description": "Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value.",
"maximum": 100,
"minimum": 0,
"title": "Min Confidence",
"type": "integer"
},
"action_country": {
"default": [],
"description": "Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Action Country",
"type": "array"
},
"actor1_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor1 Country",
"type": "array"
},
"actor2_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor2.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor2 Country",
"type": "array"
},
"event_root_code": {
"default": [],
"description": "Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Root Code",
"type": "array"
},
"event_code": {
"default": [],
"description": "Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Code",
"type": "array"
},
"bucket": {
"default": "1d",
"description": "UTC bucket size; start/end must align exactly. At most 1344 periods; every bucket in range is returned chronologically.",
"enum": [
"1h",
"1d"
],
"title": "Bucket",
"type": "string"
}
},
"required": [
"start",
"end"
],
"title": "EventTimelineParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_EventBucket": {
"additionalProperties": true,
"properties": {
"start": {
"title": "Start",
"type": "string"
},
"events": {
"description": "Distinct events with at least one qualifying mention in the bucket.",
"minimum": 0,
"title": "Events",
"type": "integer"
},
"mention_rows": {
"description": "Qualifying mention rows in the bucket; never the same thing as event volume.",
"minimum": 0,
"title": "Mention Rows",
"type": "integer"
}
},
"required": [
"start",
"events",
"mention_rows"
],
"title": "_EventBucket",
"type": "object"
},
"_EventCoverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "True only when all six feed/stream pairs are complete for the range. False means results are partial.",
"title": "Complete",
"type": "boolean"
},
"feeds": {
"description": "One entry per feed/stream pair (six today: GKG, Events, EventMentions x English, translated).",
"items": {
"$ref": "#/$defs/_EventFeedCoverage"
},
"maxItems": 30,
"minItems": 1,
"title": "Feeds",
"type": "array"
},
"event_id_conflicts": {
"description": "Event IDs recorded in both streams; their canonical record may not be the one a mention meant.",
"minimum": 0,
"title": "Event Id Conflicts",
"type": "integer"
}
},
"required": [
"complete",
"feeds",
"event_id_conflicts"
],
"title": "_EventCoverage",
"type": "object"
},
"_EventFeedCoverage": {
"additionalProperties": true,
"properties": {
"feed": {
"description": "gkg, events or event_mentions; new backend feeds are accepted.",
"title": "Feed",
"type": "string"
},
"stream": {
"title": "Stream",
"type": "string"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"failed_files": {
"minimum": 0,
"title": "Failed Files",
"type": "integer"
},
"pending_files": {
"minimum": 0,
"title": "Pending Files",
"type": "integer"
},
"buffered_files": {
"description": "Pending files still inside the stream's ingest buffer: expected lag, not a gap.",
"minimum": 0,
"title": "Buffered Files",
"type": "integer"
},
"slots_without_listing": {
"description": "Slots GKG lists that this event feed does not; upstream-absent or not yet discovered.",
"minimum": 0,
"title": "Slots Without Listing",
"type": "integer"
},
"complete": {
"title": "Complete",
"type": "boolean"
}
},
"required": [
"feed",
"stream",
"listed_files",
"available_files",
"failed_files",
"pending_files",
"buffered_files",
"slots_without_listing",
"complete"
],
"title": "_EventFeedCoverage",
"type": "object"
},
"_EventRangeMeta": {
"additionalProperties": true,
"description": "Meta for list, timeline and geo results, which must carry the reference count.",
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"time_basis": {
"const": "mention_observation",
"title": "Time Basis",
"type": "string"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_EventCoverage"
},
"event_references": {
"$ref": "#/$defs/_EventReferences",
"description": "Range-wide, not filter-specific: events mentioned in the range without an event record. Required for list, timeline and geo results."
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including extraction-confidence and role-geography caveats.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"time_basis",
"serving_horizon",
"coverage",
"event_references",
"warnings"
],
"title": "_EventRangeMeta",
"type": "object"
},
"_EventReferences": {
"additionalProperties": true,
"properties": {
"min_confidence": {
"title": "Min Confidence",
"type": "integer"
},
"referenced_events": {
"minimum": 0,
"title": "Referenced Events",
"type": "integer"
},
"unresolved_event_references": {
"description": "Range-wide (not filter-specific) count of mentioned events without an event record: older_than_window + missing_within_window.",
"minimum": 0,
"title": "Unresolved Event References",
"type": "integer"
},
"older_than_window": {
"description": "Events first recorded before the rolling Event window; mentioned but not included in event results.",
"minimum": 0,
"title": "Older Than Window",
"type": "integer"
},
"missing_within_window": {
"description": "Events recorded inside the window whose Events file is missing, failed, pending or not yet ingested.",
"minimum": 0,
"title": "Missing Within Window",
"type": "integer"
},
"unresolved_percent": {
"maximum": 100,
"minimum": 0,
"title": "Unresolved Percent",
"type": "number"
},
"cross_stream_references": {
"description": "Events mentioned from the other stream than the one that recorded them (normal; resolved by ID).",
"minimum": 0,
"title": "Cross Stream References",
"type": "integer"
},
"event_window_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Window Start"
}
},
"required": [
"min_confidence",
"referenced_events",
"unresolved_event_references",
"older_than_window",
"missing_within_window",
"unresolved_percent",
"cross_stream_references",
"event_window_start"
],
"title": "_EventReferences",
"type": "object"
},
"_EventTimelineData": {
"additionalProperties": true,
"properties": {
"bucket": {
"enum": [
"1h",
"1d"
],
"title": "Bucket",
"type": "string"
},
"metric": {
"const": "distinct_events",
"title": "Metric",
"type": "string"
},
"buckets": {
"items": {
"$ref": "#/$defs/_EventBucket"
},
"maxItems": 1344,
"title": "Buckets",
"type": "array"
}
},
"required": [
"bucket",
"metric",
"buckets"
],
"title": "_EventTimelineData",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_EventRangeMeta"
},
"data": {
"$ref": "#/$defs/_EventTimelineData"
}
},
"required": [
"meta",
"data"
],
"title": "EventTimelineResult",
"type": "object"
} # geo_by_adm1 read
Rank mentioned ADM1 regions by filtered distinct-article density within each region's total coverage.
Full description
Rank mentioned ADM1 regions by normalized distinct-article density, with samples. City/landmark mentions roll up to GDELT/FIPS ADM1; country-only mentions without ADM1 are omitted. Density divides filtered distinct documents by all documents mentioning the region in the interval, ignoring all filters in the denominator. Geography is article-level, not keyword-proximate. No keyword/full-text search; use exact metadata filters. Inspect meta for freshness, ingestion gaps, mapping coverage and warnings. No polygons. data.truncated reports the ranking cap. toolkit_notices highlights incomplete or stale data even with nonempty results; densities are not lower bounds. meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
limit | integer | No | Maximum density-ranked groups. Truncation is reported; no pagination. Default: 25 |
sample_limit | integer | No | Attributed sample articles per group; 0 explicitly omits samples. Default: 3 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"limit": {
"default": 25,
"description": "Maximum density-ranked groups. Truncation is reported; no pagination.",
"maximum": 300,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sample_limit": {
"default": 3,
"description": "Attributed sample articles per group; 0 explicitly omits samples.",
"maximum": 5,
"minimum": 0,
"title": "Sample Limit",
"type": "integer"
}
},
"required": [
"start",
"end"
],
"title": "GeographyParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_Adm1Data": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_Adm1Item"
},
"maxItems": 300,
"title": "Items",
"type": "array"
},
"truncated": {
"description": "Whether density-ranked ADM1 regions exceed the requested limit; no cursor.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"truncated"
],
"title": "_Adm1Data",
"type": "object"
},
"_Adm1Item": {
"additionalProperties": true,
"properties": {
"matching_articles": {
"minimum": 0,
"title": "Matching Articles",
"type": "integer"
},
"all_articles": {
"minimum": 0,
"title": "All Articles",
"type": "integer"
},
"density_percent": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Density Percent"
},
"sample_articles": {
"items": {
"$ref": "#/$defs/_Sample"
},
"maxItems": 5,
"title": "Sample Articles",
"type": "array"
},
"adm1_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Adm1 Code"
}
},
"required": [
"matching_articles",
"all_articles",
"density_percent",
"sample_articles",
"adm1_code"
],
"title": "_Adm1Item",
"type": "object"
},
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
},
"_Sample": {
"additionalProperties": true,
"properties": {
"observed_at": {
"title": "Observed At",
"type": "string"
},
"url": {
"minLength": 1,
"title": "Url",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"outlet": {
"title": "Outlet",
"type": "string"
}
},
"required": [
"observed_at",
"url",
"title",
"outlet"
],
"title": "_Sample",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"$ref": "#/$defs/_Adm1Data"
}
},
"required": [
"meta",
"data"
],
"title": "Adm1Result",
"type": "object"
} # geo_by_country read
Rank mentioned countries by filtered distinct-article density within each country's total coverage.
Full description
Rank mentioned countries by normalized distinct-article density, with samples. Density = 100 * matching documents mentioning the country / all documents mentioning it in the interval; the denominator ignores ALL request filters. This is not a share of returned results. Codes are GDELT/FIPS, not necessarily ISO. Geography is article-level, not keyword-proximate, and phase one has no keyword/full-text search. Use exact metadata filters. Freshness, ingestion gaps, mapping coverage and warnings pass through in meta. No polygon output. data.truncated reports the ranking cap. toolkit_notices highlights incomplete or stale data even with nonempty results; densities are not lower bounds. meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
limit | integer | No | Maximum density-ranked groups. Truncation is reported; no pagination. Default: 25 |
sample_limit | integer | No | Attributed sample articles per group; 0 explicitly omits samples. Default: 3 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"limit": {
"default": 25,
"description": "Maximum density-ranked groups. Truncation is reported; no pagination.",
"maximum": 300,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sample_limit": {
"default": 3,
"description": "Attributed sample articles per group; 0 explicitly omits samples.",
"maximum": 5,
"minimum": 0,
"title": "Sample Limit",
"type": "integer"
}
},
"required": [
"start",
"end"
],
"title": "GeographyParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_CountriesData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_CountryItem"
},
"maxItems": 300,
"title": "Items",
"type": "array"
},
"truncated": {
"description": "Whether density-ranked countries exceed the requested limit; no cursor.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"truncated"
],
"title": "_CountriesData",
"type": "object"
},
"_CountryItem": {
"additionalProperties": true,
"properties": {
"matching_articles": {
"minimum": 0,
"title": "Matching Articles",
"type": "integer"
},
"all_articles": {
"minimum": 0,
"title": "All Articles",
"type": "integer"
},
"density_percent": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Density Percent"
},
"sample_articles": {
"items": {
"$ref": "#/$defs/_Sample"
},
"maxItems": 5,
"title": "Sample Articles",
"type": "array"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
}
},
"required": [
"matching_articles",
"all_articles",
"density_percent",
"sample_articles",
"country_code"
],
"title": "_CountryItem",
"type": "object"
},
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
},
"_Sample": {
"additionalProperties": true,
"properties": {
"observed_at": {
"title": "Observed At",
"type": "string"
},
"url": {
"minLength": 1,
"title": "Url",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"outlet": {
"title": "Outlet",
"type": "string"
}
},
"required": [
"observed_at",
"url",
"title",
"outlet"
],
"title": "_Sample",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"$ref": "#/$defs/_CountriesData"
}
},
"required": [
"meta",
"data"
],
"title": "CountriesResult",
"type": "object"
} # geo_by_source_country read
Rank mapped outlet-origin countries by filtered distinct-article density, exposing mapping omissions.
Full description
Rank mapped outlet-origin countries by normalized distinct-article density. This is outlet origin, not mentioned geography. Density divides matching mapped documents by ALL mapped documents from the country in the interval. Unknown/ambiguous assignments are excluded from both counts and quantified in meta.source_country_mapping (pre-filter, physical-row coverage). Samples provide attribution. Geography filters are article-level, not keyword- proximate. No keyword/full-text search; use exact metadata filters. Freshness, gaps and warnings pass through in meta. No polygons. data.truncated reports the ranking cap. toolkit_notices highlights incomplete or stale data even with nonempty results; densities are not lower bounds. meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
limit | integer | No | Maximum density-ranked groups. Truncation is reported; no pagination. Default: 25 |
sample_limit | integer | No | Attributed sample articles per group; 0 explicitly omits samples. Default: 3 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"limit": {
"default": 25,
"description": "Maximum density-ranked groups. Truncation is reported; no pagination.",
"maximum": 300,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sample_limit": {
"default": 3,
"description": "Attributed sample articles per group; 0 explicitly omits samples.",
"maximum": 5,
"minimum": 0,
"title": "Sample Limit",
"type": "integer"
}
},
"required": [
"start",
"end"
],
"title": "GeographyParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
},
"_Sample": {
"additionalProperties": true,
"properties": {
"observed_at": {
"title": "Observed At",
"type": "string"
},
"url": {
"minLength": 1,
"title": "Url",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"outlet": {
"title": "Outlet",
"type": "string"
}
},
"required": [
"observed_at",
"url",
"title",
"outlet"
],
"title": "_Sample",
"type": "object"
},
"_SourceCountriesData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_SourceCountryItem"
},
"maxItems": 300,
"title": "Items",
"type": "array"
},
"truncated": {
"description": "Whether density-ranked outlet-origin countries exceed the requested limit; no cursor.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"truncated"
],
"title": "_SourceCountriesData",
"type": "object"
},
"_SourceCountryItem": {
"additionalProperties": true,
"properties": {
"matching_articles": {
"minimum": 0,
"title": "Matching Articles",
"type": "integer"
},
"all_articles": {
"minimum": 0,
"title": "All Articles",
"type": "integer"
},
"density_percent": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Density Percent"
},
"sample_articles": {
"items": {
"$ref": "#/$defs/_Sample"
},
"maxItems": 5,
"title": "Sample Articles",
"type": "array"
},
"source_country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Country Code"
}
},
"required": [
"matching_articles",
"all_articles",
"density_percent",
"sample_articles",
"source_country_code"
],
"title": "_SourceCountryItem",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"$ref": "#/$defs/_SourceCountriesData"
}
},
"required": [
"meta",
"data"
],
"title": "SourceCountriesResult",
"type": "object"
} # geo_points read
Rank article-level GKG places by matching article count; compact by default, explicit GeoJSON available.
Full description
Rank GKG places by distinct matching article count, with attributed samples. Geography is article-level: places may occur anywhere in each matching article, not near a keyword. Phase one has no keyword/full-text search; use exact metadata filters. Compact ranked names/counts include coordinates; explicitly choose geojson for a FeatureCollection of [longitude, latitude] points. No polygons. meta retains freshness, gaps, mapping coverage and warnings; check it even for empty results. Samples are omitted only when sample_limit=0 or none are available. Compact truncation is data.truncated; GeoJSON's top-level truncated may be absent (not proof of completeness). toolkit_notices highlights incomplete/stale data even with nonempty results; meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
limit | integer | No | Maximum ranked points; a compact 25 by default. Truncation is reported, not paginated. Default: 25 |
sample_limit | integer | No | Attributed sample articles per point; 0 explicitly omits samples. Default: 3 |
format | "compact" | "geojson" | No | Compact ranked names/counts with coordinates, or explicit GeoJSON points for mapping. Default: "compact" |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"limit": {
"default": 25,
"description": "Maximum ranked points; a compact 25 by default. Truncation is reported, not paginated.",
"maximum": 1000,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sample_limit": {
"default": 3,
"description": "Attributed sample articles per point; 0 explicitly omits samples.",
"maximum": 5,
"minimum": 0,
"title": "Sample Limit",
"type": "integer"
},
"format": {
"default": "compact",
"description": "Compact ranked names/counts with coordinates, or explicit GeoJSON points for mapping.",
"enum": [
"compact",
"geojson"
],
"title": "Format",
"type": "string"
}
},
"required": [
"start",
"end"
],
"title": "PointsParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Feature": {
"additionalProperties": true,
"properties": {
"type": {
"const": "Feature",
"title": "Type",
"type": "string"
},
"geometry": {
"$ref": "#/$defs/_Geometry"
},
"properties": {
"$ref": "#/$defs/_PointProperties"
}
},
"required": [
"type",
"geometry",
"properties"
],
"title": "_Feature",
"type": "object"
},
"_Geometry": {
"additionalProperties": true,
"properties": {
"type": {
"const": "Point",
"title": "Type",
"type": "string"
},
"coordinates": {
"items": {
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"title": "Coordinates",
"type": "array"
}
},
"required": [
"type",
"coordinates"
],
"title": "_Geometry",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_PointItem": {
"additionalProperties": true,
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"feature_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Feature Id"
},
"article_count": {
"minimum": 0,
"title": "Article Count",
"type": "integer"
},
"sample_articles": {
"items": {
"$ref": "#/$defs/_Sample"
},
"maxItems": 5,
"title": "Sample Articles",
"type": "array"
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"title": "Latitude"
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"title": "Longitude"
}
},
"required": [
"name",
"country_code",
"feature_id",
"article_count",
"sample_articles",
"latitude",
"longitude"
],
"title": "_PointItem",
"type": "object"
},
"_PointProperties": {
"additionalProperties": true,
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"feature_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Feature Id"
},
"article_count": {
"minimum": 0,
"title": "Article Count",
"type": "integer"
},
"sample_articles": {
"items": {
"$ref": "#/$defs/_Sample"
},
"maxItems": 5,
"title": "Sample Articles",
"type": "array"
}
},
"required": [
"name",
"country_code",
"feature_id",
"article_count",
"sample_articles"
],
"title": "_PointProperties",
"type": "object"
},
"_PointsData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_PointItem"
},
"maxItems": 1000,
"title": "Items",
"type": "array"
},
"truncated": {
"description": "True when compact ranked points exceed the requested limit; no cursor pagination.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"truncated"
],
"title": "_PointsData",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
},
"_Sample": {
"additionalProperties": true,
"properties": {
"observed_at": {
"title": "Observed At",
"type": "string"
},
"url": {
"minLength": 1,
"title": "Url",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"outlet": {
"title": "Outlet",
"type": "string"
}
},
"required": [
"observed_at",
"url",
"title",
"outlet"
],
"title": "_Sample",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"anyOf": [
{
"$ref": "#/$defs/_PointsData"
},
{
"type": "null"
}
],
"default": null,
"description": "Compact format only: data.items and data.truncated. Absent for GeoJSON."
},
"type": {
"anyOf": [
{
"const": "FeatureCollection",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "GeoJSON format only.",
"title": "Type"
},
"features": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/_Feature"
},
"maxItems": 1000,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "GeoJSON format only: Point features with [longitude, latitude] coordinates and attributed sample_articles in properties.",
"title": "Features"
},
"truncated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional backend GeoJSON foreign member. Omission is preserved, not an assurance that all ranked points fit.",
"title": "Truncated"
}
},
"required": [
"meta"
],
"title": "PointsResult",
"type": "object"
} # get_event_mentions read
List the attributed article mentions of one GDELT event, strongest extraction confidence first.
Full description
List the physical mentions of one event, with article attribution. Pass event.global_event_id from list_events. Mentions come from both the English and translated streams. Each row carries, when GDELT supplies them, its URL, outlet, extraction confidence, sentence and character offsets, and the exact same-stream GKG article join (title, outlet-country status); any of these can be null, and article can be empty. data.event holds the event's coded record, or null with a warning when the event predates the rolling Event window or is not loaded. A nonexistent ID returns event_not_found. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window. |
min_confidence | integer | No | Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value. Default: 50 |
global_event_id | integer | Yes | GDELT GlobalEventID from list_events (event.global_event_id). IDs are shared across the English and translated streams. |
limit | integer | No | Maximum mention rows, strongest extraction confidence first. Truncation is reported. Default: 25 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window.",
"format": "date-time",
"title": "End",
"type": "string"
},
"min_confidence": {
"default": 50,
"description": "Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value.",
"maximum": 100,
"minimum": 0,
"title": "Min Confidence",
"type": "integer"
},
"global_event_id": {
"description": "GDELT GlobalEventID from list_events (event.global_event_id). IDs are shared across the English and translated streams.",
"maximum": 9223372036854776000,
"minimum": 1,
"title": "Global Event Id",
"type": "integer"
},
"limit": {
"default": 25,
"description": "Maximum mention rows, strongest extraction confidence first. Truncation is reported.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"start",
"end",
"global_event_id"
],
"title": "EventMentionsParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_EventActor": {
"additionalProperties": true,
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Code"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/_EventLocation"
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"name",
"country_code",
"location"
],
"title": "_EventActor",
"type": "object"
},
"_EventCoverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "True only when all six feed/stream pairs are complete for the range. False means results are partial.",
"title": "Complete",
"type": "boolean"
},
"feeds": {
"description": "One entry per feed/stream pair (six today: GKG, Events, EventMentions x English, translated).",
"items": {
"$ref": "#/$defs/_EventFeedCoverage"
},
"maxItems": 30,
"minItems": 1,
"title": "Feeds",
"type": "array"
},
"event_id_conflicts": {
"description": "Event IDs recorded in both streams; their canonical record may not be the one a mention meant.",
"minimum": 0,
"title": "Event Id Conflicts",
"type": "integer"
}
},
"required": [
"complete",
"feeds",
"event_id_conflicts"
],
"title": "_EventCoverage",
"type": "object"
},
"_EventFeedCoverage": {
"additionalProperties": true,
"properties": {
"feed": {
"description": "gkg, events or event_mentions; new backend feeds are accepted.",
"title": "Feed",
"type": "string"
},
"stream": {
"title": "Stream",
"type": "string"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"failed_files": {
"minimum": 0,
"title": "Failed Files",
"type": "integer"
},
"pending_files": {
"minimum": 0,
"title": "Pending Files",
"type": "integer"
},
"buffered_files": {
"description": "Pending files still inside the stream's ingest buffer: expected lag, not a gap.",
"minimum": 0,
"title": "Buffered Files",
"type": "integer"
},
"slots_without_listing": {
"description": "Slots GKG lists that this event feed does not; upstream-absent or not yet discovered.",
"minimum": 0,
"title": "Slots Without Listing",
"type": "integer"
},
"complete": {
"title": "Complete",
"type": "boolean"
}
},
"required": [
"feed",
"stream",
"listed_files",
"available_files",
"failed_files",
"pending_files",
"buffered_files",
"slots_without_listing",
"complete"
],
"title": "_EventFeedCoverage",
"type": "object"
},
"_EventLocation": {
"additionalProperties": true,
"properties": {
"role": {
"enum": [
"action_location",
"actor1_location",
"actor2_location"
],
"title": "Role",
"type": "string"
},
"type": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Type"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"adm1_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Adm1 Code"
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"title": "Latitude"
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"title": "Longitude"
},
"feature_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Feature Id"
}
},
"required": [
"role",
"type",
"name",
"country_code",
"adm1_code",
"latitude",
"longitude",
"feature_id"
],
"title": "_EventLocation",
"type": "object"
},
"_EventMentionItem": {
"additionalProperties": true,
"properties": {
"mention_stream": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mention Stream"
},
"observed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observed At"
},
"event_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Time"
},
"mention_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mention Time"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
},
"outlet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Outlet"
},
"mention_type": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Mention Type"
},
"confidence": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Confidence"
},
"in_raw_text": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "In Raw Text"
},
"sentence_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sentence Id"
},
"char_offsets": {
"additionalProperties": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"title": "Char Offsets",
"type": "object"
},
"document_tone": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Document Tone"
},
"translation_info": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Translation Info"
},
"article": {
"additionalProperties": true,
"description": "Exact same-stream GKG join: join_status joined/not_found, title, source_country_code, source_country_status (conflicting_rows when GKG rows disagree).",
"title": "Article",
"type": "object"
}
},
"required": [
"mention_stream",
"observed_at",
"event_time",
"mention_time",
"url",
"outlet",
"mention_type",
"confidence",
"in_raw_text",
"sentence_id",
"char_offsets",
"document_tone",
"translation_info",
"article"
],
"title": "_EventMentionItem",
"type": "object"
},
"_EventMentionsData": {
"additionalProperties": true,
"properties": {
"event": {
"anyOf": [
{
"$ref": "#/$defs/_EventRecord"
},
{
"type": "null"
}
],
"description": "Null when the event is outside the rolling window or not loaded; see meta.warnings for which."
},
"items": {
"items": {
"$ref": "#/$defs/_EventMentionItem"
},
"maxItems": 100,
"title": "Items",
"type": "array"
},
"truncated": {
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"event",
"items",
"truncated"
],
"title": "_EventMentionsData",
"type": "object"
},
"_EventMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"time_basis": {
"const": "mention_observation",
"title": "Time Basis",
"type": "string"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_EventCoverage"
},
"event_references": {
"anyOf": [
{
"$ref": "#/$defs/_EventReferences"
},
{
"type": "null"
}
],
"default": null,
"description": "Present for list, timeline and geo results; omitted for single-event mentions."
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including extraction-confidence and role-geography caveats.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"time_basis",
"serving_horizon",
"coverage",
"warnings"
],
"title": "_EventMeta",
"type": "object"
},
"_EventRecord": {
"additionalProperties": true,
"properties": {
"stream": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Stream in which GDELT recorded the event (english or translation); mentions may come from either stream.",
"title": "Stream"
},
"global_event_id": {
"minimum": 1,
"title": "Global Event Id",
"type": "integer"
},
"event_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Date"
},
"cameo": {
"additionalProperties": true,
"title": "Cameo",
"type": "object"
},
"goldstein_scale": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Goldstein Scale"
},
"average_tone": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Tone"
},
"actor1": {
"$ref": "#/$defs/_EventActor"
},
"actor2": {
"$ref": "#/$defs/_EventActor"
},
"action_location": {
"anyOf": [
{
"$ref": "#/$defs/_EventLocation"
},
{
"type": "null"
}
]
},
"source_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Url"
}
},
"required": [
"stream",
"global_event_id",
"event_date",
"cameo",
"goldstein_scale",
"average_tone",
"actor1",
"actor2",
"action_location",
"source_url"
],
"title": "_EventRecord",
"type": "object"
},
"_EventReferences": {
"additionalProperties": true,
"properties": {
"min_confidence": {
"title": "Min Confidence",
"type": "integer"
},
"referenced_events": {
"minimum": 0,
"title": "Referenced Events",
"type": "integer"
},
"unresolved_event_references": {
"description": "Range-wide (not filter-specific) count of mentioned events without an event record: older_than_window + missing_within_window.",
"minimum": 0,
"title": "Unresolved Event References",
"type": "integer"
},
"older_than_window": {
"description": "Events first recorded before the rolling Event window; mentioned but not included in event results.",
"minimum": 0,
"title": "Older Than Window",
"type": "integer"
},
"missing_within_window": {
"description": "Events recorded inside the window whose Events file is missing, failed, pending or not yet ingested.",
"minimum": 0,
"title": "Missing Within Window",
"type": "integer"
},
"unresolved_percent": {
"maximum": 100,
"minimum": 0,
"title": "Unresolved Percent",
"type": "number"
},
"cross_stream_references": {
"description": "Events mentioned from the other stream than the one that recorded them (normal; resolved by ID).",
"minimum": 0,
"title": "Cross Stream References",
"type": "integer"
},
"event_window_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Window Start"
}
},
"required": [
"min_confidence",
"referenced_events",
"unresolved_event_references",
"older_than_window",
"missing_within_window",
"unresolved_percent",
"cross_stream_references",
"event_window_start"
],
"title": "_EventReferences",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_EventMeta"
},
"data": {
"$ref": "#/$defs/_EventMentionsData"
}
},
"required": [
"meta",
"data"
],
"title": "EventMentionsResult",
"type": "object"
} # get_status read
Get GDELT's current retained window, freshness, ingestion gaps and outlet-country mapping coverage.
Full description
Get the backend's current retained window, freshness, gaps and mapping coverage. Call before choosing a query interval; the backend, not the toolkit, owns retention. Degraded/stale status is preserved. No keyword search exists in phase one; query geography is article-level, not keyword-proximate. This endpoint does not provide a theme/entity/code catalog or reference taxonomy. toolkit_notices highlights incomplete/stale data; data.coverage.buffered_files distinguishes buffered lag from data.coverage.unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
No parameters.
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {},
"title": "StatusParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_ResponseMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
}
},
"required": [
"request_id",
"generated_at"
],
"title": "_ResponseMeta",
"type": "object"
},
"_StatusData": {
"additionalProperties": true,
"properties": {
"status": {
"enum": [
"ok",
"degraded"
],
"title": "Status",
"type": "string"
},
"freshness_seconds": {
"minimum": 0,
"title": "Freshness Seconds",
"type": "integer"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"hot_store": {
"additionalProperties": {
"type": "integer"
},
"title": "Hot Store",
"type": "object"
},
"newest_successful_ingest_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Newest Successful Ingest At"
}
},
"required": [
"status",
"freshness_seconds",
"serving_horizon",
"coverage",
"source_country_mapping",
"hot_store",
"newest_successful_ingest_at"
],
"title": "_StatusData",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_ResponseMeta"
},
"data": {
"$ref": "#/$defs/_StatusData"
}
},
"required": [
"meta",
"data"
],
"title": "StatusResult",
"type": "object"
} # list_articles read
List distinct article URLs matching exact GKG metadata filters, with opaque cursor pagination.
Full description
List distinct article URLs matching exact GKG metadata, with cursor pagination. No keyword/full-text search. Geography filters are article-level, not keyword- proximate. Results order by observed_at descending then URL; observed_at is earliest matching GKG slot, not publication time. Titles/publication times may be null. Reuse data.next_cursor unchanged with identical range, filters and limit. URL/outlet provide attribution. Preserve and inspect meta freshness, ingestion gaps, mapping coverage and warnings, including on empty pages. data.truncated is true exactly when data.next_cursor is non-null. toolkit_notices highlights incomplete/stale data even with nonempty results; meta.coverage.buffered_files distinguishes lag from unexpected_gap_files. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping. |
theme | array<string> | No | Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search. Default: [] |
person | array<string> | No | Exact case-sensitive GKG person names. Default: [] |
organization | array<string> | No | Exact case-sensitive GKG organization names. Default: [] |
location | array<string> | No | Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography. Default: [] |
location_country | array<string> | No | Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes. Default: [] |
location_adm1 | array<string> | No | Four-character GDELT/FIPS ADM1 codes. Default: [] |
outlet | array<string> | No | Exact source common names/domains, normalized to lowercase; not arbitrary URL matching. Default: [] |
source_language | array<string> | No | Three-letter GKG source-language codes, normalized to lowercase (eng for English). Default: [] |
source_country | array<string> | No | Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta. Default: [] |
tone_min | number | null | No | Inclusive GKG tone lower bound. |
tone_max | number | null | No | Inclusive GKG tone upper bound. |
limit | integer | No | Page size. Preserve this limit, range and filters when reusing next_cursor. Default: 25 |
cursor | string | null | No | Opaque data.next_cursor from the previous page; pass unchanged with identical range, filters and limit. |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 GKG monitoring-slot timestamp with timezone, not publication time. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 monitoring-slot timestamp with timezone. Backend enforces its current retained window without clipping.",
"format": "date-time",
"title": "End",
"type": "string"
},
"theme": {
"default": [],
"description": "Exact GKG V2 theme codes (A-Z, digits, underscore); OR within this list, AND with other filter families. No keyword search.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Theme",
"type": "array"
},
"person": {
"default": [],
"description": "Exact case-sensitive GKG person names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Person",
"type": "array"
},
"organization": {
"default": [],
"description": "Exact case-sensitive GKG organization names.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Organization",
"type": "array"
},
"location": {
"default": [],
"description": "Exact case-sensitive GKG location full names mentioned anywhere in matching articles; not keyword-proximity geography.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location",
"type": "array"
},
"location_country": {
"default": [],
"description": "Two-letter GDELT/FIPS mentioned-country codes, not necessarily ISO codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Country",
"type": "array"
},
"location_adm1": {
"default": [],
"description": "Four-character GDELT/FIPS ADM1 codes.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Location Adm1",
"type": "array"
},
"outlet": {
"default": [],
"description": "Exact source common names/domains, normalized to lowercase; not arbitrary URL matching.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Outlet",
"type": "array"
},
"source_language": {
"default": [],
"description": "Three-letter GKG source-language codes, normalized to lowercase (eng for English).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Language",
"type": "array"
},
"source_country": {
"default": [],
"description": "Two-letter mapped outlet-origin country codes. Unknown/ambiguous mappings are excluded; coverage is in meta.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Source Country",
"type": "array"
},
"tone_min": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone lower bound.",
"title": "Tone Min"
},
"tone_max": {
"anyOf": [
{
"maximum": 100,
"minimum": -100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive GKG tone upper bound.",
"title": "Tone Max"
},
"limit": {
"default": 25,
"description": "Page size. Preserve this limit, range and filters when reusing next_cursor.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"cursor": {
"anyOf": [
{
"maxLength": 1000,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Opaque data.next_cursor from the previous page; pass unchanged with identical range, filters and limit.",
"title": "Cursor"
}
},
"required": [
"start",
"end"
],
"title": "ArticlesParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_ArticleItem": {
"additionalProperties": true,
"properties": {
"observed_at": {
"title": "Observed At",
"type": "string"
},
"url": {
"minLength": 1,
"title": "Url",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"outlet": {
"title": "Outlet",
"type": "string"
},
"published_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Published At"
},
"source_language": {
"title": "Source Language",
"type": "string"
},
"source_country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Country Code"
},
"tone": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Tone"
}
},
"required": [
"observed_at",
"url",
"title",
"outlet",
"published_at",
"source_language",
"source_country_code",
"tone"
],
"title": "_ArticleItem",
"type": "object"
},
"_ArticlesData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_ArticleItem"
},
"maxItems": 100,
"title": "Items",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pass data.next_cursor unchanged as the next request's cursor, with identical filters, range, and limit. Null means no next page.",
"title": "Next Cursor"
},
"truncated": {
"description": "True exactly when data.next_cursor is non-null.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"next_cursor",
"truncated"
],
"title": "_ArticlesData",
"type": "object"
},
"_Coverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "False when listed upstream files are unavailable. Nonempty results can still be partial; ratios and tone averages may be biased in either direction.",
"title": "Complete",
"type": "boolean"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"gaps": {
"description": "At most 100 listed-but-unavailable stream/file entries, not a count of unique time slots.",
"items": {
"additionalProperties": true,
"type": "object"
},
"maxItems": 100,
"title": "Gaps",
"type": "array"
},
"gaps_truncated": {
"description": "True when more gaps exist than the bounded gaps list shows.",
"title": "Gaps Truncated",
"type": "boolean"
},
"buffered_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Pending files inside the backend's stream-specific ingest buffer; expected scheduling/publication lag. Omitted on older responses; never synthesized as zero.",
"title": "Buffered Files"
},
"unexpected_gap_files": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unavailable files outside the expected ingest buffer; distinguish these from buffered_files. Omitted on older responses; never synthesized as zero.",
"title": "Unexpected Gap Files"
},
"parser_warnings": {
"additionalProperties": {
"type": "integer"
},
"title": "Parser Warnings",
"type": "object"
}
},
"required": [
"complete",
"listed_files",
"available_files",
"gaps",
"gaps_truncated",
"parser_warnings"
],
"title": "_Coverage",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
},
"_Mapping": {
"additionalProperties": true,
"properties": {
"method": {
"title": "Method",
"type": "string"
},
"mapped_articles": {
"minimum": 0,
"title": "Mapped Articles",
"type": "integer"
},
"ambiguous_articles": {
"minimum": 0,
"title": "Ambiguous Articles",
"type": "integer"
},
"unknown_articles": {
"minimum": 0,
"title": "Unknown Articles",
"type": "integer"
},
"total_articles": {
"minimum": 0,
"title": "Total Articles",
"type": "integer"
},
"mapped_percent": {
"maximum": 100,
"minimum": 0,
"title": "Mapped Percent",
"type": "number"
}
},
"required": [
"method",
"mapped_articles",
"ambiguous_articles",
"unknown_articles",
"total_articles",
"mapped_percent"
],
"title": "_Mapping",
"type": "object"
},
"_QueryMeta": {
"additionalProperties": true,
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_Coverage"
},
"source_country_mapping": {
"$ref": "#/$defs/_Mapping"
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including article-level rather than keyword-proximate geography.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"serving_horizon",
"coverage",
"source_country_mapping",
"warnings"
],
"title": "_QueryMeta",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_QueryMeta"
},
"data": {
"$ref": "#/$defs/_ArticlesData"
}
},
"required": [
"meta",
"data"
],
"title": "ArticlesResult",
"type": "object"
} # list_events read
Rank GDELT CAMEO events by qualifying mentions, filtered by actor/action country and CAMEO code.
Full description
Rank GDELT events by qualifying mention rows, with coded actors and geography. Events are machine-coded CAMEO actor-action-actor records, not verified facts. Filter by action country (GDELT/FIPS two-letter), actor countries (CAMEO three-letter) or CAMEO root/event codes; at least one is required. Time is when mentions were observed, not when the event happened. min_confidence (default 50) is extraction confidence, not truth. Geography is role- qualified: action_location, actor1.location, actor2.location. There is no target location. Each item reports mention_rows, distinct articles and outlets, and the streams that mentioned it. Use get_event_mentions with event.global_event_id for attributed articles. meta.coverage covers all six GDELT inputs. meta.event_references is range-wide, not filter-specific: it counts all events mentioned in the range that have no event record (mostly older than the rolling window), so they cannot be matched to filters. toolkit_notices highlights partial coverage, those unmatched references and stale data. Single-shot, no automatic retry: callers may retry transient capacity errors after any reported Retry-After delay.
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range. |
end | string | Yes | Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window. |
min_confidence | integer | No | Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value. Default: 50 |
action_country | array<string> | No | Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia). Default: [] |
actor1_country | array<string> | No | Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS). Default: [] |
actor2_country | array<string> | No | Three-letter CAMEO country codes of Actor2. Default: [] |
event_root_code | array<string> | No | Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight). Default: [] |
event_code | array<string> | No | Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions). Default: [] |
limit | integer | No | Maximum ranked events. Truncation is reported; no pagination. Default: 25 |
Parameter schema (JSON)
{
"additionalProperties": false,
"properties": {
"start": {
"description": "Inclusive RFC3339 mention-observation slot timestamp with timezone. Use get_status for the retained range.",
"format": "date-time",
"title": "Start",
"type": "string"
},
"end": {
"description": "Exclusive RFC3339 mention-observation slot timestamp with timezone, within the backend's retained window.",
"format": "date-time",
"title": "End",
"type": "string"
},
"min_confidence": {
"default": 50,
"description": "Minimum GDELT extraction confidence (0-100) for a mention to count. It is machine-extraction confidence, not a truth score; 50 removes many low-confidence false codings. 0 also includes mentions with no confidence value.",
"maximum": 100,
"minimum": 0,
"title": "Min Confidence",
"type": "integer"
},
"action_country": {
"default": [],
"description": "Two-letter GDELT/FIPS country codes of the coded ACTION location (not ISO; e.g. IR Iran, MU Oman, UP Ukraine, RS Russia).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Action Country",
"type": "array"
},
"actor1_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor1 (e.g. IRN, USA, RUS).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor1 Country",
"type": "array"
},
"actor2_country": {
"default": [],
"description": "Three-letter CAMEO country codes of Actor2.",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Actor2 Country",
"type": "array"
},
"event_root_code": {
"default": [],
"description": "Two-digit CAMEO root codes (e.g. 14 protest, 18 assault, 19 fight).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Root Code",
"type": "array"
},
"event_code": {
"default": [],
"description": "Two- to four-digit CAMEO event codes (e.g. 163 impose embargo/boycott/sanctions).",
"items": {
"type": "string"
},
"maxItems": 10,
"title": "Event Code",
"type": "array"
},
"limit": {
"default": 25,
"description": "Maximum ranked events. Truncation is reported; no pagination.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"start",
"end"
],
"title": "EventListParams",
"type": "object"
}Result schema (JSON)
{
"$defs": {
"_EventActor": {
"additionalProperties": true,
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Code"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/_EventLocation"
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"name",
"country_code",
"location"
],
"title": "_EventActor",
"type": "object"
},
"_EventCoverage": {
"additionalProperties": true,
"properties": {
"complete": {
"description": "True only when all six feed/stream pairs are complete for the range. False means results are partial.",
"title": "Complete",
"type": "boolean"
},
"feeds": {
"description": "One entry per feed/stream pair (six today: GKG, Events, EventMentions x English, translated).",
"items": {
"$ref": "#/$defs/_EventFeedCoverage"
},
"maxItems": 30,
"minItems": 1,
"title": "Feeds",
"type": "array"
},
"event_id_conflicts": {
"description": "Event IDs recorded in both streams; their canonical record may not be the one a mention meant.",
"minimum": 0,
"title": "Event Id Conflicts",
"type": "integer"
}
},
"required": [
"complete",
"feeds",
"event_id_conflicts"
],
"title": "_EventCoverage",
"type": "object"
},
"_EventFeedCoverage": {
"additionalProperties": true,
"properties": {
"feed": {
"description": "gkg, events or event_mentions; new backend feeds are accepted.",
"title": "Feed",
"type": "string"
},
"stream": {
"title": "Stream",
"type": "string"
},
"listed_files": {
"minimum": 0,
"title": "Listed Files",
"type": "integer"
},
"available_files": {
"minimum": 0,
"title": "Available Files",
"type": "integer"
},
"failed_files": {
"minimum": 0,
"title": "Failed Files",
"type": "integer"
},
"pending_files": {
"minimum": 0,
"title": "Pending Files",
"type": "integer"
},
"buffered_files": {
"description": "Pending files still inside the stream's ingest buffer: expected lag, not a gap.",
"minimum": 0,
"title": "Buffered Files",
"type": "integer"
},
"slots_without_listing": {
"description": "Slots GKG lists that this event feed does not; upstream-absent or not yet discovered.",
"minimum": 0,
"title": "Slots Without Listing",
"type": "integer"
},
"complete": {
"title": "Complete",
"type": "boolean"
}
},
"required": [
"feed",
"stream",
"listed_files",
"available_files",
"failed_files",
"pending_files",
"buffered_files",
"slots_without_listing",
"complete"
],
"title": "_EventFeedCoverage",
"type": "object"
},
"_EventListData": {
"additionalProperties": true,
"properties": {
"items": {
"items": {
"$ref": "#/$defs/_EventListItem"
},
"maxItems": 100,
"title": "Items",
"type": "array"
},
"truncated": {
"description": "True when more events match than the requested limit; no pagination.",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"items",
"truncated"
],
"title": "_EventListData",
"type": "object"
},
"_EventListItem": {
"additionalProperties": true,
"properties": {
"event": {
"$ref": "#/$defs/_EventRecord"
},
"mentions": {
"$ref": "#/$defs/_EventMentionStats"
}
},
"required": [
"event",
"mentions"
],
"title": "_EventListItem",
"type": "object"
},
"_EventLocation": {
"additionalProperties": true,
"properties": {
"role": {
"enum": [
"action_location",
"actor1_location",
"actor2_location"
],
"title": "Role",
"type": "string"
},
"type": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Type"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Country Code"
},
"adm1_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Adm1 Code"
},
"latitude": {
"anyOf": [
{
"maximum": 90,
"minimum": -90,
"type": "number"
},
{
"type": "null"
}
],
"title": "Latitude"
},
"longitude": {
"anyOf": [
{
"maximum": 180,
"minimum": -180,
"type": "number"
},
{
"type": "null"
}
],
"title": "Longitude"
},
"feature_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Feature Id"
}
},
"required": [
"role",
"type",
"name",
"country_code",
"adm1_code",
"latitude",
"longitude",
"feature_id"
],
"title": "_EventLocation",
"type": "object"
},
"_EventMentionStats": {
"additionalProperties": true,
"properties": {
"mention_rows": {
"minimum": 0,
"title": "Mention Rows",
"type": "integer"
},
"articles": {
"minimum": 0,
"title": "Articles",
"type": "integer"
},
"outlets": {
"minimum": 0,
"title": "Outlets",
"type": "integer"
},
"max_confidence": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Confidence"
},
"first_mention_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Mention At"
},
"last_mention_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Mention At"
},
"mention_streams": {
"items": {
"type": "string"
},
"title": "Mention Streams",
"type": "array"
}
},
"required": [
"mention_rows",
"articles",
"outlets",
"max_confidence",
"first_mention_at",
"last_mention_at",
"mention_streams"
],
"title": "_EventMentionStats",
"type": "object"
},
"_EventRangeMeta": {
"additionalProperties": true,
"description": "Meta for list, timeline and geo results, which must carry the reference count.",
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
},
"generated_at": {
"title": "Generated At",
"type": "string"
},
"range": {
"additionalProperties": {
"type": "string"
},
"title": "Range",
"type": "object"
},
"time_basis": {
"const": "mention_observation",
"title": "Time Basis",
"type": "string"
},
"serving_horizon": {
"$ref": "#/$defs/_Horizon"
},
"coverage": {
"$ref": "#/$defs/_EventCoverage"
},
"event_references": {
"$ref": "#/$defs/_EventReferences",
"description": "Range-wide, not filter-specific: events mentioned in the range without an event record. Required for list, timeline and geo results."
},
"warnings": {
"description": "Unmodified backend warning codes and messages, including extraction-confidence and role-geography caveats.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Warnings",
"type": "array"
}
},
"required": [
"request_id",
"generated_at",
"range",
"time_basis",
"serving_horizon",
"coverage",
"event_references",
"warnings"
],
"title": "_EventRangeMeta",
"type": "object"
},
"_EventRecord": {
"additionalProperties": true,
"properties": {
"stream": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Stream in which GDELT recorded the event (english or translation); mentions may come from either stream.",
"title": "Stream"
},
"global_event_id": {
"minimum": 1,
"title": "Global Event Id",
"type": "integer"
},
"event_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Date"
},
"cameo": {
"additionalProperties": true,
"title": "Cameo",
"type": "object"
},
"goldstein_scale": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Goldstein Scale"
},
"average_tone": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Average Tone"
},
"actor1": {
"$ref": "#/$defs/_EventActor"
},
"actor2": {
"$ref": "#/$defs/_EventActor"
},
"action_location": {
"anyOf": [
{
"$ref": "#/$defs/_EventLocation"
},
{
"type": "null"
}
]
},
"source_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Url"
}
},
"required": [
"stream",
"global_event_id",
"event_date",
"cameo",
"goldstein_scale",
"average_tone",
"actor1",
"actor2",
"action_location",
"source_url"
],
"title": "_EventRecord",
"type": "object"
},
"_EventReferences": {
"additionalProperties": true,
"properties": {
"min_confidence": {
"title": "Min Confidence",
"type": "integer"
},
"referenced_events": {
"minimum": 0,
"title": "Referenced Events",
"type": "integer"
},
"unresolved_event_references": {
"description": "Range-wide (not filter-specific) count of mentioned events without an event record: older_than_window + missing_within_window.",
"minimum": 0,
"title": "Unresolved Event References",
"type": "integer"
},
"older_than_window": {
"description": "Events first recorded before the rolling Event window; mentioned but not included in event results.",
"minimum": 0,
"title": "Older Than Window",
"type": "integer"
},
"missing_within_window": {
"description": "Events recorded inside the window whose Events file is missing, failed, pending or not yet ingested.",
"minimum": 0,
"title": "Missing Within Window",
"type": "integer"
},
"unresolved_percent": {
"maximum": 100,
"minimum": 0,
"title": "Unresolved Percent",
"type": "number"
},
"cross_stream_references": {
"description": "Events mentioned from the other stream than the one that recorded them (normal; resolved by ID).",
"minimum": 0,
"title": "Cross Stream References",
"type": "integer"
},
"event_window_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Window Start"
}
},
"required": [
"min_confidence",
"referenced_events",
"unresolved_event_references",
"older_than_window",
"missing_within_window",
"unresolved_percent",
"cross_stream_references",
"event_window_start"
],
"title": "_EventReferences",
"type": "object"
},
"_Horizon": {
"additionalProperties": true,
"properties": {
"data_from": {
"title": "Data From",
"type": "string"
},
"data_through": {
"title": "Data Through",
"type": "string"
},
"latest_listed_through": {
"title": "Latest Listed Through",
"type": "string"
},
"serving_window_days": {
"minimum": 1,
"title": "Serving Window Days",
"type": "integer"
},
"stale": {
"description": "True when the newest queryable data is behind the backend's freshness threshold, including on successful historical queries.",
"title": "Stale",
"type": "boolean"
}
},
"required": [
"data_from",
"data_through",
"latest_listed_through",
"serving_window_days",
"stale"
],
"title": "_Horizon",
"type": "object"
}
},
"additionalProperties": true,
"properties": {
"toolkit_notices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Toolkit-added interpretation notices: empty results, incomplete ingestion, stale data, and for event tools range-wide mentioned events without an event record or a missing single-event record. Present only when relevant; backend message and metadata are never overwritten.",
"title": "Toolkit Notices"
},
"meta": {
"$ref": "#/$defs/_EventRangeMeta"
},
"data": {
"$ref": "#/$defs/_EventListData"
}
},
"required": [
"meta",
"data"
],
"title": "EventListResult",
"type": "object"
}