List Offices
Public political offices — legislative seats, cabinet posts, heads of state and government, courts, security and financial offices and IGO posts — one row per office, dataset-independent, with holder counts. Scope and branch are derived from the source’s gov.* topics so they are closed, filterable vocabularies. holders_current is NULL, never 0, when no source asserts currency for the office. Actor context for geopolitical analysis; NOT a PEP or sanctions-screening tool.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Rows per page. Default 25, max 100. 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 <= 100Opaque pagination cursor taken from the previous response's pagination.next_cursor. Also accepts: offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Include complete country facets over the served office registry, independent of pagination and country/name filters. Holder counts are terms across offices, not distinct people. Null facets mean unavailable.
Country of the office (ISO-3, ISO-2, or a name; comma-separate for OR). IGO / supranational posts carry no country and never match a country filter — use scope=international for those. Also accepts: country_iso3. Matched case-insensitively. 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#country
Level of government: national, subnational (state / province / municipality) or international (IGO and supranational posts). Derived from the source's topics; an office with no scope topic is national. Matched case-insensitively. Full value list: https://docs.gdeltcloud.com/reference/enums#office_scope
national, subnational, international Branch of government. head (head of state / government) wins over executive when a office carries both topics. other is sendable and returns the offices whose topics name no recognised branch. Also accepts: topic. Matched case-insensitively. Full value list: https://docs.gdeltcloud.com/reference/enums#office_branch
legislative, executive, head, judicial, security, financial, igo, other The legislature / ministry / court the office belongs to. A spine e_… id matches the resolved organization exactly (the arbiter family, so a merged-away alias still matches); any other value is a case-insensitive substring match on the organization name as published. Also accepts: organization_entity_id, org. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Case-insensitive substring match over the office name. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results keep the sort order, not a relevance ranking, so a query matching more rows than limit returns the first page of that order — narrow with country. Also accepts: search. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
true restricts to offices with at least one office-holder on record (any status); false to offices we know only as an office, with nobody recorded in it. This counts office_holders, not asserted currency — an office whose only holders are status: unknown still has holders.
VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer "what did we know then". An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as "still in office as far as the source has published".
Ordering: name (default) · holders_desc · country. Matched case-insensitively. Full value list: https://docs.gdeltcloud.com/reference/enums#offices_sort
name, holders_desc, country