Skip to content

CountryV2

A CountryV2 object represents a country in context of Modigie APIs which is based on the ISO 3166-1 standard.

In requests, it is required to provide exactly one of alpha2, alpha3, num3, or title. While alpha2, alpha3 and num3 produce a deterministic approach, title is used for a non-deterministic approach by fuzzy matching and for this reason you SHOULD provide title only if none of the other properties can be provided.

Schema

A CountryV2 object has properties as described below:

alpha2: string

The ISO 3166-1 alpha-2 code is a code of two uppercase letters that identifies a country. This code is unique for each country but may change over time.

Examples: "US" (United States of America), "CA" (Canada).

alpha3: string

The ISO 3166-1 alpha-3 code is a code of three uppercase letters that identifies a country.

Examples: "USA" (United States of America), "CAN" (Canada).

num3: string
pattern: '^\d{3}'

The ISO 3166-1 numeric-3 code is a code of three digits (including leading zeros) that identifies a country.

Examples: "840" (United States of America), "044" (Bahamas).

title: string

Display name of a country in English, based on the ISO 3166-1 standard database.

Examples: "United States", "Germany".

officialName: string read-only

Official name of a country in English, based on the ISO 3166-1 standard database.

Examples: "United States of America", "Federal Republic of Germany"

Examples

Example with alpha2

country-alpha2-request.json
{
  "alpha2": "US",
}
country-alpha2-response.json
{
  "alpha2": "US",
  "alpha3": "USA",
  "num3": "840",
  "officialName": "United States of America",
  "title": "United States"
}

Example with alpha3

country-alpha3-request.json
{
  "alpha3": "USA",
}
country-alpha3-response.json
{
  "alpha2": "US",
  "alpha3": "USA",
  "num3": "840",
  "officialName": "United States of America",
  "title": "United States"
}

Example with num3

country-num3-request.json
{
  "num3": "008", // (1)!
}
  1. Numeric ISO 3166-1 codes are presented with leading zeros and as a string.
country-num3-response.json
{
  "alpha2": "AL",
  "alpha3": "ALB",
  "num3": "008",
  "officialName": "Republic of Albania",
  "title": "Albania"
}

Example with title

Warning

The API will perform a fuzzy search on the English (short) names of the countries in the ISO 3166-1 database. Only use title if no codes are available!

country-title-request.json
{
  "title": "united states", // (1)!
}
  1. The fuzzy search is case-insensitive.
country-title-response.json
{
  "alpha2": "US",
  "alpha3": "USA",
  "num3": "840",
  "officialName": "United States of America",
  "title": "United States"
}