Server definition
- Hash
- sha256:562ebaa9405ff9572cd33682b4b3f952f8d0536ce5ecd13890ab5dcea6d89284
- What it is
- What a remote MCP server returned when asked what it offers: 9 tools
The blob, as servednamed by its sha256
{
"instructions": "GDELT MCP Server — global news and TV transcript analysis.\n- gdelt_search_articles: full-text news search (last 3 months, 65+ languages)\n- gdelt_get_coverage_timeline: when did coverage spike? (use mode volume_with_articles for signal detection)\n- gdelt_get_tone_distribution: emotional distribution of coverage (histogram)\n- gdelt_get_coverage_breakdown: which countries/languages drove coverage?\n- gdelt_search_themes: find GKG theme identifiers for the theme: operator in DOC tool queries\n- gdelt_search_tv: US TV transcript search (2009–Oct 2024, 150+ stations)\n- gdelt_get_tv_clips: read actual TV transcript excerpts with archive links\n- gdelt_get_tv_context: vocabulary framing a topic on television\n- gdelt_list_tv_stations: verify station IDs and active date ranges before TV queries (filter by stations, network, or market)\nRate limit: 1 request per 5 seconds across the DOC and TV tools — multi-step workflows take 15+ seconds. gdelt_search_themes reads a separate lookup file and does not queue behind that limit.",
"tools": [
{
"description": "Break down news coverage volume over time by source language or source country, returning a multi-series time series (one series per language or country). Shows which countries or languages drove early vs. late coverage — useful for tracing how a story propagated geographically or across language communities. Returns up to 10 series by total volume and aggregates the rest into an \"Other\" bucket, naming every series it folded in there under otherSeriesLabels — pass any of those labels back as the series input to get that series complete, ranked or not. Values are normalized: each point is the topic's share of media output, not an absolute article count. Small media markets with concentrated coverage therefore rank above large markets with diverse output — a high value means the topic dominated that source's coverage, not that it published the most articles. Use breakdownBy \"country\" with the signal-detection chain to map geographic attention, or \"language\" to detect non-English media surges.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"breakdownBy": {
"description": "Breakdown dimension: \"language\" for source language time series, \"country\" for source country time series.",
"enum": [
"language",
"country"
],
"type": "string"
},
"endDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"query": {
"description": "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).",
"minLength": 1,
"type": "string"
},
"series": {
"description": "Exact series labels to additionally return in full, e.g. [\"Portuguese\", \"Vietnamese\"]. Take them verbatim from otherSeriesLabels (the series folded into \"Other\") or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, on top of the usual top-10 overview; a label that matches nothing is rejected rather than silently skipped. Omit to get the overview alone.",
"items": {
"type": "string"
},
"type": "array"
},
"startDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"timespan": {
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months.",
"type": "string"
}
},
"required": [
"query",
"breakdownBy"
],
"type": "object"
},
"name": "gdelt_get_coverage_breakdown",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"topSeries",
"effectiveQuery",
"breakdownBy",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"breakdownBy": {
"description": "Breakdown dimension used for this response.",
"enum": [
"language",
"country"
],
"type": "string"
},
"dateResolution": {
"description": "Temporal resolution of data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back.",
"enum": [
"15min",
"hour",
"day"
],
"type": "string"
},
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"endDatetime": {
"description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_series`: A label passed in the series input matches no series in a non-empty breakdown. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_series",
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when breakdown data was returned.",
"type": "string"
},
"otherAggregated": {
"description": "Combined time series for all series beyond the top 10. Omitted when all series fit.",
"items": {
"additionalProperties": false,
"description": "A single aggregated data point for the \"Other\" bucket.",
"properties": {
"date": {
"description": "Timestep in ISO 8601 format.",
"type": "string"
},
"value": {
"description": "Aggregated normalized coverage volume for all remaining series — a share of media output, not an absolute article count.",
"type": "number"
}
},
"required": [
"date",
"value"
],
"type": "object"
},
"type": "array"
},
"otherSeriesLabels": {
"description": "Label of every series folded into otherAggregated, ranked by total volume — the identities the \"Other\" bucket would otherwise dissolve. Pass any of them to the series input to retrieve that series' complete data. Omitted when all series fit in the top 10.",
"items": {
"type": "string"
},
"type": "array"
},
"selectedSeries": {
"description": "Complete, untruncated time series for each label requested via the series input, in the order requested. Omitted when series was not supplied.",
"items": {
"additionalProperties": false,
"description": "A single language or country coverage series.",
"properties": {
"data": {
"description": "Time-ordered data points for this series.",
"items": {
"additionalProperties": false,
"description": "A single data point for this series.",
"properties": {
"date": {
"description": "Timestep in ISO 8601 format.",
"type": "string"
},
"value": {
"description": "Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count.",
"type": "number"
}
},
"required": [
"date",
"value"
],
"type": "object"
},
"type": "array"
},
"label": {
"description": "Series label (language name or country name).",
"type": "string"
}
},
"required": [
"label",
"data"
],
"type": "object"
},
"type": "array"
},
"startDatetime": {
"description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"topSeries": {
"description": "Top 10 series by total coverage volume.",
"items": {
"additionalProperties": false,
"description": "A single language or country coverage series.",
"properties": {
"data": {
"description": "Time-ordered data points for this series.",
"items": {
"additionalProperties": false,
"description": "A single data point for this series.",
"properties": {
"date": {
"description": "Timestep in ISO 8601 format.",
"type": "string"
},
"value": {
"description": "Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count.",
"type": "number"
}
},
"required": [
"date",
"value"
],
"type": "object"
},
"type": "array"
},
"label": {
"description": "Series label (language name or country name).",
"type": "string"
}
},
"required": [
"label",
"data"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of series returned before truncation to top 10.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Retrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. Use mode \"volume\" for normalized coverage intensity (% of all global coverage per timestep). Use mode \"volume_with_articles\" for the same signal plus the top articles that drove each spike — this is the primary signal-detection mode: a single call reveals both the spike and its cause, avoiding a follow-up gdelt_search_articles call. Use mode \"tone\" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). Date resolution is inferred from returned intervals: 15 minutes or hours for short windows, days for longer ones. In volume_with_articles mode the text surface shows the first 3 article links per timestep next to that timestep's true article count; name a timestep's date in points to render its full list. Note: DOC API covers only the last 3 months.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"mode": {
"default": "volume",
"description": "Timeline mode: \"volume\" returns normalized coverage % per timestep, \"volume_with_articles\" returns volume plus top articles per spike (best for signal detection), \"tone\" returns average sentiment score per timestep.",
"enum": [
"volume",
"volume_with_articles",
"tone"
],
"type": "string"
},
"points": {
"description": "Timestep dates whose complete article list should be rendered in the text surface, e.g. [\"2024-01-05T12:00:00Z\"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored.",
"items": {
"type": "string"
},
"type": "array"
},
"query": {
"description": "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), tone<.",
"minLength": 1,
"type": "string"
},
"smoothing": {
"description": "Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics.",
"maximum": 5,
"minimum": 0,
"type": "integer"
},
"startDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"timespan": {
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_get_coverage_timeline",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"series",
"effectiveQuery",
"mode",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dateResolution": {
"description": "Temporal resolution of the data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back.",
"enum": [
"15min",
"hour",
"day"
],
"type": "string"
},
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"endDatetime": {
"description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_point`: A date passed in the points input matches no timestep in a non-empty timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_point",
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"expandedPoints": {
"description": "Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way.",
"items": {
"type": "string"
},
"type": "array"
},
"mode": {
"description": "Timeline mode used for this response.",
"enum": [
"volume",
"volume_with_articles",
"tone"
],
"type": "string"
},
"notice": {
"description": "Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when timeline data was returned.",
"type": "string"
},
"series": {
"description": "One or more time series (typically one for volume/tone, one per label for breakdowns).",
"items": {
"additionalProperties": false,
"description": "A single time series with a label and data points.",
"properties": {
"data": {
"description": "Time-ordered data points for this series.",
"items": {
"additionalProperties": false,
"description": "A single time-series data point.",
"properties": {
"articles": {
"description": "Top articles driving coverage at this timestep. Present only in volume_with_articles mode.",
"items": {
"additionalProperties": false,
"description": "An article linked to this spike.",
"properties": {
"title": {
"description": "Article title.",
"type": "string"
},
"url": {
"description": "Article URL.",
"type": "string"
}
},
"required": [
"url",
"title"
],
"type": "object"
},
"type": "array"
},
"date": {
"description": "Timestep in ISO 8601 format.",
"type": "string"
},
"value": {
"description": "Normalized coverage % (volume mode) or average tone score (tone mode). Tone range is approximately -100 to +100.",
"type": "number"
}
},
"required": [
"date",
"value"
],
"type": "object"
},
"type": "array"
},
"label": {
"description": "Series label (e.g. \"Volume Intensity\" or \"Average Tone\").",
"type": "string"
}
},
"required": [
"label",
"data"
],
"type": "object"
},
"type": "array"
},
"startDatetime": {
"description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"totalCount": {
"description": "Total number of data points across all series.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "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 includes representative article URLs. 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"query": {
"description": "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).",
"minLength": 1,
"type": "string"
},
"startDatetime": {
"description": "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.",
"pattern": "^\\d{14}$",
"type": "string"
},
"timespan": {
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_get_tone_distribution",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"histogram",
"summary",
"effectiveQuery",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"endDatetime": {
"description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"histogram": {
"description": "Tone histogram sorted from most negative to most positive bin.",
"items": {
"additionalProperties": false,
"description": "A single tone histogram bin with article count and representative articles.",
"properties": {
"articles": {
"description": "Representative articles in this tone bin.",
"items": {
"additionalProperties": false,
"description": "A representative article for this tone bin.",
"properties": {
"title": {
"description": "Article title.",
"type": "string"
},
"url": {
"description": "Article URL.",
"type": "string"
}
},
"required": [
"url",
"title"
],
"type": "object"
},
"type": "array"
},
"bin": {
"description": "Tone bin integer (typically -30 to +30; 0 is neutral).",
"type": "number"
},
"count": {
"description": "Number of articles in this bin.",
"type": "number"
}
},
"required": [
"bin",
"count",
"articles"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance when no articles matched in the window — how to broaden the query or extend the window. Absent when tone data was returned.",
"type": "string"
},
"startDatetime": {
"description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
"type": "string"
},
"summary": {
"additionalProperties": false,
"description": "Summary statistics derived from the histogram. Each value is omitted when the histogram cannot support it — all of them on an empty result.",
"properties": {
"neutralPct": {
"description": "Percentage of articles in the near-neutral range (bins -2 to +2). Omitted when the histogram counts no articles.",
"type": "number"
},
"peakNegativeBin": {
"description": "Tone bin with the highest count among negative bins (bin < 0). Omitted when no negative bin was returned.",
"type": "number"
},
"peakPositiveBin": {
"description": "Tone bin with the highest count among positive bins (bin > 0). Omitted when no positive bin was returned.",
"type": "number"
}
},
"type": "object"
},
"totalCount": {
"description": "Total number of articles across all histogram bins.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Retrieve the top matching TV news clips for a query from the Internet Archive's Television News Archive: fetches up to 3,000 and returns as many as fit a 48,000-byte response — the rest are counted in withheldCount, with a continuation to reach them. Each clip includes show name, station, air timestamp, a 15-second transcript excerpt, and a direct link to view the full one-minute clip. Use after gdelt_search_tv to read the actual transcript content driving a coverage spike. GDELT answers TV windows in whole clock hours; clips it returns from outside an explicit startDatetime/endDatetime window are dropped, and continuing a cut response at maxRecords 3000 leaves room for them. 3,000 is a hard per-call ceiling and GDELT offers no cursor: when a query fills it or a response comes back cut, re-query narrower startDatetime/endDatetime windows — the response hands back the exact windows to use. Archive coverage spans 2009–October 2024.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endDatetime": {
"description": "End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"maxRecords": {
"default": 50,
"description": "Maximum number of clips to fetch (1–3000); the response carries as many of them as fit its 48,000-byte budget. 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead.",
"maximum": 3000,
"minimum": 1,
"type": "integer"
},
"query": {
"description": "Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:\"National\", show:\"Anderson Cooper\", context:\"vaccine\".",
"minLength": 1,
"type": "string"
},
"sort": {
"default": "relevance",
"description": "Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first).",
"enum": [
"relevance",
"dateDesc",
"dateAsc"
],
"type": "string"
},
"startDatetime": {
"description": "Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"stations": {
"description": "Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid IDs.",
"items": {
"type": "string"
},
"type": "array"
},
"timespan": {
"description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_get_tv_clips",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"clips",
"effectiveQuery",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"clips": {
"description": "Matching TV clips sorted per the sort parameter.",
"items": {
"additionalProperties": false,
"description": "A single TV news clip with transcript excerpt and archive link.",
"properties": {
"archiveUrl": {
"description": "Internet Archive URL to view the full 1-minute clip.",
"type": "string"
},
"date": {
"description": "Air datetime in ISO 8601 format.",
"type": "string"
},
"show": {
"description": "Show name (e.g. \"Anderson Cooper 360\").",
"type": "string"
},
"snippet": {
"description": "15-second transcript excerpt surrounding the match.",
"type": "string"
},
"station": {
"description": "Station ID (e.g. \"CNN\").",
"type": "string"
},
"thumbnail": {
"description": "Clip thumbnail URL when provided by the archive.",
"type": "string"
}
},
"required": [
"show",
"station",
"date",
"snippet",
"archiveUrl"
],
"type": "object"
},
"type": "array"
},
"continuationWindows": {
"description": "Windows to re-run this query against, one at a time, when more clips are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned clip, reaching back to the second it aired, so clips from that second come back again — de-duplicate by archiveUrl — or, when resuming there cannot reach a new clip, one window skipping past that second. Otherwise — maxRecords at its 3000 ceiling, or a relevance cut — the queried window split in two, on a clock hour when one falls inside it; the halves share no second. Absent when no window is known, or none would reach further.",
"items": {
"additionalProperties": false,
"description": "One window to re-query with the same query string.",
"properties": {
"endDatetime": {
"description": "End of this window in GDELT format YYYYMMDDHHMMSS.",
"type": "string"
},
"startDatetime": {
"description": "Start of this window in GDELT format YYYYMMDDHHMMSS.",
"type": "string"
}
},
"required": [
"startDatetime",
"endDatetime"
],
"type": "object"
},
"type": "array"
},
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to target the 2009–October 2024 archive or verify station IDs. When GDELT returned clips aired outside the requested window (it answers whole clock hours), how many were dropped. When the response was cut to its 48,000-byte budget, how many clips it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more clips may exist — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget.",
"type": "string"
},
"totalCount": {
"description": "Number of clips returned.",
"type": "number"
},
"withheldCount": {
"description": "In-window clips GDELT returned that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting clips dropped for falling outside the window. Absent when every in-window clip fit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Get the top co-occurring words and phrases from TV news clips matching a query — the vocabulary framing a topic on television. Returns the most frequent non-stopword terms from matching clips, with relative frequency scores (0–100, where 100 = the query term itself). Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms. TV data spans 2009–October 2024.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endDatetime": {
"description": "End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"query": {
"description": "Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:\"National\", show:\"Anderson Cooper\", context:\"vaccine\".",
"minLength": 1,
"type": "string"
},
"startDatetime": {
"description": "Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected. TV data spans 2009–October 2024.",
"pattern": "^\\d{14}$",
"type": "string"
},
"stations": {
"description": "Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid IDs.",
"items": {
"type": "string"
},
"type": "array"
},
"timespan": {
"description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_get_tv_context",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"words",
"effectiveQuery"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when no clips matched, so there is no vocabulary to report — the resolved timespan window, the October 2024 archive cutoff, and how to broaden the query or check station coverage. Absent when terms were returned.",
"type": "string"
},
"totalCount": {
"description": "Number of clips from which co-occurrences were computed. Absent when the upstream API does not return a clip count.",
"type": "number"
},
"words": {
"description": "Co-occurring terms sorted by score descending.",
"items": {
"additionalProperties": false,
"description": "A co-occurring term with its relative frequency score.",
"properties": {
"label": {
"description": "Co-occurring word or phrase.",
"type": "string"
},
"score": {
"description": "Relative frequency score (0–100). The query term itself scores 100; other terms are proportional to their co-occurrence frequency.",
"type": "number"
}
},
"required": [
"label",
"score"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "List the television stations available for TV search with their market, network, monitoring start date, and monitoring end date — every station by default, or only those matching the optional stations, network, and market filters (each an exact, case-insensitive match; combined with AND). activeCount and totalCount count the returned stations. Stations with an end date within the last 24 hours are flagged as active; stations with earlier end dates are discontinued. Use before querying to verify a station was active during the target time period, or to discover valid station IDs for the stations parameter in other TV tools. Most station monitoring ended October 2024 when the Internet Archive TV feed stopped updating.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"market": {
"description": "Market to narrow to (e.g. \"National\", \"San Francisco\"), matched as a whole value case-insensitively after trimming — \"National\" does not match \"NationalSpecialty\". Values come from the market field of the unfiltered list. Blank is ignored.",
"type": "string"
},
"network": {
"description": "Network to narrow to (e.g. \"CNN\", \"ABC\"), matched as a whole value case-insensitively after trimming — \"FOX\" does not match \"FOXNEWS\". Values come from the network field of the unfiltered list. Blank is ignored.",
"type": "string"
},
"stations": {
"description": "Station IDs to return (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]) — the IDs the stations parameter of the other TV tools takes. Matches any listed ID, exactly and case-insensitively after trimming; IDs that match no station are named in the notice. Blank entries are ignored; omit it or pass [] to include every station.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "gdelt_list_tv_stations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"stations",
"activeCount",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"activeCount": {
"description": "Number of returned stations currently flagged as active.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data, including an empty station catalog. Other values are possible when a failure originates below the handler.",
"examples": [
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Filter outcome: names the filters when no station matched, and names requested station IDs that are not in the catalog or that another filter excluded. Absent when every requested ID was returned and the result is not empty.",
"type": "string"
},
"stations": {
"description": "Stations matching every supplied filter — all stations when none is given — sorted by station ID.",
"items": {
"additionalProperties": false,
"description": "A single TV station with monitoring metadata.",
"properties": {
"description": {
"description": "Human-readable station description.",
"type": "string"
},
"endDate": {
"description": "Monitoring end date in ISO 8601 format.",
"type": "string"
},
"isActive": {
"description": "True when the end date is within the last 24 hours (recently updated feed). False for discontinued stations.",
"type": "boolean"
},
"market": {
"description": "Market (e.g. \"National\", \"San Francisco\").",
"type": "string"
},
"network": {
"description": "Network affiliation (e.g. \"CNN\", \"NBC\").",
"type": "string"
},
"startDate": {
"description": "Monitoring start date in ISO 8601 format.",
"type": "string"
},
"stationId": {
"description": "Station ID used in TV query operators (e.g. \"CNN\").",
"type": "string"
}
},
"required": [
"stationId",
"description",
"market",
"network",
"startDate",
"endDate",
"isActive"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Number of stations returned — the whole catalog when no filter is given.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Fetches up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL, and returns as many as fit a 48,000-byte response — the rest are counted in withheldCount, with a continuation to reach them. Query supports full GDELT syntax: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), source country (sourcecountry:china), source language (sourcelang:spanish), domain (domain:who.int), GKG theme (theme:TAX_DISEASE_OUTBREAK — find identifiers with gdelt_search_themes), tone filter (tone<-5 for negative), proximity (near20:\"flu virus\"), and repeat (repeat3:\"outbreak\"). 250 is a hard per-call ceiling and GDELT offers no cursor: when a query fills it or a response comes back cut, re-query narrower startDatetime/endDatetime windows — the response hands back the exact windows to use. Note: this API covers only the most recent 3 months — use gdelt_search_tv for historical TV transcripts back to 2009.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endDatetime": {
"description": "End of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must be supplied together with startDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"maxRecords": {
"default": 75,
"description": "Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead.",
"maximum": 250,
"minimum": 1,
"type": "integer"
},
"query": {
"description": "Search query. Supports GDELT operators: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:TAX_DISEASE_OUTBREAK (GKG theme identifiers come from gdelt_search_themes), tone<-5, near20:\"flu virus\", repeat3:\"outbreak\".",
"minLength": 1,
"type": "string"
},
"sort": {
"default": "relevance",
"description": "Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency).",
"enum": [
"relevance",
"dateDesc",
"dateAsc",
"toneDesc",
"toneAsc",
"hybridRel"
],
"type": "string"
},
"startDatetime": {
"description": "Start of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must be supplied together with endDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"timespan": {
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_search_articles",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"articles",
"effectiveQuery",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"articles": {
"description": "Matching articles sorted per the sort parameter.",
"items": {
"additionalProperties": false,
"description": "A single news article with metadata.",
"properties": {
"domain": {
"description": "Source domain (e.g. \"nytimes.com\").",
"type": "string"
},
"language": {
"description": "Article language (e.g. \"English\", \"Spanish\").",
"type": "string"
},
"seendate": {
"description": "Publication datetime in GDELT format (YYYYMMDDTHHMMSSZ).",
"type": "string"
},
"socialimage": {
"description": "Social sharing image URL when provided by the source.",
"type": "string"
},
"sourcecountry": {
"description": "Country of the source outlet (e.g. \"United States\").",
"type": "string"
},
"title": {
"description": "Article title.",
"type": "string"
},
"url": {
"description": "Article URL.",
"type": "string"
}
},
"required": [
"url",
"title",
"seendate",
"domain",
"language",
"sourcecountry"
],
"type": "object"
},
"type": "array"
},
"continuationWindows": {
"description": "Windows to re-run this query against, one at a time, when more articles are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further.",
"items": {
"additionalProperties": false,
"description": "One window to re-query with the same query string.",
"properties": {
"endDatetime": {
"description": "End of this window in GDELT format YYYYMMDDHHMMSS.",
"type": "string"
},
"startDatetime": {
"description": "Start of this window in GDELT format YYYYMMDDHHMMSS.",
"type": "string"
}
},
"required": [
"startDatetime",
"endDatetime"
],
"type": "object"
},
"type": "array"
},
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget.",
"type": "string"
},
"timespan": {
"description": "Echoed timespan parameter when provided.",
"type": "string"
},
"totalCount": {
"description": "Number of articles returned in this response.",
"type": "number"
},
"withheldCount": {
"description": "Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Find 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"limit": {
"default": 25,
"description": "Maximum matches returned in this response (1–100).",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "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.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_search_themes",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"matches",
"totalMatches",
"offset",
"limit",
"effectiveQuery",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_query`: The query has no letter or digit to match — blank, whitespace, or only punctuation such as \"___\". `offset_out_of_range`: The requested offset is at or beyond the end of a non-empty match list. `gdelt_unavailable`: The GDELT GKG theme lookup could not be downloaded, or came back empty or not as THEME<TAB>count lines. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_query",
"offset_out_of_range",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"limit": {
"description": "Maximum matches requested for this page.",
"type": "number"
},
"matches": {
"description": "Matches on this page: an exact identifier match first, then by count descending, then by identifier.",
"items": {
"additionalProperties": false,
"description": "A matching GKG theme.",
"properties": {
"count": {
"description": "Count the GDELT theme lookup lists for this theme — a static prevalence figure, not a live article total.",
"type": "number"
},
"operator": {
"description": "Paste-ready query operator for the DOC tools (e.g. \"theme:NATURAL_DISASTER_DROUGHT\").",
"type": "string"
},
"theme": {
"description": "GKG theme identifier (e.g. \"NATURAL_DISASTER_DROUGHT\").",
"type": "string"
}
},
"required": [
"theme",
"count",
"operator"
],
"type": "object"
},
"type": "array"
},
"nextOffset": {
"description": "Offset for the next page with the same query. Absent when this is the final page.",
"type": "number"
},
"notice": {
"description": "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.",
"type": "string"
},
"offset": {
"description": "Zero-based offset of this page.",
"type": "number"
},
"totalCount": {
"description": "Total themes matching the query — the same figure as totalMatches.",
"type": "number"
},
"totalMatches": {
"description": "Total themes matching the query, across all pages.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search US television news closed captions (2009–October 2024, 150+ stations) for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic. Use the stations parameter to select networks (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]) — the TV API requires at least one station, supplied either there or as a station: selector inside query. TV query also supports in-query operators: station:CNN, network:CBS, market:\"National\", show:\"Anderson Cooper 360\", context:\"vaccine\". Important: most station monitoring ended October 2024 — use gdelt_list_tv_stations to verify active date ranges before querying recent events.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"dateres": {
"description": "Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution.",
"enum": [
"hour",
"day",
"week",
"month",
"year"
],
"type": "string"
},
"endDatetime": {
"description": "End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"limit": {
"default": 500,
"description": "Maximum timeline points returned in this response (1–500).",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"normalize": {
"default": true,
"description": "When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts.",
"type": "boolean"
},
"offset": {
"default": 0,
"description": "Zero-based point offset into the deterministic date-then-station ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Search query for TV transcript content. Supports TV operators: station:CNN, network:CBS, market:\"National\", show:\"Anderson Cooper\", context:\"vaccine\". Boolean OR and phrase operators also work.",
"minLength": 1,
"type": "string"
},
"smoothing": {
"description": "Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics.",
"maximum": 5,
"minimum": 0,
"type": "integer"
},
"startDatetime": {
"description": "Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected.",
"pattern": "^\\d{14}$",
"type": "string"
},
"stations": {
"description": "Up to 10 station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid station IDs.",
"items": {
"type": "string"
},
"maxItems": 10,
"type": "array"
},
"timespan": {
"description": "Time window, e.g. \"1m\", \"6m\", \"1y\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "gdelt_search_tv",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"series",
"normalized",
"totalPoints",
"offset",
"limit",
"effectiveQuery",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dateResolution": {
"description": "Temporal resolution of data points — as GDELT reported it, as requested via dateres, or inferred from the returned intervals. Omitted when none of those can establish it.",
"enum": [
"hour",
"day",
"week",
"month",
"year"
],
"type": "string"
},
"effectiveQuery": {
"description": "Echoed query string for use in follow-up calls.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"offset_out_of_range",
"invalid_query",
"gdelt_rate_limited",
"gdelt_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"limit": {
"description": "Maximum points requested for this page.",
"type": "number"
},
"nextOffset": {
"description": "Offset for the next page using the same query inputs. Absent when this is the final page.",
"type": "number"
},
"normalized": {
"description": "True when values are normalized coverage percentages.",
"type": "boolean"
},
"notice": {
"description": "Guidance when the query matched no TV coverage — the resolved timespan window, the October 2024 archive cutoff, and how to check station coverage. Absent when coverage was returned.",
"type": "string"
},
"offset": {
"description": "Zero-based offset of this point page.",
"type": "number"
},
"series": {
"description": "Station series represented in this point page.",
"items": {
"additionalProperties": false,
"description": "Coverage time series for a single station.",
"properties": {
"data": {
"description": "Time-ordered coverage data for this station.",
"items": {
"additionalProperties": false,
"description": "A single coverage data point.",
"properties": {
"date": {
"description": "Timestep in ISO 8601 format.",
"type": "string"
},
"value": {
"description": "Coverage value (normalized % or raw matching 15-second clip count).",
"type": "number"
}
},
"required": [
"date",
"value"
],
"type": "object"
},
"type": "array"
},
"station": {
"description": "Station ID (e.g. \"CNN\").",
"type": "string"
}
},
"required": [
"station",
"data"
],
"type": "object"
},
"type": "array"
},
"timeRange": {
"additionalProperties": false,
"description": "Date range spanned by this returned point page. Omitted when the page is empty.",
"properties": {
"end": {
"description": "Latest date in the returned data.",
"type": "string"
},
"start": {
"description": "Earliest date in the returned data.",
"type": "string"
}
},
"required": [
"start",
"end"
],
"type": "object"
},
"totalCount": {
"description": "Number of station series returned.",
"type": "number"
},
"totalPoints": {
"description": "Total points available across all matched station series before pagination.",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:562ebaa9405ff9572cd33682b4b3f952f8d0536ce5ecd13890ab5dcea6d89284 | sha256sum