curl --request GET \
--url https://gdeltcloud.com/api/v2/search \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/search"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"query": "Petrobras",
"count": 1,
"data": [
{
"entity_id": "e_1a2b3c4d5e6f7a8b",
"name": "Petróleo Brasileiro S.A. — Petrobras",
"entity_type": "organization",
"score": 0.987,
"match_type": "alias",
"match_reason": "Matched the common organization name Petrobras.",
"country_iso3": [
"BRA"
],
"sources": {
"news": true,
"sec": true,
"gem": true,
"sanctions": false,
"china": false,
"wiki": true,
"epoch": false,
"gov": false
},
"identifiers": {
"ticker": [
"PBR"
],
"us_sec_cik": [
"1119639"
]
}
}
],
"applied_filters": {
"q": "Petrobras",
"type": "organization",
"limit": 10
}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}Unified cross-source entity search
Resolve a name, alias, or acronym into ranked entity candidates before creating a Monitor or calling an entity-conditioned endpoint. q is the canonical query parameter; choose a result and reuse its entity_id for reporting. Facility candidates retain facility_id for facility context; ownership and proximity are distinct from identity. The registry and osint universes instead return source records; a null entity_id means that record has no spine link and does not establish news coverage. Native non-Latin-script matching is not yet complete: for Cyrillic, Chinese and other non-Latin names, use a common Romanized or English spelling for now (for example Gazprom rather than Газпром, or Beijing rather than 北京). Native-script queries outside supported scripts return an explicit error. Candidate source failures return retryable ENTITY_SEARCH_UNAVAILABLE; a failed read never establishes the absence of a match.
curl --request GET \
--url https://gdeltcloud.com/api/v2/search \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/search"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"query": "Petrobras",
"count": 1,
"data": [
{
"entity_id": "e_1a2b3c4d5e6f7a8b",
"name": "Petróleo Brasileiro S.A. — Petrobras",
"entity_type": "organization",
"score": 0.987,
"match_type": "alias",
"match_reason": "Matched the common organization name Petrobras.",
"country_iso3": [
"BRA"
],
"sources": {
"news": true,
"sec": true,
"gem": true,
"sanctions": false,
"china": false,
"wiki": true,
"epoch": false,
"gov": false
},
"identifiers": {
"ticker": [
"PBR"
],
"us_sec_cik": [
"1119639"
]
}
}
],
"applied_filters": {
"q": "Petrobras",
"type": "organization",
"limit": 10
}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Use name for stable alphabetical public-official browsing with universe=osint and holds_office=true. Default when q is absent. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Number of records to skip before this page. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 0Canonical search text: a name, alias, or acronym. Required except when browsing public officials with universe=osint and holds_office=true. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Optional identity type used to narrow ambiguous candidates. Conflicting linked types retain entity_type=entity and type_evidence; a filtered result includes a conflict only when the requested type is a published possibility. facility searches the existing facility directory and returns facility_id, not an invented entity ID. Source entitlements apply. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#search_entity_type
person, organization, place, facility Known country association from source records, not an assertion of headquarters, citizenship, or reporting location. Accepts country names, ISO-2 or ISO-3; comma-separate for OR. Use country_match=strict for candidates with known matching evidence. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
strict requires known matching source country association; include_unknown also returns candidates with no country evidence. Recommended requests explicitly send strict. Omission retains include_unknown compatibility. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#search_country_match
strict, include_unknown Geographic region whose member countries define the scope. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region
Middle East, Northern Africa, Western Africa, Eastern Africa, Middle Africa, Southern Africa, Eastern Europe, South Asia, Southeast Asia, East Asia, Central Asia, Northern America, Central America, Caribbean Continent whose member countries define the geographic scope. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent
Africa, Asia, Europe, North America, South America, Oceania Retain source article image URLs on returned cards when available. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Number of records to return on this page; pagination describes how to continue. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 50Search all merged entities, news entities, reference entities, raw GLEIF registry records, or OSINT list and office-holder records. The registry and osint lanes return source records with nullable entity_id; they do not establish news coverage. Source entitlements apply. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#search_universe
all, news, reference, registry, osint Return only candidates linked to a canonical registry identity. Available for all, news and reference entity searches. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Only politicians: entities that hold or have held a published public office (sources.offices), or on universe=osint only office-holder records. A ROLE filter, not a type — an office-holder is a person. Requires can_use_offices (403 PLAN_REQUIRED otherwise) and is not applicable to universe=registry (legal entities only; 400). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Response
Ranked entity-name candidates. Select a terminal e_… entity_id before creating an entity Monitor; present ambiguous candidates rather than automatically choosing a weak match.
Entity candidates for all/news/reference; source records for osint/registry. Reference records can have a null entity_id and do not imply news coverage.
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Present for alphabetical public-official browsing. Continue with next_offset; null means the directory is exhausted.
Show child attributes
Show child attributes
Source-lane provenance and entitlement scope for reference universes.
Show child attributes
Show child attributes