Get GDELT Coverage Timeline
gdelt_get_coverage_timelineRetrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. Use mode "volume" for normalized coverage intensity (% of all global coverage per timestep). Use mode "volume_with_articles" for the same signal plus the top articles that drove each spike — this is the primary signal-detection mode: a single call reveals both the spike and its cause, avoiding a follow-up gdelt_search_articles call. Use mode "tone" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). Date resolution is inferred from returned intervals: 15 minutes or hours for short windows, days for longer ones. In volume_with_articles mode the text surface shows the first 3 article links per timestep next to that timestep's true article count; name a timestep's date in points to render its full list. Note: DOC API covers only the last 3 months.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Timeline mode: "volume" returns normalized coverage % per timestep, "volume_with_articles" returns volume plus top articles per spike (best for signal detection), "tone" returns average sentiment score per timestep. | volume |
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:, tone<. | |
| points | No | Timestep dates whose complete article list should be rendered in the text surface, e.g. ["2024-01-05T12:00:00Z"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored. | |
| 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 | Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics. | |
| 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 |
|---|---|---|---|
| mode | No | Timeline mode used for this response. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Recovery hint when no timeline data was returned. Absent on successful responses. | |
| series | No | One or more time series (typically one for volume/tone, one per label for breakdowns). | |
| totalCount | No | Total number of data points across all series. | |
| endDatetime | No | Echoed end datetime when provided (YYYYMMDDHHMMSS). | |
| startDatetime | No | Echoed start datetime when provided (YYYYMMDDHHMMSS). | |
| dateResolution | No | Temporal resolution of the data points — 15min, hour, or day. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. | |
| expandedPoints | No | Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way. |