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 up to 10 series by total volume and aggregates the rest into an "Other" bucket, naming every series it folded in there under otherSeriesLabels — pass any of those labels back as the series input to get that series complete, ranked or not. Values are normalized: each point is the topic's share of media output, not an absolute article count. 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:. | |
| series | No | Exact series labels to additionally return in full, e.g. ["Portuguese", "Vietnamese"]. Take them verbatim from otherSeriesLabels (the series folded into "Other") or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, on top of the usual top-10 overview; a label that matches nothing is rejected rather than silently skipped. Omit to get the overview alone. | |
| timespan | No | Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. | |
| 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. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Recovery hint when no breakdown data was returned. Absent on successful responses. | |
| topSeries | No | Top 10 series by total coverage volume. | |
| totalCount | No | Total number of series returned before truncation to top 10. | |
| breakdownBy | No | Breakdown dimension used for this response. | |
| endDatetime | No | Echoed end datetime when provided (YYYYMMDDHHMMSS). | |
| startDatetime | No | Echoed start datetime when provided (YYYYMMDDHHMMSS). | |
| dateResolution | No | Temporal resolution of data points — 15min, hour, or day. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. | |
| selectedSeries | No | Complete, untruncated time series for each label requested via the series input, in the order requested. Omitted when series was not supplied. | |
| otherAggregated | No | Combined time series for all series beyond the top 10. Omitted when all series fit. | |
| otherSeriesLabels | No | Label of every series folded into otherAggregated, ranked by total volume — the identities the "Other" bucket would otherwise dissolve. Pass any of them to the series input to retrieve that series' complete data. Omitted when all series fit in the top 10. |