# GDELT

> Search the world's news with GDELT, the open project that monitors online news in 65 languages and decades of US television news, and works out what each story is about and how positively it is told. No account or API key is needed. Search articles back to 2017 and the sentences a phrase appears in; chart how coverage and its tone move over time; and search television by what was said, written on screen or shown on camera.

App · News · 12 actions. Web page: https://docs.lodol.com/docs/integrations/gdelt

## Actions

### Chart news coverage over time

Chart how much a topic was covered, and how positively, over time. Choose a share of all coverage, a raw article count, the average tone, or a breakdown by language or publishing country. A breakdown returns one line per language or country GDELT monitors, so the ones with no coverage at all are left out, and 'How many lines' keeps just the busiest of the rest.

**Inputs**

- What to chart (`metric`, text): Which measurement to plot over time. One of: `volume_share` (Share of all coverage (%)), `article_count` (Number of matching articles), `volume_with_articles` (Share of all coverage, with the top articles at each point), `tone` (Average tone of the coverage), `by_language` (Share of coverage, split by language), `by_source_country` (Share of coverage, split by publishing country). Default: `volume_share`.
- Search words (`query`, text): The words to search for, for example 'wildfire evacuation'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when at least one filter below is set.
- Theme (`theme`, text): Only coverage tagged with this GDELT theme, for example 'NATURAL_DISASTER_FLOOD'. Themes are GDELT's own topic labels; the list is the most-used ones, each showing how often it appears.
- Published in (`source_country`, text): Only coverage published in this country. This is where the outlet is, not what the story is about.
- Written in (`source_language`, text): Only coverage written in this language. GDELT machine-translates all of them, so English search words still match.
- Only these websites (`domains`, text): Only coverage from these websites, as a comma-separated list of domains, for example 'bbc.com, reuters.com'.
- Leave out these websites (`exclude_domains`, text): Leave out coverage from these websites, as a comma-separated list of domains.
- Tone above (`tone_greater_than`, number): Only coverage more positive than this. Tone runs from about -10 (extremely negative) to +10 (extremely positive), with most news between -5 and +5. Try 2 for positive coverage. From -100 to 100.
- Tone below (`tone_less_than`, number): Only coverage more negative than this. Try -5 for strongly negative coverage. From -100 to 100.
- How far back (`timespan`, text): How far back to search. Leave empty for GDELT's default of the last 3 months. Use the two date fields below instead for an exact window. One of: `1h` (Last hour), `6h` (Last 6 hours), `12h` (Last 12 hours), `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), and 3 more.
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Smoothing (`smoothing`, number): Average each point with the ones around it to flatten day-to-day noise, from 0 (off) to 30 points. From 0 to 30.
- How many lines (`max_series`, number): When splitting by language or country, keep only the busiest this many. Leave empty to return every one, which is around 200 lines, so try 10 first. From 1 to 250.

**Outputs**

- `date_resolution` (text)
- `empty_series_omitted` (number)
- `metric` (text)
- `query` (text)
- `quiet_series_omitted` (number)
- `series` (list)
- `series_count` (number)

**Example output**

```json
{
  "date_resolution": "day",
  "empty_series_omitted": 0,
  "metric": "TimelineVol",
  "query": "climate change",
  "quiet_series_omitted": 0,
  "series": [
    {
      "point_count": 2,
      "points": [
        {
          "date": "2026-08-21T00:00:00Z",
          "value": 1.0945
        },
        {
          "date": "2026-08-22T00:00:00Z",
          "value": 1.4183
        }
      ],
      "series": "Volume Intensity"
    }
  ],
  "series_count": 1
}
```

### Chart television coverage over time

Chart how much television airtime a topic took over time, as a share of everything each station broadcast so stations of different sizes can be compared directly.

**Inputs**

- What to chart (`metric`, text): Which measurement to plot over time. One of: `airtime_share` (Share of airtime the topic took (%)), `monitored_airtime` (How much airtime was monitored in total), `hourly_heatmap` (Hour-by-hour heatmap), `streamgraph` (Stacked stream, one band per station). Default: `airtime_share`.
- Search words (`query`, text): The words to look for in the closed captions, for example 'interest rates'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when a station, market, network or show is chosen below.
- Station (`station`, text): Only clips from this station, for example CNN.
- Market (`market`, text): Only clips from stations in this market. 'National' is the national networks; the rest are individual cities.
- Network (`network`, text): Only clips from this network's stations, for example CBS. A network covers all of its local affiliates at once.
- Show (`show`, text): Only clips from this show. The name must match exactly, for example 'Anderson Cooper 360'.
- Also said nearby (`context`, text): Only clips where this also comes up within about fifteen seconds of the search words.
- How far back (`timespan`, text): How far back to search. Leave empty to search the last 5 years. GDELT's television archive runs from July 2009 to October 2024, so a short window finds nothing. Use the two date fields below to search an exact stretch of it. One of: `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), `1y` (Last year), `2y` (Last 2 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Group points by (`date_resolution`, text): How wide each point on the chart should be. Defaults to whatever suits the window. One of: `hour` (Hourly), `day` (Daily), `week` (Weekly), `month` (Monthly), `year` (Yearly).
- Measure as (`normalization`, text): Whether each point is a share of the station's airtime or a raw clip count. One of: `percentage` (As a share of each station's airtime (comparable)), `raw` (As a raw count of matching clips).
- Combine all stations (`combine_stations`, true/false): Merge every station into one line instead of drawing one line per station.
- Smoothing (`smoothing`, number): Average each point with the ones around it to flatten day-to-day noise, from 0 (off) to 30 points. From 0 to 30.
- Include the last 24 hours (`include_last_24_hours`, true/false): The most recent day is left out by default because it is still being processed and reads as a dip. Turn this on to include it anyway.

**Outputs**

- `empty_series_omitted` (number)
- `metric` (text)
- `note` (text)
- `query` (text)
- `series` (list)
- `series_count` (number)

**Example output**

```json
{
  "empty_series_omitted": 0,
  "metric": "TimelineVol",
  "query": "climate market:\"National\"",
  "series": [
    {
      "point_count": 2,
      "points": [
        {
          "date": "2024-09-01T12:00:00Z",
          "value": 0.42
        },
        {
          "date": "2024-10-01T12:00:00Z",
          "value": 0.61
        }
      ],
      "series": "CNN"
    }
  ],
  "series_count": 1
}
```

### Chart the tone of coverage

Show how positive or negative the coverage of a topic is, as a histogram: one bin per tone score, how many articles landed in it, and a sample of those articles. Handy for jumping straight to the most negative reporting on something.

**Inputs**

- Search words (`query`, text): The words to search for, for example 'wildfire evacuation'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when at least one filter below is set.
- Theme (`theme`, text): Only coverage tagged with this GDELT theme, for example 'NATURAL_DISASTER_FLOOD'. Themes are GDELT's own topic labels; the list is the most-used ones, each showing how often it appears.
- Published in (`source_country`, text): Only coverage published in this country. This is where the outlet is, not what the story is about.
- Written in (`source_language`, text): Only coverage written in this language. GDELT machine-translates all of them, so English search words still match.
- Only these websites (`domains`, text): Only coverage from these websites, as a comma-separated list of domains, for example 'bbc.com, reuters.com'.
- Leave out these websites (`exclude_domains`, text): Leave out coverage from these websites, as a comma-separated list of domains.
- How far back (`timespan`, text): How far back to search. Leave empty for GDELT's default of the last 3 months. Use the two date fields below instead for an exact window. One of: `1h` (Last hour), `6h` (Last 6 hours), `12h` (Last 12 hours), `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), and 3 more.
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.

**Outputs**

- `bin_count` (number)
- `bins` (list)
- `query` (text)

**Example output**

```json
{
  "bin_count": 2,
  "bins": [
    {
      "bin": -3,
      "count": 412
    },
    {
      "articles": [
        {
          "domain": "bbc.com",
          "language": "English",
          "seendate": "2026-08-22T14:15:00Z",
          "socialimage": "https://ichef.bbci.co.uk/news/1024/example.jpg",
          "sourcecountry": "United Kingdom",
          "title": "Severe flood warnings issued across the south coast",
          "url": "https://www.bbc.com/news/articles/example-flood-warning",
          "url_mobile": ""
        }
      ],
      "bin": 0,
      "count": 1580
    }
  ],
  "query": "climate change"
}
```

### Chart what TV said and showed over time

Chart how often something was said aloud, written on screen or shown on camera, using GDELT's AI annotations of television news rather than the closed captions alone. Unlike the caption archive this is still being updated, so it reaches up to the past few days.

**Inputs**

- Station (`station`, text, required): Which station to search. Required: GDELT's AI television search only runs against named stations.
- Search words (`query`, text): Words to look for across every annotation layer at once. For a specific layer, use the four fields below instead. Can be left empty when one of those is filled in.
- Spoken on air (`spoken_words`, text): Words spoken aloud, from the machine transcript. Up to five words.
- In the closed captions (`closed_captions`, text): Words as they appeared in the station's own closed captions.
- Written on screen (`onscreen_text`, text): Text recognised on screen (a chyron, a caption, a sign). Up to five words.
- Shown on screen (`visual_label`, text): Something a vision model saw in the picture, for example 'flag' or 'crowd'. Use 'List what TV said and showed' to see the labels available.
- Show (`show`, text): Only clips from this show. The name must match exactly.
- Day of the week (`day_of_week`, number): Only broadcasts on this day, as a number: 0 for Sunday through to 6 for Saturday (7 also means Sunday). From 0 to 7.
- How far back (`timespan`, text): How far back to chart. Leave empty for the last 2 years. GDELT's AI television timeline only answers for a window of about two years or more, so those are the choices; the chart still runs up to the present. One of: `2y` (Last 2 years), `3y` (Last 3 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Combine all stations (`combine_stations`, true/false): Merge every station into one line instead of drawing one line per station.
- Smoothing (`smoothing`, number): Average each point with the ones around it to flatten day-to-day noise, from 0 (off) to 30 points. From 0 to 30.

**Outputs**

- `date_resolution` (text)
- `empty_series_omitted` (number)
- `note` (text)
- `query` (text)
- `series` (list)
- `series_count` (number)

**Example output**

```json
{
  "date_resolution": "day",
  "empty_series_omitted": 0,
  "query": "station:CNN visual:\"flag\"",
  "series": [
    {
      "point_count": 2,
      "points": [
        {
          "date": "2026-08-21T12:00:00Z",
          "value": 2305
        },
        {
          "date": "2026-08-22T12:00:00Z",
          "value": 1415
        }
      ],
      "series": ""
    }
  ],
  "series_count": 1
}
```

### List AI television stations

List the stations covered by GDELT's AI television annotations, with the dates their coverage runs between. Far fewer stations are annotated than are captioned, and every AI television search has to name one. Takes no inputs.

**Inputs**: None.

**Outputs**

- `count` (number)
- `stations` (list)

**Example output**

```json
{
  "count": 2,
  "stations": [
    {
      "Label": "ABC",
      "LabelLong": "ABC (KGO) (7/15/2010 - Now)",
      "StationID": "KGO"
    },
    {
      "Label": "CNN",
      "LabelLong": "CNN (1/1/2020 - Now)",
      "StationID": "CNN"
    }
  ]
}
```

### List television stations

List every television station GDELT monitors, with its market, its network, and the dates its coverage runs between. Use it to find the exact station code for a television search. Takes no inputs.

**Inputs**: None.

**Outputs**

- `count` (number)
- `stations` (list)

**Example output**

```json
{
  "count": 2,
  "stations": [
    {
      "Description": "CNN",
      "EndDate": "2024-10-10T23:59:59Z",
      "Market": "National",
      "Network": "CNN",
      "StartDate": "2009-07-02T00:00:00Z",
      "StationID": "CNN"
    },
    {
      "Description": "ABC (KGO San Francisco)",
      "EndDate": "2024-10-10T23:59:59Z",
      "Market": "San Francisco",
      "Network": "ABC",
      "StartDate": "2010-07-15T00:00:00Z",
      "StationID": "KGO"
    }
  ]
}
```

### List what TV said and showed

List the concepts named in a station's closed captions, or the objects and scenes a vision model saw on screen. The values it returns are exactly what the caption-concept and shown-on-screen filters take, so use it to discover what to chart next.

**Inputs**

- Annotation layer (`source`, text): Which layer of annotation to list. One of: `caption_concepts` (Concepts named in the closed captions), `visual_labels` (Objects and scenes seen on screen). Default: `caption_concepts`.
- Station (`station`, text, required): Which station to search. Required: GDELT's AI television search only runs against named stations.
- Search words (`query`, text): Words to look for across every annotation layer at once. For a specific layer, use the four fields below instead. Can be left empty when one of those is filled in.
- Spoken on air (`spoken_words`, text): Words spoken aloud, from the machine transcript. Up to five words.
- In the closed captions (`closed_captions`, text): Words as they appeared in the station's own closed captions.
- Written on screen (`onscreen_text`, text): Text recognised on screen (a chyron, a caption, a sign). Up to five words.
- Shown on screen (`visual_label`, text): Something a vision model saw in the picture, for example 'flag' or 'crowd'. Use 'List what TV said and showed' to see the labels available.
- Show (`show`, text): Only clips from this show. The name must match exactly.
- Day of the week (`day_of_week`, number): Only broadcasts on this day, as a number: 0 for Sunday through to 6 for Saturday (7 also means Sunday). From 0 to 7.
- How far back (`timespan`, text): How far back to search. Leave empty to search the last 5 years. GDELT's television archive runs from July 2009 to October 2024, so a short window finds nothing. Use the two date fields below to search an exact stretch of it. One of: `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), `1y` (Last year), `2y` (Last 2 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.

**Outputs**

- `count` (number)
- `entities` (list)
- `query` (text)
- `source` (text)

**Example output**

```json
{
  "count": 2,
  "entities": [
    {
      "label": "U.S.",
      "mid": "/m/09c7w0"
    },
    {
      "label": "WHITE HOUSE",
      "mid": "/m/081sq"
    }
  ],
  "query": "station:CNN president",
  "source": "CapNlpEntityDetails"
}
```

### List words said alongside a topic on TV

List the words spoken most often in the clips that match a television search, which shows what the coverage of a topic was actually about.

**Inputs**

- Search words (`query`, text): The words to look for in the closed captions, for example 'interest rates'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when a station, market, network or show is chosen below.
- Station (`station`, text): Only clips from this station, for example CNN.
- Market (`market`, text): Only clips from stations in this market. 'National' is the national networks; the rest are individual cities.
- Network (`network`, text): Only clips from this network's stations, for example CBS. A network covers all of its local affiliates at once.
- Show (`show`, text): Only clips from this show. The name must match exactly, for example 'Anderson Cooper 360'.
- Also said nearby (`context`, text): Only clips where this also comes up within about fifteen seconds of the search words.
- How far back (`timespan`, text): How far back to search. Leave empty to search the last 5 years. GDELT's television archive runs from July 2009 to October 2024, so a short window finds nothing. Use the two date fields below to search an exact stretch of it. One of: `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), `1y` (Last year), `2y` (Last 2 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.

**Outputs**

- `count` (number)
- `note` (text)
- `query` (text)
- `words` (list)

**Example output**

```json
{
  "count": 2,
  "query": "climate market:\"National\"",
  "words": [
    {
      "count": 100.0,
      "label": "Climate"
    },
    {
      "count": 37.0753,
      "label": "Change"
    }
  ]
}
```

### Rank television stations or shows

See which stations or which shows covered a topic most, as a ranked list. Answers questions like which network talked about something the most.

**Inputs**

- Rank by (`group_by`, text): Whether to rank stations or individual shows. One of: `station` (By station), `show` (By show). Default: `station`.
- Search words (`query`, text): The words to look for in the closed captions, for example 'interest rates'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when a station, market, network or show is chosen below.
- Station (`station`, text): Only clips from this station, for example CNN.
- Market (`market`, text): Only clips from stations in this market. 'National' is the national networks; the rest are individual cities.
- Network (`network`, text): Only clips from this network's stations, for example CBS. A network covers all of its local affiliates at once.
- Show (`show`, text): Only clips from this show. The name must match exactly, for example 'Anderson Cooper 360'.
- Also said nearby (`context`, text): Only clips where this also comes up within about fifteen seconds of the search words.
- How far back (`timespan`, text): How far back to search. Leave empty to search the last 5 years. GDELT's television archive runs from July 2009 to October 2024, so a short window finds nothing. Use the two date fields below to search an exact stretch of it. One of: `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), `1y` (Last year), `2y` (Last 2 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.

**Outputs**

- `count` (number)
- `group_by` (text)
- `note` (text)
- `query` (text)
- `results` (list)

**Example output**

```json
{
  "count": 2,
  "group_by": "StationChart",
  "query": "climate market:\"National\"",
  "results": [
    {
      "count": 0.6519,
      "station": "CSPAN"
    },
    {
      "count": 0.3367,
      "station": "CNN"
    }
  ]
}
```

### Search news articles

Search worldwide online news coverage in 65 languages, back to 2017. Match on words, a GDELT theme, the country or language the story was published in, the website it came from, or how positive or negative it is. Each result has the article's title, link, publication time, outlet, language and country.

**Inputs**

- Search words (`query`, text): The words to search for, for example 'wildfire evacuation'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when at least one filter below is set.
- Theme (`theme`, text): Only coverage tagged with this GDELT theme, for example 'NATURAL_DISASTER_FLOOD'. Themes are GDELT's own topic labels; the list is the most-used ones, each showing how often it appears.
- Published in (`source_country`, text): Only coverage published in this country. This is where the outlet is, not what the story is about.
- Written in (`source_language`, text): Only coverage written in this language. GDELT machine-translates all of them, so English search words still match.
- Only these websites (`domains`, text): Only coverage from these websites, as a comma-separated list of domains, for example 'bbc.com, reuters.com'.
- Leave out these websites (`exclude_domains`, text): Leave out coverage from these websites, as a comma-separated list of domains.
- Tone above (`tone_greater_than`, number): Only coverage more positive than this. Tone runs from about -10 (extremely negative) to +10 (extremely positive), with most news between -5 and +5. Try 2 for positive coverage. From -100 to 100.
- Tone below (`tone_less_than`, number): Only coverage more negative than this. Try -5 for strongly negative coverage. From -100 to 100.
- Strength of feeling above (`tone_absolute_greater_than`, number): Only coverage this emotive, whichever direction it leans. Try 10 for the most charged reporting on a topic, positive or negative. From 0 to 100.
- Words close together (`near_words`, text): Only coverage where these words appear near each other, for example 'trade tariff'. Set how near with the field below.
- Within how many words (`near_distance`, number): How many words apart they may be. Defaults to 10. From 1 to 250.
- Word repeated (`repeat_word`, text): Only coverage that says this word several times, which finds articles genuinely about it rather than ones mentioning it in passing.
- At least how many times (`repeat_times`, number): How many times it must appear. Defaults to 2. From 2 to 100.
- How far back (`timespan`, text): How far back to search. Leave empty for GDELT's default of the last 3 months. Use the two date fields below instead for an exact window. One of: `1h` (Last hour), `6h` (Last 6 hours), `12h` (Last 12 hours), `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), and 3 more.
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Order (`sort_by`, text): What order to return the articles in. One of: `relevance` (Most relevant first), `newest` (Newest first), `oldest` (Oldest first), `most_positive` (Most positive tone first), `most_negative` (Most negative tone first).
- How many to return (`max_records`, number): How many articles to return, from 1 to 250. Defaults to 75. From 1 to 250.

**Outputs**

- `articles` (list)
- `count` (number)
- `query` (text)

**Example output**

```json
{
  "articles": [
    {
      "domain": "bbc.com",
      "language": "English",
      "seendate": "2026-08-22T14:15:00Z",
      "socialimage": "https://ichef.bbci.co.uk/news/1024/example.jpg",
      "sourcecountry": "United Kingdom",
      "title": "Severe flood warnings issued across the south coast",
      "url": "https://www.bbc.com/news/articles/example-flood-warning",
      "url_mobile": ""
    }
  ],
  "count": 1,
  "query": "flood sourcecountry:UK"
}
```

### Search sentences in the news

Find the individual sentences a phrase appears in, rather than whole articles: every search word has to land in the same sentence, and what comes back is that sentence plus the ones either side of it. Good for reading what was actually said about something. Covers the past 72 hours only.

**Inputs**

- Search words (`query`, text): The words to search for, for example 'wildfire evacuation'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when at least one filter below is set.
- Only these websites (`domains`, text): Only coverage from these websites, as a comma-separated list of domains, for example 'bbc.com, reuters.com'.
- Leave out these websites (`exclude_domains`, text): Leave out coverage from these websites, as a comma-separated list of domains.
- Words close together (`near_words`, text): Only coverage where these words appear near each other, for example 'trade tariff'. Set how near with the field below.
- Within how many words (`near_distance`, number): How many words apart they may be. Defaults to 10. From 1 to 250.
- Word repeated (`repeat_word`, text): Only coverage that says this word several times, which finds articles genuinely about it rather than ones mentioning it in passing.
- At least how many times (`repeat_times`, number): How many times it must appear. Defaults to 2. From 2 to 100.
- How far back (`timespan`, text): How far back to search. Leave empty for the last 24 hours. This search only holds the past 72 hours. One of: `15min` (Last 15 minutes), `1h` (Last hour), `6h` (Last 6 hours), `12h` (Last 12 hours), `24h` (Last 24 hours), `48h` (Last 2 days), `72h` (Last 3 days (the most this search holds)).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Quotes only (`quotes_only`, true/false): Return only sentences that are direct quotations, so you get what someone said rather than what a reporter wrote.
- Language (`search_language`, text): Only sentences in this language. Leave empty to search every language.
- Order (`sort_by`, text): What order to return the sentences in. One of: `relevance` (Most relevant first), `newest` (Newest first), `oldest` (Oldest first).
- How many to return (`max_records`, number): How many sentences to return, from 1 to 200. Defaults to 75. From 1 to 200.

**Outputs**

- `count` (number)
- `query` (text)
- `sentences` (list)

**Example output**

```json
{
  "count": 1,
  "query": "\"interest rates\"",
  "sentences": [
    {
      "context": "The decision was unanimous. Policymakers said interest rates would stay where they are until inflation falls further. Markets had expected a cut.",
      "domain": "reuters.com",
      "isquote": 0,
      "language": "ENGLISH",
      "seendate": "2026-08-23T09:00:00Z",
      "sentence": "Policymakers said interest rates would stay where they are until inflation falls further.",
      "title": "Central bank holds rates steady",
      "url": "https://www.reuters.com/markets/example-rates"
    }
  ]
}
```

### Search television news clips

Search the closed captions of US and international television news and get the matching fifteen-second clips, each with its station, show, air time, a snippet of what was said, and a link to watch it in the Internet Archive. The archive runs from July 2009 to October 2024.

**Inputs**

- Search words (`query`, text): The words to look for in the closed captions, for example 'interest rates'. Put a phrase in double quotes to match it exactly, write (a OR b) to match either, and put a minus in front of a word to leave it out. Can be left empty when a station, market, network or show is chosen below.
- Station (`station`, text): Only clips from this station, for example CNN.
- Market (`market`, text): Only clips from stations in this market. 'National' is the national networks; the rest are individual cities.
- Network (`network`, text): Only clips from this network's stations, for example CBS. A network covers all of its local affiliates at once.
- Show (`show`, text): Only clips from this show. The name must match exactly, for example 'Anderson Cooper 360'.
- Also said nearby (`context`, text): Only clips where this also comes up within about fifteen seconds of the search words.
- How far back (`timespan`, text): How far back to search. Leave empty to search the last 5 years. GDELT's television archive runs from July 2009 to October 2024, so a short window finds nothing. Use the two date fields below to search an exact stretch of it. One of: `24h` (Last 24 hours), `3d` (Last 3 days), `1w` (Last week), `2w` (Last 2 weeks), `1m` (Last month), `3m` (Last 3 months), `6m` (Last 6 months), `1y` (Last year), `2y` (Last 2 years), `5y` (Last 5 years), `10y` (Last 10 years), `20y` (The whole archive).
- From (`start_time`, date and time): Search from this date and time (UTC) instead of using 'How far back'. Leave both date fields empty to use 'How far back'.
- To (`end_time`, date and time): Search up to this date and time (UTC). Only used alongside 'From'; leave it empty to search from 'From' up to now.
- Order (`sort_by`, text): What order to return the clips in. One of: `relevance` (Most relevant first), `newest` (Newest first), `oldest` (Oldest first).
- How many to return (`max_records`, number): How many clips to return, from 1 to 3,000. Defaults to 50. From 1 to 3000.

**Outputs**

- `clips` (list)
- `count` (number)
- `note` (text)
- `query` (text)

**Example output**

```json
{
  "clips": [
    {
      "date": "2024-09-10T01:15:30Z",
      "ia_show_id": "CNNW_20240910_010000",
      "preview_url": "https://archive.org/details/CNNW_20240910_010000#start/930/end/965",
      "show": "Anderson Cooper 360",
      "snippet": "\u2026the Federal Reserve signalled that interest rates would stay higher for longer\u2026",
      "station": "CNN"
    }
  ],
  "count": 1,
  "query": "\"interest rates\" station:CNN"
}
```