GDELT

Sentiment histogram for a GDELT query

Returns a sentiment histogram for the required GDELT query: one bin per integer tone value, each with an article count and a short sample of top articles with title and URL. Filter with country, language, domain, and timespan or from and to. A tone value with no matching articles is absent rather than returned with a zero count.

get/gdelt/tonechart

Request

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

Query parameters

querystring required

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

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.

Headers

x-api-keystring required

API key required

Response

OK

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "bins": [
      {
        "bin": -5,
        "count": 12,
        "top_articles": [
          {
            "title": "Climate report warns of rising sea levels",
            "url": "https://www.example.com/news/climate-report"
          }
        ]
      }
    ],
    "fetched_at": "2026-08-20T10:00:00Z",
    "query": "climate change",
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=tonechart&query=climate+change"
  },
  "msg": "OK"
}

Changes

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