Search GDELT GKG Themes
gdelt_search_themesFind GDELT Global Knowledge Graph (GKG) theme identifiers for the theme: operator that gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown accept in query. Searches the identifiers in the GDELT GKG theme lookup, which carries no labels or descriptions: every query word must begin one of the _-separated parts of an identifier or run across consecutive parts, or all the words joined must, so "drought" finds NATURAL_DISASTER_DROUGHT, "cyberattack" finds CYBER_ATTACK, "plant disease" finds TAX_PLANTDISEASE, and "wb water" narrows to World Bank water themes. There is no stemming or synonym matching — "displacement" does not reach DISPLACED — except one fallback: when nothing matches, the search retries once with a trailing s dropped from each word of four or more letters, and says so. Matches rank an exact identifier first, then by the count the lookup lists — a static prevalence figure, not a live article total — and each carries a paste-ready operator such as theme:TAX_DISEASE_OUTBREAK. Page with offset and limit (up to 100 matches per page; a larger limit runs at 100).
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_search_themes"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matches returned in this response. Values above 100 run at 100 with a limitClamp disclosure when clamping is enabled. | |
| query | Yes | Words to find in theme identifiers (e.g. "drought", "cyber attack", "refugee"), a family prefix with a word ("wb water", "crisislex"), or a whole identifier to confirm it is listed ("TAX_DISEASE_OUTBREAK"). Case-insensitive; a leading theme: is ignored; every word must match, or all the words joined must ("plant disease" matches TAX_PLANTDISEASE). Must contain at least one letter or digit. | |
| offset | No | Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| limit | No | Maximum matches this page holds — the requested limit, or 100 when a larger one was clamped. | |
| notice | No | Search outcome: that the plural fallback supplied the matches and which words it tried, or, when nothing matched, how to retry. Absent when the query as given matched. | |
| offset | No | Zero-based offset of this page. | |
| matches | No | Matches on this page: an exact identifier match first, then by count descending, then by identifier. | |
| 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 for the next page with the same query. Absent when this is the final page. | |
| totalCount | No | Total themes matching the query — the same figure as totalMatches. | |
| totalMatches | No | Total themes matching the query, across all pages. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. |