Skip to main content
GET
/
api
/
v1
/
entity-geg
Get GEG Entity Profile
curl --request GET \
  --url https://gdeltcloud.com/api/v1/entity-geg \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "entity": {
    "canonical_name": "<string>",
    "display_name": "<string>",
    "wikipedia_url": "<string>",
    "type": "<string>",
    "total_articles": 123,
    "total_mentions": 123,
    "avg_salience_overall": 123,
    "last_seen": "2023-12-25"
  },
  "linked_stories": [
    {
      "cluster_id": "<string>",
      "cluster_label": "<string>",
      "category": "<string>",
      "scope": "local",
      "time_bucket": "2023-11-07T05:31:56Z",
      "cluster_article_count": 123
    }
  ],
  "co_occurrences": [
    {
      "related_name": "<string>",
      "related_type": "person",
      "co_occurrence_count": 123,
      "avg_combined_salience": 123,
      "last_seen": "2023-12-25"
    }
  ],
  "timeline": [
    {
      "date": "2023-12-25",
      "total_articles": 123,
      "avg_salience": 123,
      "avg_sentiment": 123
    }
  ],
  "filters": {
    "date": "<string>",
    "start_date": "<string>",
    "days": 123,
    "language": "<string>",
    "category": "<string>",
    "scope": "<string>",
    "detail": "<string>",
    "limit": 123,
    "offset": 123
  },
  "metadata": {
    "execution_time_ms": 123,
    "total_articles_in_window": 123,
    "total_stories": 123,
    "returned_stories": 123,
    "has_more": true
  }
}

Authorizations

Authorization
string
header
required

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

Query Parameters

canonical_name
string
required

Entity canonical name in lowercase (e.g. 'donald trump', 'elon musk').

Example:

"donald trump"

type
enum<string>
required

Entity type.

Available options:
person,
organization
date
string<date>

Anchor/end date for the lookback window (YYYY-MM-DD). Defaults to today UTC.

Example:

"2025-02-20"

days
integer
default:1

Lookback window in days from date. Default 1, max 30.

Required range: 1 <= x <= 30
Example:

7

detail
enum<string>
default:full

Response detail level. summary (~300 tokens): entity basics (name, type, wiki_url, total_articles), 3 story ref cards (cluster_id + label + category + scope + count), 10 co-occ ref cards (name, type, count). No timeline. standard (~1200 tokens): full entity master, 20 story ref cards (+ time_bucket), 25 co-occ ref cards (+ salience, last_seen), timeline. full (~1500 tokens, default): full entity master, paginated story ref cards, 50 co-occ ref cards, timeline.

Available options:
summary,
standard,
full
limit
integer
default:10

Number of linked story clusters to return. Default 10, max 50.

Required range: 1 <= x <= 50
offset
integer
default:0

Story cluster pagination offset. Pass offset=10 for page 2.

Required range: x >= 0
Example:

10

language
string

Filter articles by source language (e.g. 'English', 'Spanish', 'French').

Example:

"English"

category
enum<string>

Filter linked stories by topic category.

Available options:
conflict_security,
politics_governance,
crime_justice,
economy_business,
science_health,
disaster_emergency,
society_culture,
technology
scope
enum<string>

Filter linked stories by geographic scope.

Available options:
local,
national,
global

Response

Success

success
boolean
entity
object

Entity master record. Summary returns lean subset (name, display_name, wiki_url, type, total_articles); standard/full return all fields.

linked_stories
object[]

Compact cluster reference cards. Summary: 3 cards (cluster_id, label, category, scope, count). Standard: 20 cards (+ time_bucket). Full: paginated cards (+ time_bucket). Use media-events/cluster to hydrate any story.

co_occurrences
object[]

Compact entity reference cards for co-occurring entities. Summary: 10 cards (name, type, count). Standard: 25 cards (+ salience, last_seen). Full: 50 cards (+ salience, last_seen). Use entity-geg to hydrate any entity.

timeline
object[]

Daily activity timeline (standard/full only). Omitted in summary.

filters
object
metadata
object