Docs menu

GDELT API endpoint

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.

GETapiKey0 credits/requestGDELTgdelt.toneChartResponseDoc/gdelt/tonechart

Endpoint facts

Method: GET
API path: /gdelt/tonechart
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.toneChartResponseDoc

GDELT News Monitoring API Try GDELT Tone Chart API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Same syntax as gdelt-search's query.
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.

Notable 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 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.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tonechart?query=climate+change
Items in bins: 40
Fields filled in every checked item: 2
Fields empty in some or all items: 1

Field	Filled in, of 40 checked	Values in the sample
bin	40	-23 to 16, median -4
count	40	0 to 16,448, median 108
top_articles	36	median 10 entries

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.	climate change
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

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"
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.toneChartResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.ToneChartResponse	No
data.bins	array	No
data.bins[].bin	integer	No	-5
data.bins[].count	integer	No	12
data.bins[].top_articles	array	No
data.bins[].top_articles[].title	string	No	Climate report warns of rising sea levels
data.bins[].top_articles[].url	string	No	https://www.example.com/news/climate-report
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	climate change
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=tonechart&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More GDELT endpoint docs GDELT News Monitoring API GDELT Context Search API documentation GDELT Search API documentation GDELT Timeline API documentation GDELT Television Concept Entities API documentation GDELT Television Search API documentation GDELT Television Show Chart API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Tone Chart API

GETapiKey0 credits/requestGDELTgdelt.toneChartResponseDoc/gdelt/tonechart

Endpoint facts

Method: GET
API path: /gdelt/tonechart
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.toneChartResponseDoc

GDELT News Monitoring API Try GDELT Tone Chart API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Same syntax as gdelt-search's query.
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
to (optional) — end of an absolute time window. Same formats as from.

Notable 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 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.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tonechart?query=climate+change
Items in bins: 40
Fields filled in every checked item: 2
Fields empty in some or all items: 1

Field	Filled in, of 40 checked	Values in the sample
bin	40	-23 to 16, median -4
count	40	0 to 16,448, median 108
top_articles	36	median 10 entries

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Same syntax as gdelt-search's query.	climate change
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

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"
          }
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.toneChartResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.ToneChartResponse	No
data.bins	array	No
data.bins[].bin	integer	No	-5
data.bins[].count	integer	No	12
data.bins[].top_articles	array	No
data.bins[].top_articles[].title	string	No	Climate report warns of rising sea levels
data.bins[].top_articles[].url	string	No	https://www.example.com/news/climate-report
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	climate change
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=tonechart&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tonechart?query=climate+change&country=us&language=en" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

GDELT Tone Chart API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Tone Chart API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related