---
title: "Unified cross-source entity search"
method: GET
path: "/api/v2/search"
tags: ["Unified Search"]
---

# Unified cross-source entity search

`GET /api/v2/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.

## Query parameters

- `q` string, required
- `universe` 'all' | 'news' | 'reference'
- `country` string
- `region` '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'
- `continent` 'Africa' | 'Asia' | 'Europe' | 'North America' | 'South America' | 'Oceania'
- `type` 'person' | 'organization'
- `limit` integer

## Response `200`

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 }`.

- object
  - `success` boolean
  - `query` string
  - `count` integer — Number of entities in `data` (echoes data.length).
  - `data` object[]
    - `entity_id` string — 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` string, nullable — The spine `e_` id when the entity is in the registry-of-record, else null.
    - `name` string
    - `entity_type` 'person' | 'company' | 'organization' | 'government' | 'state_body' | 'place' | 'entity' — Normalized canonical type. `entity` is the fallback when no source carried a usable type.
    - `entity_type_raw` string — The raw per-source type string that won the vote, preserved for debugging.
    - `wikipedia_url` string, nullable
    - `score` number — Match score (higher is a stronger match).
    - `match_type` string — How the entity matched, e.g. exact_name, token_set, acronym, fuzzy_name, semantic.
    - `match_reason` string — Human-readable reason the entity matched the query.
    - `sources` object — Per-source availability for this entity. Each flag is a real JSON boolean.
      - `news` boolean
      - `sec` boolean
      - `gem` boolean
      - `sanctions` boolean
      - `china` boolean
      - `wiki` boolean
      - `epoch` boolean
    - `identifiers` object — 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.
    - `source_universes` string[] — Which universes contributed to this merged entity (media, geg_wiki, reference).
  - `applied_filters` object
    - `q` string
    - `universe` string
    - `limit` integer
    - `country` string — Resolved country name — echoed only when a country/region/continent resolved.
    - `region` string — Resolved region — echoed only when supplied and resolvable.
    - `continent` string — Resolved continent — echoed only when supplied and resolvable.
    - `country_iso3` string[] — The ISO-3 set the geo filter expanded to; present only when a country/region/continent resolved.
    - `ignored` string[]

## Other responses

- `400` — Missing/invalid query (MISSING_PARAM / QUERY_TOO_LONG)
- `401` — Missing/invalid API key
- `403` — API key disabled or access denied (`API_KEY_DISABLED`). Unified search carries no plan flag, so a plan can never 403 it.
- `500` — Server error

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/revisions/01aaa6255180/schema)