Endpoint Playground

Try the GDELT Tone Chart API

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.

What a live request returned

14 Oct 2026: 40 bins; 2 fields had a value in every checked item and 1 varied between items.

Observed request: GET /gdelt/tonechart?query=climate+change
Fields with a value in every checked item: bin, count

Sample value profiles: bin: -23 to 16, median -4; top_articles: median 10 entries; count: 0 to 16,448, median 108.

Request: GET /gdelt/tonechart
Cost: 0 credits/request
Auth: apiKey

GDELT Tone Chart API documentation GDELT platform page Pricing

Prefilled cURL

curl 'https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change' \
  -H "x-api-key: $CRAWLORA_API_KEY"

Request parameters

Parameter	Type	Required	Prefilled value	Description
query	string	Yes	climate change	GDELT query string. Same syntax as gdelt-search's query.
country	string	No		Convenience source-country filter, appended to the query as sourcecountry:VALUE.
language	string	No		Convenience source-language filter, appended to the query as sourcelang:VALUE.
domain	string	No		Convenience domain filter, appended to the query as domain:VALUE.
timespan	string	No		Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from	string	No		Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to	string	No		End of an absolute time window. Same formats as from.

Example JSON response

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

More GDELT endpoints

Sentence-level co-occurrence search across recent GDELT coverage Search global news coverage indexed by GDELT Coverage volume or tone over time for a GDELT query List GDELT Television 2.0 AI concept entities Search US television news coverage (transcripts, captions, OCR, visual labels)Top US television shows by coverage share for a query Compare US television news coverage across stations List GDELT Television 2.0 AI stations Airtime volume over time for US television news coverage List GDELT Television 2.0 AI visual entities Word cloud for US television news coverage

The sample response, schema and code snippets below work without an account. Sending a live request needs an API key.

Set up API key Endpoint docs

Endpoint

Choose one catalog endpoint for this request.

1 shown

Group

Method

Auth

Endpoint

GETapiKey0 credits/requestgdelt.toneChartResponseDocGDELT

GET /gdelt/tonechart

Sentiment histogram for a GDELT query

Response behavior

- `bins` is ordered by GDELT's own upstream order (not guaranteed sorted by `bin`); a bin with zero matching articles for that tone value is simply absent from the array, not returned with `count: 0`. - `top_articles` is a short, GDELT-selected sample per bin, not an exhaustive list — use [gdelt-search](gdelt-search.md) with a `tone<N`/ `tone>N` query clause for the full article list at a given sentiment range. - `source_url` is the exact upstream GDELT DOC API URL used for the call. - A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.

API key required. Paste a full key or rotate one from the API Keys page.

Set up API key

View docs

API key

API key required for live requests. Your key is only used to send requests from this Playground.

not configured

Active Playground key: not configured

Manage API keys in Console

Required query parameters

query

requiredstring

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

Add an API key to send a live request.

If an active API key is configured, Copy cURL includes it. Share links never include API keys.

View docs

Sample responseGET

Shown before your first request. Add an API key and send a request to see the live response, status, latency, and headers.

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

Endpoint Playground

Try the GDELT Tone Chart API

What a live request returned

14 Oct 2026: 40 bins; 2 fields had a value in every checked item and 1 varied between items.

Observed request: GET /gdelt/tonechart?query=climate+change
Fields with a value in every checked item: bin, count

Sample value profiles: bin: -23 to 16, median -4; top_articles: median 10 entries; count: 0 to 16,448, median 108.

Request: GET /gdelt/tonechart
Cost: 0 credits/request
Auth: apiKey

GDELT Tone Chart API documentation GDELT platform page Pricing

Prefilled cURL

curl 'https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change' \
  -H "x-api-key: $CRAWLORA_API_KEY"

Request parameters

Parameter	Type	Required	Prefilled value	Description
query	string	Yes	climate change	GDELT query string. Same syntax as gdelt-search's query.
country	string	No		Convenience source-country filter, appended to the query as sourcecountry:VALUE.
language	string	No		Convenience source-language filter, appended to the query as sourcelang:VALUE.
domain	string	No		Convenience domain filter, appended to the query as domain:VALUE.
timespan	string	No		Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from	string	No		Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to	string	No		End of an absolute time window. Same formats as from.

Example JSON response

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

More GDELT endpoints

The sample response, schema and code snippets below work without an account. Sending a live request needs an API key.

Set up API key Endpoint docs

Endpoint

Choose one catalog endpoint for this request.

1 shown

Group

Method

Auth

Endpoint

GETapiKey0 credits/requestgdelt.toneChartResponseDocGDELT

GET /gdelt/tonechart

Sentiment histogram for a GDELT query

Response behavior

API key required. Paste a full key or rotate one from the API Keys page.

Set up API key

View docs

API key

API key required for live requests. Your key is only used to send requests from this Playground.

not configured

Active Playground key: not configured

Manage API keys in Console

Required query parameters

query

requiredstring

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

Add an API key to send a live request.

If an active API key is configured, Copy cURL includes it. Share links never include API keys.

View docs

Sample responseGET

Shown before your first request. Add an API key and send a request to see the live response, status, latency, and headers.

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