GDELT

Search global news coverage indexed by GDELT

Searches global news coverage indexed by GDELT for the required query, which accepts quoted phrases, (a OR b), theme:, tone<N and domain:. Narrow with country, language, domain, and timespan or from and to (about the last 3 months are indexed). Returns up to maxrecords articles (default 75, max 250) with title, URL, domain, language, source country and seen_at.

get/gdelt/search

Request

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

Query parameters

querystring required

GDELT query string. Supports GDELT's own search operators: quoted phrases, (a OR b), theme:NAME, tone<N / tone>N, near20:\

countrystring

Convenience source-country filter, appended to the query as sourcecountry:VALUE. Accepts a GDELT-recognized country name (no spaces) or 2-letter FIPS code.

languagestring

Convenience source-language filter, appended to the query as sourcelang:VALUE. Accepts a GDELT-recognized language name or 3-letter code.

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; GDELT only indexes roughly the last 3 months.

tostring

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

sort'relevance' | 'datedesc' | 'dateasc' | 'tonedesc' | 'toneasc'

Result order.

maxrecordsinteger

Rows to return. GDELT's own hard cap is 250; there is no pagination cursor beyond it.

Headers

x-api-keystring required

API key required

Response

OK

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "articles": [
      {
        "domain": "example.com",
        "language": "English",
        "seen_at": "2026-08-19T23:00:00Z",
        "social_image_url": "https://www.example.com/images/social.jpg",
        "source_country": "United States",
        "title": "Climate report warns of rising sea levels",
        "url": "https://www.example.com/news/climate-report"
      }
    ],
    "count": 12,
    "fetched_at": "2026-08-20T10:00:00Z",
    "maxrecords": 75,
    "query": "climate change",
    "sort": "relevance",
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change"
  },
  "msg": "OK"
}

Changes

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