CountryResponse

interface CountryResponse extends Rules {
country: Named;
lang: Lang;
curated: boolean;
version: string;
currency?: string;
region?: RegionName;
address: AddressSource;
fields: Partial<Record<FieldName, Field>>;
states?: StateOption[];
}

The response of GET /v1/countries/:country, and of rules in GET /v1/geo?include=rules: one country's rules, and with ?include=states the options of its state list.

The example is GET /v1/countries/US?lang=en&include=states, with most fields and states left out.

Example

CODE

{
  "country": { "code": "US", "name": "United States" },
  "lang": "en",
  "curated": true,
  "version": "1nd7x9w",
  "currency": "USD",
  "region": {
    "code": "019",
    "name": "Americas",
    "subregion": { "code": "021", "name": "Northern America" }
  },
  "address": {
    "layout": [
      ["country"],
      ["first_name", "last_name"],
      ["line1"],
      ["line2"],
      ["city", "state", "postcode"],
      ["phone_number"]
    ],
    "fixed": {}
  },
  "fields": {
    "postcode": {
      "label": "ZIP Code",
      "label_optional": "ZIP Code (optional)",
      "required": true,
      "autocomplete": "postal-code",
      "format": {
        "pattern": "^[0-9]{5}([0-9]{4}|[0-9]{6})?$",
        "example": "90210",
        "masks": ["#####", "#####-####", "#####-######"]
      },
      "input": { "type": "text", "auto_capitalize": "characters", "max_length": 64 },
      "errors": {
        "blank": "Enter a ZIP Code",
        "invalid": "Enter a valid ZIP Code, like 90210",
        "contains_emoji": "ZIP Code can't contain emojis",
        "too_long": "ZIP Code must be 64 characters or fewer"
      }
    }
  },
  "states": [
    { "code": "AL", "name": "Alabama" },
    { "code": "AK", "name": "Alaska" }
  ]
}

Hierarchy

Rules
CountryResponse

Properties

`country: Named`

Inherited from country

The country, named in lang. A code with no country behind it keeps its code and gets the default layout, never a 404.

`lang: Lang`

Inherited from lang

The language every label, message and placeholder is in.

`curated: boolean`

Inherited from curated

true when the country has a layout of its own. false for the default layout, where the postcode and state are optional and no value is checked against a pattern.

`version: string`

Inherited from version

The data version: the same string GET /v1/version reports. It changes whenever any rule or text does, so a client that keeps rules keys them on it.

`currency: string`

Inherited from currency

The ISO 4217 currency in circulation in the country. A reading of where a visitor is, not what to charge them.

`region: RegionName`

Inherited from region

The country's UN M49 region and subregion, named in lang.

`address: AddressSource`

Inherited from address

The address: how it is typed in (layout, fixed), how it is written for reading (format, format_latin, upper), and a real one to preview both with (example).

`fields: Partial<Record<FieldName, Field>>`

Inherited from fields

Every field in address.layout, and the email, keyed by name.

`states: StateOption[]`

The options of the state list, in lang's alphabetical order. Only with ?include=states, and only where the country's state is a list.