gdelt-mcp-server

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.

{
  "type": "object",
  "properties": {
    "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": {
      "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"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 250
    },
    "sort": {
      "default": "relevance",
      "description": "Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency).",
      "type": "string",
      "enum": [
        "relevance",
        "dateDesc",
        "dateAsc",
        "toneDesc",
        "toneAsc",
        "hybridRel"
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "articles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Article URL."
          },
          "title": {
            "type": "string",
            "description": "Article title."
          },
          "seendate": {
            "type": "string",
            "description": "Publication datetime in GDELT format (YYYYMMDDTHHMMSSZ)."
          },
          "domain": {
            "type": "string",
            "description": "Source domain (e.g. \"nytimes.com\")."
          },
          "language": {
            "type": "string",
            "description": "Article language (e.g. \"English\", \"Spanish\")."
          },
          "sourcecountry": {
            "type": "string",
            "description": "Country of the source outlet (e.g. \"United States\")."
          },
          "socialimage": {
            "description": "Social sharing image URL when provided by the source.",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title",
          "seendate",
          "domain",
          "language",
          "sourcecountry"
        ],
        "additionalProperties": false,
        "description": "A single news article with metadata."
      },
      "description": "Matching articles sorted per the sort parameter."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of articles returned in this response."
    },
    "timespan": {
      "description": "Echoed timespan parameter when provided.",
      "type": "string"
    },
    "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"
    },
    "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"
    },
    "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.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "startDatetime": {
            "type": "string",
            "description": "Start of this window in GDELT format YYYYMMDDHHMMSS."
          },
          "endDatetime": {
            "type": "string",
            "description": "End of this window in GDELT format YYYYMMDDHHMMSS."
          }
        },
        "required": [
          "startDatetime",
          "endDatetime"
        ],
        "additionalProperties": false,
        "description": "One window to re-query with the same query string."
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "articles",
        "effectiveQuery",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "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), tone<."
    },
    "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.",
      "type": "string",
      "enum": [
        "volume",
        "volume_with_articles",
        "tone"
      ]
    },
    "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"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "smoothing": {
      "description": "Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics.",
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "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.",
      "type": "string",
      "enum": [
        "15min",
        "hour",
        "day"
      ]
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Series label (e.g. \"Volume Intensity\" or \"Average Tone\")."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Timestep in ISO 8601 format."
                },
                "value": {
                  "type": "number",
                  "description": "Normalized coverage % (volume mode) or average tone score (tone mode). Tone range is approximately -100 to +100."
                },
                "articles": {
                  "description": "Top articles driving coverage at this timestep. Present only in volume_with_articles mode.",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "Article URL."
                      },
                      "title": {
                        "type": "string",
                        "description": "Article title."
                      }
                    },
                    "required": [
                      "url",
                      "title"
                    ],
                    "additionalProperties": false,
                    "description": "An article linked to this spike."
                  }
                }
              },
              "required": [
                "date",
                "value"
              ],
              "additionalProperties": false,
              "description": "A single time-series data point."
            },
            "description": "Time-ordered data points for this series."
          }
        },
        "required": [
          "label",
          "data"
        ],
        "additionalProperties": false,
        "description": "A single time series with a label and data points."
      },
      "description": "One or more time series (typically one for volume/tone, one per label for breakdowns)."
    },
    "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "mode": {
      "type": "string",
      "enum": [
        "volume",
        "volume_with_articles",
        "tone"
      ],
      "description": "Timeline mode used for this response."
    },
    "totalCount": {
      "type": "number",
      "description": "Total number of data points across all series."
    },
    "startDatetime": {
      "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
      "type": "string"
    },
    "endDatetime": {
      "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
      "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "series",
        "effectiveQuery",
        "mode",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "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)."
    },
    "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"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "histogram": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bin": {
            "type": "number",
            "description": "Tone bin integer (typically -30 to +30; 0 is neutral)."
          },
          "count": {
            "type": "number",
            "description": "Number of articles in this bin."
          },
          "articles": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "description": "Article URL."
                },
                "title": {
                  "type": "string",
                  "description": "Article title."
                }
              },
              "required": [
                "url",
                "title"
              ],
              "additionalProperties": false,
              "description": "A representative article for this tone bin."
            },
            "description": "Representative articles in this tone bin."
          }
        },
        "required": [
          "bin",
          "count",
          "articles"
        ],
        "additionalProperties": false,
        "description": "A single tone histogram bin with article count and representative articles."
      },
      "description": "Tone histogram sorted from most negative to most positive bin."
    },
    "summary": {
      "type": "object",
      "properties": {
        "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"
        },
        "neutralPct": {
          "description": "Percentage of articles in the near-neutral range (bins -2 to +2). Omitted when the histogram counts no articles.",
          "type": "number"
        }
      },
      "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."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "type": "number",
      "description": "Total number of articles across all histogram bins."
    },
    "startDatetime": {
      "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
      "type": "string"
    },
    "endDatetime": {
      "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
      "type": "string"
    },
    "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "histogram",
        "summary",
        "effectiveQuery",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "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)."
    },
    "breakdownBy": {
      "type": "string",
      "enum": [
        "language",
        "country"
      ],
      "description": "Breakdown dimension: \"language\" for source language time series, \"country\" for source country time series."
    },
    "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"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query",
    "breakdownBy"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "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.",
      "type": "string",
      "enum": [
        "15min",
        "hour",
        "day"
      ]
    },
    "topSeries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Series label (language name or country name)."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Timestep in ISO 8601 format."
                },
                "value": {
                  "type": "number",
                  "description": "Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count."
                }
              },
              "required": [
                "date",
                "value"
              ],
              "additionalProperties": false,
              "description": "A single data point for this series."
            },
            "description": "Time-ordered data points for this series."
          }
        },
        "required": [
          "label",
          "data"
        ],
        "additionalProperties": false,
        "description": "A single language or country coverage series."
      },
      "description": "Top 10 series by total coverage volume."
    },
    "otherAggregated": {
      "description": "Combined time series for all series beyond the top 10. Omitted when all series fit.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Timestep in ISO 8601 format."
          },
          "value": {
            "type": "number",
            "description": "Aggregated normalized coverage volume for all remaining series — a share of media output, not an absolute article count."
          }
        },
        "required": [
          "date",
          "value"
        ],
        "additionalProperties": false,
        "description": "A single aggregated data point for the \"Other\" bucket."
      }
    },
    "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "selectedSeries": {
      "description": "Complete, untruncated time series for each label requested via the series input, in the order requested. Omitted when series was not supplied.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Series label (language name or country name)."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Timestep in ISO 8601 format."
                },
                "value": {
                  "type": "number",
                  "description": "Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count."
                }
              },
              "required": [
                "date",
                "value"
              ],
              "additionalProperties": false,
              "description": "A single data point for this series."
            },
            "description": "Time-ordered data points for this series."
          }
        },
        "required": [
          "label",
          "data"
        ],
        "additionalProperties": false,
        "description": "A single language or country coverage series."
      }
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "breakdownBy": {
      "type": "string",
      "enum": [
        "language",
        "country"
      ],
      "description": "Breakdown dimension used for this response."
    },
    "totalCount": {
      "type": "number",
      "description": "Total number of series returned before truncation to top 10."
    },
    "startDatetime": {
      "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
      "type": "string"
    },
    "endDatetime": {
      "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
      "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 breakdown data was returned.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "topSeries",
        "effectiveQuery",
        "breakdownBy",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "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": {
      "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 25,
      "description": "Maximum matches returned in this response (1–100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "theme": {
            "type": "string",
            "description": "GKG theme identifier (e.g. \"NATURAL_DISASTER_DROUGHT\")."
          },
          "count": {
            "type": "number",
            "description": "Count the GDELT theme lookup lists for this theme — a static prevalence figure, not a live article total."
          },
          "operator": {
            "type": "string",
            "description": "Paste-ready query operator for the DOC tools (e.g. \"theme:NATURAL_DISASTER_DROUGHT\")."
          }
        },
        "required": [
          "theme",
          "count",
          "operator"
        ],
        "additionalProperties": false,
        "description": "A matching GKG theme."
      },
      "description": "Matches on this page: an exact identifier match first, then by count descending, then by identifier."
    },
    "totalMatches": {
      "type": "number",
      "description": "Total themes matching the query, across all pages."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of this page."
    },
    "limit": {
      "type": "number",
      "description": "Maximum matches requested for this page."
    },
    "nextOffset": {
      "description": "Offset for the next page with the same query. Absent when this is the final page.",
      "type": "number"
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "type": "number",
      "description": "Total themes matching the query — the same figure as totalMatches."
    },
    "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "matches",
        "totalMatches",
        "offset",
        "limit",
        "effectiveQuery",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "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."
    },
    "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.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "timespan": {
      "description": "Time window, e.g. \"1m\", \"6m\", \"1y\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
      "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "smoothing": {
      "description": "Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics.",
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "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"
    },
    "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.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 500,
      "description": "Maximum timeline points returned in this response (1–500).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "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.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "timeRange": {
      "description": "Date range spanned by this returned point page. Omitted when the page is empty.",
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "Earliest date in the returned data."
        },
        "end": {
          "type": "string",
          "description": "Latest date in the returned data."
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "station": {
            "type": "string",
            "description": "Station ID (e.g. \"CNN\")."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Timestep in ISO 8601 format."
                },
                "value": {
                  "type": "number",
                  "description": "Coverage value (normalized % or raw matching 15-second clip count)."
                }
              },
              "required": [
                "date",
                "value"
              ],
              "additionalProperties": false,
              "description": "A single coverage data point."
            },
            "description": "Time-ordered coverage data for this station."
          }
        },
        "required": [
          "station",
          "data"
        ],
        "additionalProperties": false,
        "description": "Coverage time series for a single station."
      },
      "description": "Station series represented in this point page."
    },
    "normalized": {
      "type": "boolean",
      "description": "True when values are normalized coverage percentages."
    },
    "totalPoints": {
      "type": "number",
      "description": "Total points available across all matched station series before pagination."
    },
    "offset": {
      "type": "number",
      "description": "Zero-based offset of this point page."
    },
    "limit": {
      "type": "number",
      "description": "Maximum points requested for this page."
    },
    "nextOffset": {
      "description": "Offset for the next page using the same query inputs. Absent when this is the final page.",
      "type": "number"
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of station series returned."
    },
    "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$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"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "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": {
      "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "timespan": {
      "description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
      "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 3000
    },
    "sort": {
      "default": "relevance",
      "description": "Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first).",
      "type": "string",
      "enum": [
        "relevance",
        "dateDesc",
        "dateAsc"
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "clips": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "show": {
            "type": "string",
            "description": "Show name (e.g. \"Anderson Cooper 360\")."
          },
          "station": {
            "type": "string",
            "description": "Station ID (e.g. \"CNN\")."
          },
          "date": {
            "type": "string",
            "description": "Air datetime in ISO 8601 format."
          },
          "snippet": {
            "type": "string",
            "description": "15-second transcript excerpt surrounding the match."
          },
          "archiveUrl": {
            "type": "string",
            "description": "Internet Archive URL to view the full 1-minute clip."
          },
          "thumbnail": {
            "description": "Clip thumbnail URL when provided by the archive.",
            "type": "string"
          }
        },
        "required": [
          "show",
          "station",
          "date",
          "snippet",
          "archiveUrl"
        ],
        "additionalProperties": false,
        "description": "A single TV news clip with transcript excerpt and archive link."
      },
      "description": "Matching TV clips sorted per the sort parameter."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of clips returned."
    },
    "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"
    },
    "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"
    },
    "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.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "startDatetime": {
            "type": "string",
            "description": "Start of this window in GDELT format YYYYMMDDHHMMSS."
          },
          "endDatetime": {
            "type": "string",
            "description": "End of this window in GDELT format YYYYMMDDHHMMSS."
          }
        },
        "required": [
          "startDatetime",
          "endDatetime"
        ],
        "additionalProperties": false,
        "description": "One window to re-query with the same query string."
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "clips",
        "effectiveQuery",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "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": {
      "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.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "timespan": {
      "description": "Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.",
      "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    },
    "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.",
      "type": "string",
      "pattern": "^\\d{14}$"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "words": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Co-occurring word or phrase."
          },
          "score": {
            "type": "number",
            "description": "Relative frequency score (0–100). The query term itself scores 100; other terms are proportional to their co-occurrence frequency."
          }
        },
        "required": [
          "label",
          "score"
        ],
        "additionalProperties": false,
        "description": "A co-occurring term with its relative frequency score."
      },
      "description": "Co-occurring terms sorted by score descending."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "Echoed query string for use in follow-up calls."
    },
    "totalCount": {
      "description": "Number of clips from which co-occurrences were computed. Absent when the upstream API does not return a clip count.",
      "type": "number"
    },
    "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "words",
        "effectiveQuery"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "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.",
      "type": "array",
      "items": {
        "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"
    },
    "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"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "stations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "stationId": {
            "type": "string",
            "description": "Station ID used in TV query operators (e.g. \"CNN\")."
          },
          "description": {
            "type": "string",
            "description": "Human-readable station description."
          },
          "market": {
            "type": "string",
            "description": "Market (e.g. \"National\", \"San Francisco\")."
          },
          "network": {
            "type": "string",
            "description": "Network affiliation (e.g. \"CNN\", \"NBC\")."
          },
          "startDate": {
            "type": "string",
            "description": "Monitoring start date in ISO 8601 format."
          },
          "endDate": {
            "type": "string",
            "description": "Monitoring end date in ISO 8601 format."
          },
          "isActive": {
            "type": "boolean",
            "description": "True when the end date is within the last 24 hours (recently updated feed). False for discontinued stations."
          }
        },
        "required": [
          "stationId",
          "description",
          "market",
          "network",
          "startDate",
          "endDate",
          "isActive"
        ],
        "additionalProperties": false,
        "description": "A single TV station with monitoring metadata."
      },
      "description": "Stations matching every supplied filter — all stations when none is given — sorted by station ID."
    },
    "activeCount": {
      "type": "number",
      "description": "Number of returned stations currently flagged as active."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of stations returned — the whole catalog when no filter is given."
    },
    "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "stations",
        "activeCount",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}