Get GDELT Tone Distribution
gdelt_get_tone_distributionRead-only
Get the tonal distribution of articles matching a query as a histogram (bins approximately -30 to +30). Unlike a single average tone score, the histogram reveals whether coverage is uniformly negative, bimodal (some articles extremely positive and some extremely negative), or clustered near neutral. Each bin carries its first 3 representative article links and referenceCount, how many GDELT returned; name bins in the bins input to get only those bins, each with every link. A response carries limit bins (default 10, cap 400); when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Distinct from gdelt_get_coverage_timeline (mode: tone) — this is a snapshot distribution across all matching articles, not a time series. Use gdelt_get_coverage_timeline with mode "tone" to see how sentiment shifted over time.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "gdelt_get_tone_distribution"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bins | No | Tone bins to return alone, e.g. [-7, 4]. Take them from histogram[].bin in a prior response, or from the list an unknown_bin error prints. The response then carries only these bins, in histogram order, each with every representative article link instead of the first 3. A value matching no bin is rejected rather than silently ignored. | |
| limit | No | Maximum bins per page (default 10, cap 400). Larger counts clamp with limitClamp; strict deployments reject them. | |
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes). | |
| offset | No | Zero-based bin offset — into the histogram, or into the bins named in bins. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page. | |
| timespan | No | Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected. The window may predate the last 3 months. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected. The window may predate the last 3 months. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when no articles matched in the window — how to broaden the query or extend the window — or, when this response is one page of several, which bins it returned out of how many. When the server's local GKG mirror answered (source: gkg_mirror), why, and how its figures differ from the DOC API's. Absent when the DOC API answered and the whole histogram fit in one response. | |
| source | No | Where this answer came from: doc_api, the GDELT DOC API, or gkg_mirror, the server's local mirror of GDELT's Global Knowledge Graph, which answers when the DOC API refuses the request or returns nothing. Present on every answer while the server runs a mirror; absent otherwise. | |
| summary | No | Summary statistics derived from the whole histogram, not this page. Each value is omitted when the histogram cannot support it — all of them on an empty result. | |
| attempts | No | Each source tried for this call, in order. Present only when the DOC API did not answer with data and the mirror was consulted. | |
| coverage | No | Present only when the mirror answered less than the requested window. Every count, share, and article in this response comes from answeredStart through answeredEnd; nothing outside it, or in a missing slot, was counted. | |
| histogram | No | The bins of this page, sorted from most negative to most positive — the whole histogram when it fits. | |
| limitClamp | No | Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value. | |
| nextOffset | No | Offset of the next page, for the same inputs. Absent when this page reaches the last bin. | |
| totalCount | No | Total number of articles across all histogram bins, not only this page. | |
| endDatetime | No | Echoed end datetime when provided (YYYYMMDDHHMMSS). | |
| staleResponse | No | Present only when the refetch of this exact request was refused, failed, or came back empty, and the response is GDELT's stored answer from fetchedAt instead. It holds nothing published after fetchedAt; a relative timespan covers the window ending at fetchedAt, not now. Absent on a live answer. | |
| startDatetime | No | Echoed start datetime when provided (YYYYMMDDHHMMSS). | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. |