---
title: "Aggregate search across every code property"
method: GET
path: "/countries/v5/code"
tags: ["Aggregates"]
---

# Aggregate search across every code property

`GET /countries/v5/code`

Searches the q value across alpha_2, alpha_3, ccn3, fips, gec, fifa, and cioc simultaneously. Useful when the caller has a code but doesn't know which standard it belongs to.

## Query parameters

- `q` string, required
- `limit` integer
- `offset` integer
- `response_fields` string
- `response_fields_omit` string
- `pretty` boolean

## Response `200`

Paginated list of countries.

- CountryListResponse
  - `data` object, required
    - `objects` Country[], required
      - `uuid` string, uuid — Stable per-country identifier independent of code revisions.
      - `names` object
        - `common` string
        - `official` string
        - `alternates` string[]
        - `native` object — Map of ISO 639-3 language code to native name pair.
        - `translations` object — Map of ISO 639-3 language code to translated name pair. Heavy field; trim with response_fields_omit when not needed.
      - `codes` object
        - `alpha_2` string — ISO 3166-1 alpha-2 (two-letter) code.
        - `alpha_3` string — ISO 3166-1 alpha-3 (three-letter) code.
        - `ccn3` string — ISO 3166-1 numeric (three-digit) code.
        - `fips` string — FIPS 10-4 country code.
        - `gec` string — GEC code.
        - `fifa` string — FIFA code.
        - `cioc` string — International Olympic Committee code.
      - `capitals` object[]
        - `name` string
        - `coordinates` object
          - `lat` number
          - `lng` number
        - `attributes` object — Role flags for this capital. Multi-capital countries set whichever flags fit each city; single-capital countries set primary.
          - `primary` boolean
          - `constitutional` boolean
          - `administrative` boolean
          - `executive` boolean
          - `legislative` boolean
          - `judicial` boolean
      - `continents` string[]
      - `region` string
      - `subregion` string
      - `landlocked` boolean
      - `coordinates` object
        - `lat` number
        - `lng` number
      - `area` object
        - `kilometers` number
        - `miles` number
      - `borders` string[]
      - `timezones` string[]
      - `government_type` string
      - `leaders` union[] — Heads of state and government. Paid-plan field, and the gating shows up two ways. As a response field it stays an array on every plan: on a plan that doesn't include it the array holds exactly one LeadersNotice element ({message, sample}) rather than leader records, so check for a message key before treating an entry as a leader. As a search, filter, or lookup target it returns HTTP 403 on those plans instead.
        - union
          - Leader — A single head of state or government.
            - `assets` object[]
              - …
            - `attributes` object
              - …
            - `links` object
              - …
            - `name` string, nullable
            - `title` string, nullable
          - LeadersNotice — The single element the leaders array carries on a plan that doesn't include the field, in place of leader records.
            - `message` string, required — Explains that leaders is paid-plan only and links to the plans page.
            - `sample` string, uri, required — URL of a hosted sample payload showing the shape a paid plan receives.
      - `flag` object
        - `emoji` string
        - `unicode` string
        - `html_entity` string
        - `description` string
        - `url_png` string, uri
        - `url_svg` string, uri
        - `colors` object
          - `dominant` string — Dominant flag color as a hex string.
          - `prominent` string — Most prominent flag color (the single color covering the largest share of the flag's area) as a hex string.
          - `palette` object[] — Flag color palette as an array of {hex, proportion} maps, each pairing a hex color with the share (0-1) of the flag it covers.
            - `hex` string
            - `proportion` number
          - `swatches` object — Flag semantic color swatches keyed by role. All six roles are always present; a role the flag has no matching color for is null.
            - `vibrant` string, nullable
            - `muted` string, nullable
            - `dark_vibrant` string, nullable
            - `dark_muted` string, nullable
            - `light_vibrant` string, nullable
            - `light_muted` string, nullable
      - `currencies` object[] — Currencies used by the country.
        - `code` string
        - `name` string
        - `symbol` string
      - `population` integer
      - `economy` object
        - `gini_coefficient` object — Map of year (string) to Gini value (number).
      - `demonyms` object — Map of ISO 639-3 language code to {m, f} demonym pair.
      - `languages` object[] — Languages used in the country, each with ISO 639 identifiers, BCP 47 tag, English name, and native name.
        - `iso639_1` string
        - `iso639_2t` string
        - `iso639_2b` string
        - `iso639_3` string
        - `bcp47` string
        - `name` string
        - `native_name` string
      - `calling_codes` string[]
      - `tlds` string[]
      - `cars` object
        - `driving_side` 'left' | 'right'
        - `signs` string[]
      - `postal_code` object
        - `format` string
        - `regex` string
      - `number_format` object
        - `decimal_separator` string
        - `thousands_separator` string
      - `units` object
        - `measurement_system` 'metric' | 'imperial'
        - `temperature_scale` 'Celsius' | 'Fahrenheit'
      - `memberships` object
        - `un` boolean
        - `african_union` boolean
        - `arab_league` boolean
        - `asean` boolean
        - `brics` boolean
        - `commonwealth` boolean
        - `eu` boolean
        - `eurozone` boolean
        - `g7` boolean
        - `g20` boolean
        - `nato` boolean
        - `oecd` boolean
        - `opec` boolean
        - `schengen` boolean
      - `classification` object
        - `sovereign` boolean
        - `disputed` boolean
        - `iso_status` 'official' | 'user_assigned' | 'unassigned'
        - `un_member` boolean
        - `un_observer` boolean
        - `dependency` boolean
        - `dependency_type` string — Kind of dependency for dependent entities (e.g. overseas_territory, crown_dependency, special_administrative_region, constituent_country); empty string when the entity is not a dependency.
      - `parent` object — Present on dependent entities (overseas territories, crown dependencies, SARs).
        - `alpha_2` string
        - `alpha_3` string
      - `date` object
        - `start_of_week` 'monday' | 'sunday' | 'saturday'
        - `academic_year_start` object
          - `month` integer
          - `day` integer
        - `fiscal_year_start` object
          - `government` object
            - `month` integer
            - `day` integer
          - `corporate` object
            - `month` integer
            - `day` integer
            - `basis` string
          - `personal` object
            - `month` integer
            - `day` integer
      - `links` object
        - `wikipedia` string, uri
        - `official` string, uri
        - `google_maps` string, uri
        - `open_street_maps` string, uri
      - `assets` object[] — Hosted files and media associated with the country (e.g. a link to a photo of the parliament building). Currently always empty; each item will be an object describing one asset.
    - `meta` ListMeta
      - `total` integer, required — Total records matching the query (independent of limit/offset).
      - `count` integer, required — Number of records in this page (length of objects).
      - `limit` integer, required
      - `offset` integer, required
      - `more` boolean, required — True when records remain beyond this page.
      - `request_id` string, required
      - `duration` integer, required — Server-side processing time in milliseconds.

## Other responses

- `400` — Bad request. Malformed parameters or unsupported property.
- `401` — Unauthorized. Missing, invalid, expired, or revoked API key.
- `403` — Forbidden. The account is deleted, disabled, frozen, or pending approval; the request origin isn't in the key's allowed CORS origins; a paid-only field was used as a search, filter, or lookup target on a plan that doesn't include it; a limit above the plan's ceiling but within the paid maximum was requested on a non-paid plan; or the monthly quota has been exceeded past the soft-limit grace period.
- `404` — Not found. The route doesn't match any defined endpoint, the API isn't active, or listing isn't supported for this API version.
- `405` — Method not allowed. Every endpoint is GET-only.
- `410` — Gone. The requested API version is no longer active.
- `429` — Too Many Requests. Sustained traffic above the edge rate limit (20 requests per 10 seconds) is rejected by Cloudflare before the request reaches the API, so this response is generated at the edge and does not carry the standard JSON error envelope. Back off briefly and retry.

---

[API](https://skmtc.dev/restcountries/apis/rest-countries.md) · [All operations](https://skmtc.dev/restcountries/apis/rest-countries/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/restcountries/rest-countries/revisions/87a86bdd79f6/schema)