Get GDELT Coverage Breakdown
gdelt_get_coverage_breakdownBreak down news coverage volume over time by source language or source country, returning a multi-series time series (one series per language or country). Shows which countries or languages drove early vs. late coverage — useful for tracing how a story propagated geographically or across language communities. Returns the top 10 series ranked by the sum of their values and names every other series under otherSeriesLabels — pass any labels, ranked or not, as the series input to get only those series, complete. A response carries limit series (default 10, cap 75); when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Values are normalized: each point is the topic's share of that source's media output, not an absolute article count, so values from different sources do not add up to a share. Small media markets with concentrated coverage therefore rank above large markets with diverse output — a high value means the topic dominated that source's coverage, not that it published the most articles. Use breakdownBy "country" with the signal-detection chain to map geographic attention, or "language" to detect non-English media surges.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>",
"breakdownBy": "<breakdownBy>"
},
"name": "gdelt_get_coverage_breakdown"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum series per page (default 10, cap 75). Larger counts clamp with limitClamp; strict deployments reject them. | |
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes). | |
| offset | No | Zero-based series offset — into the ranked top 10, or into the series named in series. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page. | |
| series | No | Exact series labels to return instead of the ranked overview, e.g. ["Portuguese Volume Intensity", "Vietnamese Volume Intensity"]. Take them verbatim from otherSeriesLabels or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, in the order requested; a label that matches nothing is rejected rather than silently skipped. Omit to get the ranked overview. | |
| timespan | No | Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. | |
| smoothing | No | Trailing moving-average width in timesteps (0–30; 0 or 1 leaves values unsmoothed). Width N needs N source steps, omitting leading steps without a full window and potentially shifting peaks later. | |
| breakdownBy | Yes | Breakdown dimension: "language" for source language time series, "country" for source country time series. | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected. The window may predate the last 3 months. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected. The window may predate the last 3 months. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when the query matched no coverage in the window — how to broaden the query or extend the window — or, when this response is one page of several, which series it returned out of how many. When the server's local GKG mirror answered (source: gkg_mirror), why, how its figures differ from the DOC API's, and how many matching articles a country breakdown left out for having no known source country. Absent when the DOC API answered and every series fit in one response. | |
| source | No | Where this answer came from: doc_api, the GDELT DOC API, or gkg_mirror, the server's local mirror of GDELT's Global Knowledge Graph, which answers when the DOC API refuses the request or returns nothing. Present on every answer while the server runs a mirror; absent otherwise. | |
| attempts | No | Each source tried for this call, in order. Present only when the DOC API did not answer with data and the mirror was consulted. | |
| coverage | No | Present only when the mirror answered less than the requested window. Every count, share, and article in this response comes from answeredStart through answeredEnd; nothing outside it, or in a missing slot, was counted. | |
| topSeries | No | The ranked overview: the top 10 series by the sum of their values, those of this page in rank order. Omitted when the series input selects series instead. | |
| limitClamp | No | Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value. | |
| nextOffset | No | Offset of the next page, for the same inputs. Absent when this page reaches the last series. | |
| totalCount | No | Total number of series GDELT returned, before ranking into the top 10 or paging. | |
| breakdownBy | No | Breakdown dimension used for this response. | |
| endDatetime | No | Echoed end datetime when provided (YYYYMMDDHHMMSS). | |
| staleResponse | No | Present only when the refetch of this exact request was refused, failed, or came back empty, and the response is GDELT's stored answer from fetchedAt instead. It holds nothing published after fetchedAt; a relative timespan covers the window ending at fetchedAt, not now. Absent on a live answer. | |
| startDatetime | No | Echoed start datetime when provided (YYYYMMDDHHMMSS). | |
| dateResolution | No | Temporal resolution of data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. | |
| selectedSeries | No | Complete, untruncated time series for the labels requested via the series input — those of this page, in the order requested. Omitted when series was not supplied. | |
| otherSeriesLabels | No | Label of every series beyond the top 10, ranked by the sum of its values, on every overview page. Pass any of them to the series input to retrieve that series' complete data. Omitted when all series fit in the top 10, or when the series input selects series instead. |