Skip to main content
GET
/
api
/
v1
/
top-entities
Top Entities by Coverage
curl --request GET \
  --url https://gdeltcloud.com/api/v1/top-entities \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "entities": [
    {
      "canonical_name": "<string>",
      "type": "person",
      "wikipedia_url": "<string>",
      "total_articles": 123,
      "total_mentions": 123
    }
  ],
  "filters": {
    "type": "<string>",
    "days": 123,
    "date": "<string>",
    "start_date": "<string>",
    "limit": 123
  },
  "metadata": {
    "entity_count": 123,
    "execution_time_ms": 123
  }
}

Authorizations

​
Authorization
string
header
required

API key format: gdelt_sk_<64-hex-chars>. Generate in Dashboard → Settings → API Keys.

Query Parameters

​
type
enum<string>

Filter to only persons or only organizations. Omit to return both.

Available options:
person,
organization
​
days
integer
default:1

Lookback window in days from date. Default 1 = today only.

Required range: 1 <= x <= 30
​
date
string<date>

Anchor/end date (YYYY-MM-DD). Defaults to today UTC.

Example:

"2025-03-01"

​
limit
integer
default:20

Number of entities to return. Default 20, max 100.

Required range: 1 <= x <= 100
​
search
string

Case-insensitive substring match on canonical_name. Use to discover entities by partial name before calling entity-geg for a full profile. Examples: 'trump' matches 'donald trump', 'apple' matches 'apple inc.', 'fed' matches 'federal reserve'. Filtered results are still ranked by article coverage volume.

Example:

"apple"

Response

Success

​
success
boolean
​
entities
object[]
​
filters
object
​
metadata
object