Skip to main content

​
Overview

get_top_entities returns the top people and organizations by total article coverage across the GDELT Cloud news corpus. Results draw from the GEG (GDELT Entity Graph) — GDELT’s entity extraction pipeline that identifies and resolves named entities from millions of global news articles daily. Use this tool to quickly surface the most newsworthy actors in a given time window, optionally filtered by entity type or a search query. Each result includes a Wikipedia URL (when available) enabling deeper research.

​
Parameters

ParameterTypeDefaultDescription
daysinteger7Lookback window in days from date. Max 30.
datestringtoday UTCAnchor/end date in YYYY-MM-DD format.
limitinteger20Number of entities to return (max 100).
typeenum—Filter to 'person' or 'organization'. If omitted, returns both.
searchstring—Filter by entity name (substring match, case-insensitive). Useful for checking coverage of a specific person or organization (e.g. 'Trump', 'NATO').

​
Data Structure

Each returned entity contains: 
{
  "canonical_name": "Donald Trump",
  "entity_type": "person",
  "wikipedia_url": "https://en.wikipedia.org/wiki/Donald_Trump",
  "total_articles": 14823,
  "total_mentions": 38402
}
FieldDescription
canonical_nameResolved canonical entity name (Wikipedia-normalized where possible).
entity_type'person' or 'organization'.
wikipedia_urlWikipedia page URL, or null if no Wikipedia match was found.
total_articlesNumber of distinct articles mentioning this entity in the time window.
total_mentionsTotal raw mention count (an entity may appear multiple times in one article).

​
Usage Patterns

​
Who is dominating the news?

get_top_entities(days=7)
→ Top 20 people and organizations by article count this week

​
Focus on specific entity type

get_top_entities(days=7, type='organization')
→ Top organizations in the news this week (governments, companies, international bodies)

​
Lookup a specific entity

get_top_entities(days=30, search='Federal Reserve')
→ Check how much coverage the Federal Reserve received this month

​
Example queries

get_top_entities(
    days=7,
    limit=20
)

​
Common Use Cases

  • “Who are the most newsworthy people right now?” → type='person', days=7
  • “Which organizations are dominating coverage?” → type='organization', days=7
  • “How much coverage did Trump get this month?” → search='Trump', days=30
  • “What were the top entities during the UN General Assembly?” → days=7, date='2025-09-26'
  • “Find the top 50 entities globally this week” → days=7, limit=50

​
Notes on Entity Resolution

  • Entities are extracted from news articles using GDELT’s NLP pipeline and resolved to Wikipedia canonical names where possible.
  • total_articles counts distinct articles; total_mentions counts all occurrences including repeated references within a single article.
  • The same real-world entity may appear under slightly different names if disambiguation is uncertain. Use search to check for variants.
  • wikipedia_url is null for entities without a confident Wikipedia match (common for local officials, minor organizations).

get_entity

Deep-dive into a single entity — co-occurrences, related stories, full coverage history

get_media_events

Find news story clusters — filter by entity to see what stories an actor is associated with

get_conflict_events

See conflict events involving specific actors