Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
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 the top 10 series ranked by the sum of their values and names every other series under otherSeriesLabels — pass any labels, ranked or not, as the series input to get only those series, complete. A response carries as many whole series as fit its size budget; when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Values are normalized: each point is the topic's share of that source's media output, not an absolute article count, so values from different sources do not add up to a share. 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.
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).
Breakdown dimension: "language" for source language time series, "country" for source country time series.
Zero-based series offset — into the ranked top 10, or into the series named in series. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page.
Exact series labels to return instead of the ranked overview, e.g. ["Portuguese", "Vietnamese"]. Take them verbatim from otherSeriesLabels or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, in the order requested; a label that matches nothing is rejected rather than silently skipped. Omit to get the ranked overview.
Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.
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.
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.
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 the top 10 series ranked by the sum of their values and names every other series under otherSeriesLabels — pass any labels, ranked or not, as the series input to get only those series, complete. A response carries as many whole series as fit its size budget; when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Values are normalized: each point is the topic's share of that source's media output, not an absolute article count, so values from different sources do not add up to a share. 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.
| Argument | Type | Description |
|---|---|---|
| query* | string | 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 | integer | Zero-based series offset — into the ranked top 10, or into the series named in series. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page. |
| series | array | Exact series labels to return instead of the ranked overview, e.g. ["Portuguese", "Vietnamese"]. Take them verbatim from otherSeriesLabels or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, in the order requested; a label that matches nothing is rejected rather than silently skipped. Omit to get the ranked overview. |
| timespan | string | Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. |
| breakdownBy* | string | Breakdown dimension: "language" for source language time series, "country" for source country time series. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query",
"breakdownBy"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"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)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based series offset — into the ranked top 10, or into the series named in series. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page."
},
"series": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact series labels to return instead of the ranked overview, e.g. [\"Portuguese\", \"Vietnamese\"]. Take them verbatim from otherSeriesLabels or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, in the order requested; a label that matches nothing is rejected rather than silently skipped. Omit to get the ranked overview."
},
"timespan": {
"type": "string",
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."
},
"breakdownBy": {
"enum": [
"language",
"country"
],
"type": "string",
"description": "Breakdown dimension: \"language\" for source language time series, \"country\" for source country time series."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}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 each timestep carries its first 3 article links and referenceCount, its true article count; name timesteps' dates in points to get only those timesteps, each with its full list. A response carries as many whole timesteps as fit its size budget; when more remain it returns nextOffset — pass it back as offset with otherwise identical inputs for the next page. Note: DOC API covers only the last 3 months.
| Argument | Type | Description |
|---|---|---|
| mode | string | 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. |
| query* | string | 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<. |
| offset | integer | Zero-based timestep offset — into the timeline, or into the timesteps named in points. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page. |
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 as many whole bins as fit its size budget; 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.
| Argument | Type | Description |
|---|---|---|
| bins | array | 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. |
| query* | string | 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 | integer | 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. |
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, the station's display name — with its station ID when that name resolves to one — 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 — pass a series' station value as stations here. 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.
| Argument | Type | Description |
|---|---|---|
| sort | string | Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first). |
| query* | string | Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". |
| stations | array | 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. |
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 with relative frequency scores (0–100, where 100 = the query term itself). Terms and scores come from GDELT's relevance-ranked sample of matching clips, documented as the 200 most relevant, not all matching coverage — compare windows or stations with a separate, narrower call for each. Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms. TV data spans 2009–October 2024.
| Argument | Type | Description |
|---|---|---|
| query* | string | Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". |
| stations | array | 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. |
| timespan | string | Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024. |
| endDatetime | string | 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. |
| startDatetime |
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.
| Argument | Type | Description |
|---|---|---|
| market | string | 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. |
| network | string | 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. |
| stations | array | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"market": {
"type": "string",
"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."
},
"network": {
"type": "string",
"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."
},
"stations": {
"type": "array",
"items": {
"type": "string"
},
"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."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| sort | string | Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency). |
| query* | string | 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". |
| timespan | string | 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. |
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 (up to 100 matches per page; a larger limit runs at 100).
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum matches returned in this response (1–100; a value up to 1000 runs at 100, and the response says so in limitClamp). |
| query* | string | 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 | integer |
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 — up to 500 points per page; a larger limit runs at 500. Each series carries GDELT's display name for the station and, when that name resolves to one, the station ID gdelt_get_tv_clips takes as stations. 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.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum timeline points returned in this response (1–500; a value up to 5000 runs at 500, and the response says so in limitClamp). |
| query* | string | 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. |
| offset | integer | Zero-based point offset into the deterministic date-then-station-name ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page. |
| dateres | string | Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution. |
| points | array | Timestep dates to return alone, 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. The response then carries only these timesteps, in timeline order, and in volume_with_articles mode each carries its complete article list instead of the first 3. A date matching no timestep is rejected rather than silently ignored. |
| timespan | string | Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. |
| smoothing | integer | Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"mode": {
"enum": [
"volume",
"volume_with_articles",
"tone"
],
"type": "string",
"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."
},
"query": {
"type": "string",
"minLength": 1,
"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<."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based timestep offset — into the timeline, or into the timesteps named in points. Pass nextOffset from the preceding response, with otherwise identical inputs, to get the next page."
},
"points": {
"type": "array",
"items": {
"type": "string"
},
"description": "Timestep dates to return alone, 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. The response then carries only these timesteps, in timeline order, and in volume_with_articles mode each carries its complete article list instead of the first 3. A date matching no timestep is rejected rather than silently ignored."
},
"timespan": {
"type": "string",
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."
},
"smoothing": {
"type": "integer",
"maximum": 5,
"minimum": 0,
"description": "Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}| timespan |
| string |
| Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"bins": {
"type": "array",
"items": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"description": "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."
},
"query": {
"type": "string",
"minLength": 1,
"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)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "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": {
"type": "string",
"description": "Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}| timespan |
| string |
| Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024. |
| maxRecords | integer | Maximum number of clips to fetch (1–3000; a value up to 30000 runs at 3000, and the response says so in limitClamp). 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. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"sort": {
"enum": [
"relevance",
"dateDesc",
"dateAsc"
],
"type": "string",
"default": "relevance",
"description": "Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first)."
},
"query": {
"type": "string",
"minLength": 1,
"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\"."
},
"stations": {
"type": "array",
"items": {
"type": "string"
},
"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."
},
"timespan": {
"type": "string",
"description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024."
},
"maxRecords": {
"type": "integer",
"default": 50,
"maximum": 30000,
"minimum": 1,
"description": "Maximum number of clips to fetch (1–3000; a value up to 30000 runs at 3000, and the response says so in limitClamp). 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."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}| string |
| 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"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\"."
},
"stations": {
"type": "array",
"items": {
"type": "string"
},
"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."
},
"timespan": {
"type": "string",
"description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}| maxRecords | integer | Maximum number of articles to fetch (1–250; a value up to 2500 runs at 250, and the response says so in limitClamp). 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. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"sort": {
"enum": [
"relevance",
"dateDesc",
"dateAsc",
"toneDesc",
"toneAsc",
"hybridRel"
],
"type": "string",
"default": "relevance",
"description": "Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency)."
},
"query": {
"type": "string",
"minLength": 1,
"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\"."
},
"timespan": {
"type": "string",
"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."
},
"maxRecords": {
"type": "integer",
"default": 75,
"maximum": 2500,
"minimum": 1,
"description": "Maximum number of articles to fetch (1–250; a value up to 2500 runs at 250, and the response says so in limitClamp). 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."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}| Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 1000,
"minimum": 1,
"description": "Maximum matches returned in this response (1–100; a value up to 1000 runs at 100, and the response says so in limitClamp)."
},
"query": {
"type": "string",
"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."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page."
}
},
"additionalProperties": false
}| stations | array | 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. |
| timespan | string | Time window, e.g. "1m", "6m", "1y". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024. |
| normalize | boolean | When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts. |
| smoothing | integer | Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics. |
| endDatetime | string | 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. |
| startDatetime | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 500,
"maximum": 5000,
"minimum": 1,
"description": "Maximum timeline points returned in this response (1–500; a value up to 5000 runs at 500, and the response says so in limitClamp)."
},
"query": {
"type": "string",
"minLength": 1,
"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."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based point offset into the deterministic date-then-station-name ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page."
},
"dateres": {
"enum": [
"hour",
"day",
"week",
"month",
"year"
],
"type": "string",
"description": "Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution."
},
"stations": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"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."
},
"timespan": {
"type": "string",
"description": "Time window, e.g. \"1m\", \"6m\", \"1y\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024."
},
"normalize": {
"type": "boolean",
"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."
},
"smoothing": {
"type": "integer",
"maximum": 5,
"minimum": 0,
"description": "Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics."
},
"endDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
},
"startDatetime": {
"type": "string",
"pattern": "^\\d{14}$",
"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."
}
},
"additionalProperties": false
}