> ## 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. # Unified cross-source entity search > High-recall fuzzy + semantic entity search across EVERY entity universe — news, GEG-Wikipedia, SEC/EDGAR, Global Energy Monitor, sanctions lists, China development finance, and Epoch AI — deduplicated into ONE result per real-world entity (keyed on the canonical spine `e_` id), each with a per-source availability map and cross-source identifiers. This is a CANDIDATE LIST (not resolve-to-one): a query like `Zelensky` legitimately means several people. Available to any authenticated API key — search itself carries no plan flag. Your plan still governs the DETAIL behind a hit: sources you are not entitled to are redacted from the `sources` availability map and `identifiers` rather than blocking the search. Use this to find an entity by any name/alias/acronym without knowing which source it lives in, then jump into `/api/v2/entities/{entity_id}` for the full profile. The `q` param is canonical; `query`, `keyword`, `name`, and `search` are accepted aliases. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/search openapi: 3.0.3 info: title: GDELT Cloud API v2 version: 2.0.0 description: >- Clean v2 REST API for generated GDELT Cloud structured Events, clustered Stories, linked Entities, summaries, admin1 discovery, significance ranking, and paginated article evidence. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves. goldstein_scale is one canonical public metric, populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful. Story linked_event_count is a Story-to-Event link aggregate, not a distinct Event total. servers: - url: https://gdeltcloud.com description: Production - url: http://localhost:3000 description: Local development security: - ApiKeyAuth: [] tags: - name: Events description: Coded CAMEO+ / conflict events — search, fetch, and summarize. - name: Stories description: Clustered narratives (stories) and their articles. - name: Entities description: >- People & organizations — resolve a name to an entity, then fetch its profile and tone. - name: Geography description: Admin-1 geography lookups. - name: Energy description: Global Energy Monitor assets + ownership registry. - name: Facilities description: >- Unified physical-asset directory — GEM energy assets + World Port Index ports + Epoch AI data centers on one keyed surface, resolved to spine owners. Plan-gated (Analyst plan and up). - name: Screening and Reference description: >- Restricted-party lists, screening, and ownership-chain exposure. Plan-gated (`can_use_screening` / `can_use_exposure`). - name: China description: >- China overseas development finance (AidData GCDF). Plan-gated (`can_use_china`). - name: Media Intelligence description: >- Entity tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`) are plan-gated. Social signal remains an admin-only preview. - name: Filings description: >- SEC EDGAR filings, XBRL financials, and AI-extracted relations. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above. - name: Macro Finance description: >- FRED economic time series (catalog, point-in-time observations, releases). Plan-gated (`can_use_macro`). - name: Maritime description: >- AIS-derived vessel-flow signals across maritime chokepoints — chokepoint transits, last-known vessel positions, carriers, dwell, and AIS-dark gaps. Plan-gated (`can_use_maritime`). - name: Briefs description: Source-backed monitoring briefs. paths: /api/v2/search: get: tags: - Unified Search summary: Unified cross-source entity search description: >- High-recall fuzzy + semantic entity search across EVERY entity universe — news, GEG-Wikipedia, SEC/EDGAR, Global Energy Monitor, sanctions lists, China development finance, and Epoch AI — deduplicated into ONE result per real-world entity (keyed on the canonical spine `e_` id), each with a per-source availability map and cross-source identifiers. This is a CANDIDATE LIST (not resolve-to-one): a query like `Zelensky` legitimately means several people. Available to any authenticated API key — search itself carries no plan flag. Your plan still governs the DETAIL behind a hit: sources you are not entitled to are redacted from the `sources` availability map and `identifiers` rather than blocking the search. Use this to find an entity by any name/alias/acronym without knowing which source it lives in, then jump into `/api/v2/entities/{entity_id}` for the full profile. The `q` param is canonical; `query`, `keyword`, `name`, and `search` are accepted aliases. operationId: unified-entity-search-v2 parameters: - name: q in: query required: true schema: type: string maxLength: 200 description: >- Search text — a name, alias, or acronym. Fuzzy + semantic, so exact spelling is not required. Required. Aliases `query`, `keyword`, `name`, and `search` are accepted (first non-empty wins). - name: universe in: query required: false schema: type: string enum: - all - news - reference - registry default: all description: >- Which universes to search. `all` (default) spans every source; `news` restricts to entities seen in news coverage; `reference` restricts to the canonical spine (SEC / GEM / sanctions / China / Epoch). `registry` searches the raw GLEIF Global LEI Index (3.39M records, CC0) by legal name or LEI in its own lane: hits are legal-entity REGISTRATIONS, not evidence of news coverage. Each carries `resolved_in_spine` (whether we also cover the entity itself) and a `lei` that chains to /api/v2/gleif/entities/{lei} and /api/v2/entities/{lei}/hierarchy. Registry rows never appear under `all` or `reference`. - name: country in: query required: false schema: type: string example: Germany description: >- Optional country disambiguator, folded to one ISO-3 set through the shared `resolveCohortGeoIso3` resolver (the same layer `region`/`continent` use). Accepts a country name (`Germany`), ISO-2 (`DE`), ISO-3 (`DEU`), or alias (comma-separated list allowed). Additive — it keeps entities carrying a matching country but never drops entities that have no country (media/GEG entities usually lack one), so it narrows a common name without gutting results. An unresolvable value now returns `400 INVALID_ENUM`, consistent with the rest of the API. - name: region in: query required: false schema: type: string enum: - Africa - Asia - Middle East - Northern Africa - Western Africa - Eastern Africa - Middle Africa - Southern Africa - Europe - Eastern Europe - South Asia - Southeast Asia - East Asia - Central Asia - North America - Central America - Caribbean - South America - Oceania description: >- Additive geo disambiguator — expanded to an ISO-3 set via the same `resolveCohortGeoIso3` resolver as `country` and combinable with it. An unresolvable value returns `400 INVALID_ENUM`. - name: continent in: query required: false schema: type: string enum: - Africa - Asia - Europe - North America - South America - Oceania description: >- Additive geo disambiguator — expanded to an ISO-3 set via `resolveCohortGeoIso3`. An unresolvable value returns `400 INVALID_ENUM`. - name: type in: query required: false schema: type: string enum: - person - organization - place description: >- Optional entity type filter. `place` covers geographies (countries, cities, regions), typed from Wikidata P31 — before 2026-07-30 these were mis-filed under organization and person, so type=organization returned countries. Roles and offices are deliberately none of these three and are excluded rather than mislabelled. - name: limit in: query required: false schema: type: integer default: 10 minimum: 1 maximum: 50 description: >- Number of distinct real-world entities to return (1–50). Defaults to 10. responses: '200': description: >- A ranked list of distinct real-world entities. Each item carries the canonical entity id, an optional spine id, a normalized entity_type, a per-source availability map (`sources`), cross-source identifiers, and the universes it was matched in. Envelope: `{ success, query, count, data, applied_filters }`. content: application/json: schema: type: object properties: success: type: boolean query: type: string count: type: integer description: Number of entities in `data` (echoes data.length). data: type: array items: type: object properties: entity_id: type: string description: >- Canonical entity id — the spine `e_` id when the entity resolves into the spine, else the source candidate's own id. Feed this to `/api/v2/entities/{entity_id}`. spine_id: type: string nullable: true description: >- The spine `e_` id when the entity is in the registry-of-record, else null. name: type: string entity_type: type: string description: >- Normalized canonical type. `entity` is the fallback when no source carried a usable type. enum: - person - company - organization - government - state_body - place - entity entity_type_raw: type: string description: >- The raw per-source type string that won the vote, preserved for debugging. wikipedia_url: type: string nullable: true score: type: number description: Match score (higher is a stronger match). match_type: type: string description: >- How the entity matched, e.g. exact_name, token_set, acronym, fuzzy_name, semantic. match_reason: type: string description: Human-readable reason the entity matched the query. sources: type: object description: >- Per-source availability for this entity. Each flag is a real JSON boolean. properties: news: type: boolean sec: type: boolean gem: type: boolean sanctions: type: boolean china: type: boolean wiki: type: boolean epoch: type: boolean identifiers: type: object description: >- Cross-source identifiers keyed by id type (e.g. us_sec_cik, ticker, gem, epoch_org), each an array of values. Empty when the entity has no spine id. additionalProperties: type: array items: type: string source_universes: type: array description: >- Which universes contributed to this merged entity (media, geg_wiki, reference). items: type: string applied_filters: type: object properties: q: type: string universe: type: string limit: type: integer country: type: string description: >- Resolved country name — echoed only when a country/region/continent resolved. region: type: string description: >- Resolved region — echoed only when supplied and resolvable. continent: type: string description: >- Resolved continent — echoed only when supplied and resolvable. country_iso3: type: array items: type: string description: >- The ISO-3 set the geo filter expanded to; present only when a country/region/continent resolved. ignored: type: array items: type: string examples: example: summary: GET /api/v2/search?q=Rosneft — example response value: success: true query: Rosneft count: 1 data: - entity_id: e_1a2b3c4d5e6f7a8b spine_id: e_1a2b3c4d5e6f7a8b name: Rosneft Oil Company entity_type: company entity_type_raw: state-owned enterprise wikipedia_url: https://en.wikipedia.org/wiki/Rosneft score: 0.987 match_type: exact_name match_reason: Exact match on canonical name sources: news: true sec: false gem: true sanctions: true china: false wiki: true epoch: false identifiers: gem: - G100000112345 list_entry: - OFAC-SDN-12345 source_universes: - media - reference applied_filters: q: Rosneft universe: all limit: 10 '400': description: Missing/invalid query (MISSING_PARAM / QUERY_TOO_LONG) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing/invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- API key disabled or access denied (`API_KEY_DISABLED`). Unified search carries no plan flag, so a plan can never 403 it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: ErrorResponse: type: object properties: success: type: boolean enum: - false error: type: string code: type: string details: type: object description: >- Recoverable validation context when available, such as param, invalid_value, accepted_values, nearest_values, and a corrected example. additionalProperties: true securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````