GDELT

Coverage volume or tone over time for a GDELT query

Returns how coverage of the required GDELT query changes over time, as dated points. metric picks volume (the default, share of monitored articles), volume_raw (matching article count), tone (average sentiment), or lang and country for one series per language or country. Filter with country, language, domain, timespan or from and to; smooth runs 0 to 30 (default 0).

get/gdelt/timeline

Request

  • Base URL: https://api.crawlora.net/api/v1
  • URL: https://api.crawlora.net/api/v1/gdelt/timeline
  • Auth: API key in header x-api-key

Query parameters

querystring required

GDELT query string. Same syntax as gdelt-search's query.

metric'volume' | 'volume_raw' | 'tone' | 'lang' | 'country'

Timeline metric. lang and country return one series per language/country instead of one aggregate series.

countrystring

Convenience source-country filter, appended to the query as sourcecountry:VALUE.

languagestring

Convenience source-language filter, appended to the query as sourcelang:VALUE.

domainstring

Convenience domain filter, appended to the query as domain:VALUE.

timespanstring

Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.

fromstring

Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.

tostring

End of an absolute time window. Same formats as from.

smoothinteger

Moving-window smoothing applied to the timeline, in steps. 0 disables smoothing.

Headers

x-api-keystring required

API key required

Response

OK

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "fetched_at": "2026-08-20T10:00:00Z",
    "metric": "volume",
    "query": "climate change",
    "series": [
      {
        "points": [
          {
            "date": "2026-08-19T00:00:00Z",
            "value": 1.42
          }
        ],
        "series": "climate change"
      }
    ],
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change"
  },
  "msg": "OK"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.