Skip to main content
GET
/
api
/
v1
/
top-entities
Top Entities by Coverage
curl --request GET \
  --url http://localhost:3000/api/api/v1/top-entities
{
  "success": true,
  "entities": [
    {
      "canonical_name": "<string>",
      "type": "person",
      "wikipedia_url": "<string>",
      "total_articles": 123,
      "total_mentions": 123,
      "entity_url": "<string>"
    }
  ],
  "filters": {
    "type": "<string>",
    "days": 123,
    "date": "<string>",
    "start_date": "<string>",
    "limit": 123
  },
  "metadata": {
    "entity_count": 123,
    "execution_time_ms": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

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