Country Code Normalizer

location.normalize_country

ProductionEngine wrapper (Class A)Deterministicstrictfastv1.0.0

No network

Overview

You give us one country label — a common name like Belgique, a shorthand like UK, or an ISO code — and we resolve it to the canonical ISO-3166-1 alpha-2, alpha-3, and numeric codes plus English and display names. We tell you how we matched and how confident we are. If nothing matches cleanly, you get matched=false with clear findings instead of a hard error. We don't look up regions, currencies, phone codes, or street addresses — and we won't guess through typos or geocode a place name.

Country fields arrive as BE, bel, 056, Belgique and Belgium, and a guess that silently turns England into a country of its own is worse than no answer. We resolve against published reference data, tell you which route matched, and say so plainly when nothing does.

Reliability

The reference data is ISO 3166-1 as published through ICU/CLDR, pinned at the version we report as dataProfile — cldr-icu-76.1 today, covering 249 countries and territories. Same input and same data version, same answer; when that version moves a display name can change with it, so pin dataProfile if you compare stored results. Matching is exact after we fold case, accents and punctuation — there is no typo tolerance, so Beglium will not resolve. Nothing found and more than one candidate both come back as ordinary successes with matched false and a finding, so branch on matched rather than on your error path. LOCALE_UNSUPPORTED — trigger: an inputLocale outside en, fr, de, es, nl, ja and tr; retryable: no, the same tag always fails; next: send one of those seven, or drop the field and send the ISO code instead of a localized name. COUNTRY_BATCH_LIMIT_EXCEEDED — trigger: your countries array holds more than 100 designations; retryable: no; next: split the list into chunks of 100 or fewer and merge the results on your side.

Context footprint

Send one designation or up to 100 in a batch. Each designation can be up to 128 characters. A successful call costs 1 execution credit.

When to use it

When you hold a country name or code and need the canonical alpha-2, alpha-3 and numeric forms to store, compare or send onward.

When you need regions or subdivisions, coordinates for an address, or a parser that forgives misspellings.

Scope

Note

Resolve one country designation to canonical ISO-3166-1 codes and names.

Non-goals

No region or subdivision lookup
No currency, calling code, or timezone lookup
No fuzzy typo correction beyond case, accents, and punctuation
No geocoding of place names

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

data-transformationvalidation

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input4 KB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
country	string	No	One country designation; required unless countries supplies a batch.
countries	array	No	From 1 through 100 country designation strings resolved in order; required unless country is supplied.
inputLocale	string	No	Language used by localized country names.
options	object	No	Closed allowCommonAliases and allowHistoricalCodes options; omit it to apply their documented defaults.

Output schema

Field	Type	Required	Description
matched	boolean	No	Whether exactly one country resolved.
alpha2	string	No	Two-letter ISO code; omitted when unmatched.
alpha3	string	No	Three-letter ISO code; omitted when unmatched.
numeric	string	No	Three-digit ISO code; omitted when unmatched.
officialName	string	No	English name; omitted when unmatched.
displayName	string	No	Display name; omitted when unmatched.
matchMethod	string	No	Resolution method; omitted when unmatched.
matchedInput	string	No	Trimmed designation represented by this result.
confidence	string	No	EXACT or NORMALIZED; omitted when unmatched.
findings	array	No	From 0 through 1 closed finding objects; empty for a match and actionable when unmatched.
results	array	No	From 1 through 100 closed country result objects preserved in caller order.
_meta	object	Yes	Reference-data profile and number of designations considered.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"location.normalize_country","input":{"country":"Belgique","inputLocale":"fr"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("location.normalize_country", {"inputLocale":"fr","options":{"allowCommonAliases":true,"allowHistoricalCodes":false},"country":"Belgique"});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
COUNTRY_BATCH_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
LOCALE_UNSUPPORTED	400	No	The skill does not support the requested variant.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

No region or subdivision lookup
No currency, calling code, or timezone lookup
No fuzzy typo correction beyond case, accents, and punctuation
No geocoding of place names
Looking up states, provinces, or cities inside a country
Turning a street address into coordinates
Fixing heavily misspelled country names

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "location.normalize_country",
  "input": {
    "inputLocale": "fr",
    "options": {
      "allowCommonAliases": true,
      "allowHistoricalCodes": false
    },
    "country": "Belgique"
  }
}

Examples

French checkout form says Belgique — you need the ISO codes

Inputjson

{
  "inputLocale": "fr",
  "options": {
    "allowCommonAliases": true,
    "allowHistoricalCodes": false
  },
  "country": "Belgique"
}

Expected outputjson

{
  "matchMethod": "LOCALIZED_NAME",
  "numeric": "056",
  "officialName": "Belgium",
  "confidence": "EXACT",
  "alpha2": "BE",
  "alpha3": "BEL",
  "findings": [],
  "matchedInput": "Belgique",
  "_meta": {
    "dataProfile": "cldr-icu-76.1",
    "candidatesConsidered": 1
  },
  "displayName": "Belgium",
  "matched": true
}

Customer typed UK and you want the official GB code

Inputjson

{
  "country": "UK",
  "options": {
    "allowCommonAliases": true,
    "allowHistoricalCodes": false
  }
}

Expected outputjson

{
  "matchMethod": "ALIAS",
  "numeric": "826",
  "officialName": "United Kingdom",
  "confidence": "EXACT",
  "alpha2": "GB",
  "alpha3": "GBR",
  "findings": [],
  "matchedInput": "UK",
  "_meta": {
    "dataProfile": "cldr-icu-76.1",
    "candidatesConsidered": 1
  },
  "displayName": "United Kingdom",
  "matched": true
}

Made-up country name — we tell you plainly instead of guessing

Inputjson

{
  "country": "Atlantis"
}

Expected outputjson

{
  "matched": false,
  "_meta": {
    "dataProfile": "cldr-icu-76.1",
    "candidatesConsidered": 1
  },
  "matchedInput": "Atlantis",
  "findings": [
    {
      "details": {},
      "path": "/country",
      "code": "COUNTRY_UNMATCHED",
      "message": "No ISO-3166-1 country matches the designation",
      "severity": "error"
    }
  ]
}

Import batch mixing an alpha-2 code with a numeric one

Inputjson

{
  "countries": [
    "DE",
    "056"
  ]
}

Expected outputjson

{
  "results": [
    {
      "matched": true,
      "alpha2": "DE",
      "alpha3": "DEU",
      "numeric": "276",
      "officialName": "Germany",
      "displayName": "Germany",
      "matchMethod": "ALPHA2",
      "matchedInput": "DE",
      "confidence": "EXACT",
      "findings": [],
      "_meta": {
        "dataProfile": "cldr-icu-76.1",
        "candidatesConsidered": 2
      }
    },
    {
      "matched": true,
      "alpha2": "BE",
      "alpha3": "BEL",
      "numeric": "056",
      "officialName": "Belgium",
      "displayName": "Belgium",
      "matchMethod": "NUMERIC",
      "matchedInput": "056",
      "confidence": "EXACT",
      "findings": [],
      "_meta": {
        "dataProfile": "cldr-icu-76.1",
        "candidatesConsidered": 2
      }
    }
  ],
  "_meta": {
    "dataProfile": "cldr-icu-76.1",
    "candidatesConsidered": 2
  }
}

Recommended use cases

Clean up free-form country fields before you store or validate them
Turn common shortcuts like UK or USA into stable alpha-2 codes
Accept localized country names when you know which language the form was in

Avoid for

Looking up states, provinces, or cities inside a country
Turning a street address into coordinates
Fixing heavily misspelled country names

location.validate_postal_code location.distance_between

Composable with

location.validate_postal_code

Safety & privacy

Runs without calling any external service.
Your payloads are never stored permanently.
Telemetry captures metadata only — never your payload contents.
We never train models on your payloads.
No human reviews your payloads.

Country Code Normalizer

Overview

When to use it

Scope

Non-goals

Properties

Capabilities

Cost & billing

File handling

How we handle your data

What this means

Squillify guarantees

Your responsibility

Input schema

Output schema

API contract

Errors

Other limits

Limitations

How to call

Examples

French checkout form says Belgique — you need the ISO codes

Customer typed UK and you want the official GB code

Made-up country name — we tell you plainly instead of guessing

Import batch mixing an alpha-2 code with a numeric one

Recommended use cases

Avoid for

Related skills

Composable with

Safety & privacy

Tags