Docs menu

GDELT API endpoint

GDELT Search API

Searches global news coverage indexed by GDELT for the required `query`, which accepts quoted phrases, `(a OR b)`, `theme:`, `tone<N` and `domain:`. Narrow with `country`, `language`, `domain`, and `timespan` or `from` and `to` (about the last 3 months are indexed). Returns up to `maxrecords` articles (default 75, max 250) with title, URL, domain, language, source country and `seen_at`.

GETapiKey0 credits/requestGDELTgdelt.searchResponseDoc/gdelt/search

Endpoint facts

Method: GET
API path: /gdelt/search
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.searchResponseDoc

GDELT News Monitoring API Try GDELT Search API in Playground GDELT API documentation

How this endpoint behaves

Source: the GDELT Project. GDELT datasets are released for unlimited and unrestricted academic, commercial, and governmental use; please credit the GDELT Project and link back to gdeltproject.org when republishing GDELT-derived data.

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Supports GDELT's own search operators: quoted phrases ("exact phrase"), boolean OR ((a OR b)), theme:NAME, tone<N / tone>N, near20:"word1 word2", repeat3:"word", domain:example.com.
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE. Accepts a GDELT-recognized country name (no spaces) or 2-letter FIPS code, e.g. unitedkingdom or uk.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE. Accepts a GDELT-recognized language name or 3-letter code, e.g. spanish or spa.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT only indexes roughly the last 3 months.
to (optional) — end of an absolute time window. Same formats as from.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc, tonedesc, toneasc.
maxrecords (optional, default 75) — rows to return. GDELT's own hard cap is 250; there is no pagination cursor beyond it.

Notable response behavior:

count is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT DOC API URL used for the call.
A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/search?maxrecords=3&query=climate
Items in articles: 3
Fields filled in every checked item: 7

Field	Filled in, of 3 checked	Values in the sample
url	3	irishtimes.com and 2 other hosts
title	3	“New era of climate obstruction requires pretending things a…” and 2 other values
seen_at	3	2026-08-19 to 2026-08-20
domain	3	“irishtimes.com” and 2 other values
language	3	“English” and 2 other values
source_country	3	“Ireland” and 2 other values
social_image_url	3	irishtimes.com and 2 other hosts

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Supports GDELT's own search operators: quoted phrases, (a OR b), theme:NAME, tone<N / tone>N, near20:\	climate change
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE. Accepts a GDELT-recognized country name (no spaces) or 2-letter FIPS code.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE. Accepts a GDELT-recognized language name or 3-letter code.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT only indexes roughly the last 3 months.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc, tonedesc, toneasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 250; there is no pagination cursor beyond it. Minimum: 1. Maximum: 250.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/search?query=climate+change&country=us&language=en&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "sort": "relevance",
    "maxrecords": 75,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change",
    "fetched_at": "2026-08-20T10:00:00Z",
    "articles": [
      {
        "url": "https://www.example.com/news/climate-report",
        "title": "Climate report warns of rising sea levels",
        "seen_at": "2026-08-19T23:00:00Z",
        "domain": "example.com",
        "language": "English",
        "source_country": "United States",
        "social_image_url": "https://www.example.com/images/social.jpg"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.searchResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.SearchResponse	No
data.articles	array	No
data.articles[].domain	string	No	example.com
data.articles[].language	string	No	English
data.articles[].seen_at	string	No	2026-08-19T23:00:00Z
data.articles[].social_image_url	string	No	https://www.example.com/images/social.jpg
data.articles[].source_country	string	No	United States
data.articles[].title	string	No	Climate report warns of rising sea levels
data.articles[].url	string	No	https://www.example.com/news/climate-report
data.count	integer	No	12
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	75
data.query	string	No	climate change
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/search?query=climate+change&country=us&language=en&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More GDELT endpoint docs GDELT News Monitoring API GDELT Context Search API documentation GDELT Timeline API documentation GDELT Tone Chart API documentation GDELT Television Concept Entities API documentation GDELT Television Search API documentation GDELT Television Show Chart API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Search API

GETapiKey0 credits/requestGDELTgdelt.searchResponseDoc/gdelt/search

Endpoint facts

Method: GET
API path: /gdelt/search
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.searchResponseDoc

GDELT News Monitoring API Try GDELT Search API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

query (required) — GDELT query string. Supports GDELT's own search operators: quoted phrases ("exact phrase"), boolean OR ((a OR b)), theme:NAME, tone<N / tone>N, near20:"word1 word2", repeat3:"word", domain:example.com.
country (optional) — convenience source-country filter, appended to the query as sourcecountry:VALUE. Accepts a GDELT-recognized country name (no spaces) or 2-letter FIPS code, e.g. unitedkingdom or uk.
language (optional) — convenience source-language filter, appended to the query as sourcelang:VALUE. Accepts a GDELT-recognized language name or 3-letter code, e.g. spanish or spa.
domain (optional) — convenience domain filter, appended to the query as domain:VALUE.
timespan (optional) — relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.
from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT only indexes roughly the last 3 months.
to (optional) — end of an absolute time window. Same formats as from.
sort (optional, default relevance) — result order. Allowed values: relevance, datedesc, dateasc, tonedesc, toneasc.
maxrecords (optional, default 75) — rows to return. GDELT's own hard cap is 250; there is no pagination cursor beyond it.

Notable response behavior:

count is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error).
source_url is the exact upstream GDELT DOC API URL used for the call.
A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/search?maxrecords=3&query=climate
Items in articles: 3
Fields filled in every checked item: 7

Field	Filled in, of 3 checked	Values in the sample
url	3	irishtimes.com and 2 other hosts
title	3	“New era of climate obstruction requires pretending things a…” and 2 other values
seen_at	3	2026-08-19 to 2026-08-20
domain	3	“irishtimes.com” and 2 other values
language	3	“English” and 2 other values
source_country	3	“Ireland” and 2 other values
social_image_url	3	irishtimes.com and 2 other hosts

Request parameters

Parameter	Type	Required	Description	Example
query	string	Yes	GDELT query string. Supports GDELT's own search operators: quoted phrases, (a OR b), theme:NAME, tone<N / tone>N, near20:\	climate change
country	string	No	Convenience source-country filter, appended to the query as sourcecountry:VALUE. Accepts a GDELT-recognized country name (no spaces) or 2-letter FIPS code.	unitedkingdom
language	string	No	Convenience source-language filter, appended to the query as sourcelang:VALUE. Accepts a GDELT-recognized language name or 3-letter code.	english
domain	string	No	Convenience domain filter, appended to the query as domain:VALUE.	bbc.com
timespan	string	No	Relative time window ending now, e.g. 1h, 2d, 1w, 3m. Cannot be combined with from/to.	1w
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan; GDELT only indexes roughly the last 3 months.	2026-08-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
sort	string	No	Result order. Allowed values: relevance, datedesc, dateasc, tonedesc, toneasc.
maxrecords	integer	No	Rows to return. GDELT's own hard cap is 250; there is no pagination cursor beyond it. Minimum: 1. Maximum: 250.
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/search?query=climate+change&country=us&language=en&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "climate change",
    "sort": "relevance",
    "maxrecords": 75,
    "count": 1,
    "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change",
    "fetched_at": "2026-08-20T10:00:00Z",
    "articles": [
      {
        "url": "https://www.example.com/news/climate-report",
        "title": "Climate report warns of rising sea levels",
        "seen_at": "2026-08-19T23:00:00Z",
        "domain": "example.com",
        "language": "English",
        "source_country": "United States",
        "social_image_url": "https://www.example.com/images/social.jpg"
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.searchResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.SearchResponse	No
data.articles	array	No
data.articles[].domain	string	No	example.com
data.articles[].language	string	No	English
data.articles[].seen_at	string	No	2026-08-19T23:00:00Z
data.articles[].social_image_url	string	No	https://www.example.com/images/social.jpg
data.articles[].source_country	string	No	United States
data.articles[].title	string	No	Climate report warns of rising sea levels
data.articles[].url	string	No	https://www.example.com/news/climate-report
data.count	integer	No	12
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.maxrecords	integer	No	75
data.query	string	No	climate change
data.sort	string	No	relevance
data.source_url	string	No	https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/search?query=climate+change&country=us&language=en&sort=relevance" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

GDELT Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Search API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related