Which fields an address needs in each of 252 countries and territories, and the order they print on the envelope — plus a live envelope renderer.
Authoritative reference data or standards computation
All 252 region codes, always ordered alphabetically by countryCode so offset paging is stable. The ZZ fallback template is excluded here — it is not a region; fetch it from /lookup?country=ZZ. One caveat for format=csv: fieldWidths has one key per component in that region's fieldOrder, so the flattened CSV header is derived from whichever rows land on the page and is not the same column set on every page (the page holding India carries three extra fieldWidths.landmark* columns). Add an explicit fields= list whenever you intend to concatenate pages.
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
requires | enum | default: any allowed: adminArea | dependentLocality | locality | postalCode | streetAddress | any example: adminArea | Only regions whose `requiredFields` include this component. `country` is not offered: it is required everywhere, so filtering on it would be a no-op. |
uses | enum | default: any allowed: adminArea | dependentLocality | landmarkAffix | landmarkDescriptor | landmarkName | locality | organization | postalCode | recipient | sortingCode | streetAddress | any example: sortingCode | Only regions whose local-script template has a slot for this component. |
adminAreaType | enum | default: any allowed: area | county | department | district | do_si | emirate | island | oblast | parish | prefecture | province | state | any example: prefecture | Only regions that call the state/province level this. Matches the effective value, so `province` includes every region that inherits it. |
postalCodeType | enum | default: any allowed: eircode | pin | postal | zip | any example: eircode | Only regions that call the postal code this. |
hasLatinFormat | boolean | example: true | Only regions that do (or do not) declare a separate Latin-script template. |
usesDefaultFormat | boolean | example: true | Only regions that inherit the fallback template, or only those with a template of their own. |
search | string | allowed: 2 – 60 example: ireland | Case-insensitive substring match over `countryCode` and `postalName`. |
offset | int | default: 0 allowed: 0 – 1000 example: 100 | Skip this many matches before `count` applies. `count` caps at 100, so three calls page the whole 252-row table. To concatenate CSV pages, pin the columns — `?format=csv&fields=countryCode,format,requiredFields,fieldOrder&offset=…` — because an unpinned CSV header is derived from the rows on that page and differs between pages. |
requires enum Only regions whose `requiredFields` include this component. `country` is not offered: it is required everywhere, so filtering on it would be a no-op.
uses enum Only regions whose local-script template has a slot for this component.
adminAreaType enum Only regions that call the state/province level this. Matches the effective value, so `province` includes every region that inherits it.
postalCodeType enum Only regions that call the postal code this.
hasLatinFormat boolean Only regions that do (or do not) declare a separate Latin-script template.
usesDefaultFormat boolean Only regions that inherit the fallback template, or only those with a template of their own.
search string Case-insensitive substring match over `countryCode` and `postalName`.
offset int Skip this many matches before `count` applies. `count` caps at 100, so three calls page the whole 252-row table. To concatenate CSV pages, pin the columns — `?format=csv&fields=countryCode,format,requiredFields,fieldOrder&offset=…` — because an unpinned CSV header is derived from the rows on that page and differs between pages.
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: 100 allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to 100. |
fields | list | example: countryCode,postalName | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: languages | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to 100.
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
exclude list Return all fields except these (comma-separated).
format enum Response format: json envelope, ndjson (one record per line) or csv.
pretty boolean Pretty-print the JSON response.
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
| Field | Type | Description | Example |
|---|---|---|---|
countryCode | string (ISO 3166-1 alpha-2) | The region code as the metadata keys it. 249 are ISO 3166-1 officially assigned; `AC` and `TA` are exceptionally reserved and `XK` is user-assigned. `ZZ` — the fallback template, not a region — is reachable only through the lookup and render routes. | GB |
postalName nullable | string | libaddressinput's own uppercase English postal label, verbatim. NOT an ISO 3166 name — dozens differ (`AX` is labelled `FINLAND`, `GG` and `JE` are both `CHANNEL ISLANDS`, `CZ` is `CZECH REP.`, `SZ` is `SWAZILAND`). Use `/api/countries/lookup?code=…` for the ISO name. Null only for `ZZ`. | UNITED KINGDOM |
format | string | The local-script line template verbatim, or the fallback template when the region declares none. `%`-tokens are components, `%n` is a line break, and everything else is literal text that prints as-is. | %N%n%O%n%A%n%C%n%Z |
templateLines | string[] | `format` split on `%n` — the template as printed lines, tokens still in place. | ["%N","%O","%A","%C","%Z"] |
latinFormat nullable | string | The region's alternative Latin-script template, verbatim. Declared by only 14 regions and null for the other 238; it is genuinely different from `format` for just 8 (CN, HK, JP, KP, KR, MO, TH, TW). | null |
usesDefaultFormat | boolean | True when `format` is the fallback template rather than one this region declares — the 54 regions that inherit `%N%n%O%n%A%n%C`, plus the `ZZ` row itself. | false |
fieldOrder | string[] | The distinct components in template order, first occurrence winning — the same de-duplication `FormatInterpreter.getAddressFieldOrder` performs. This is the field order for a form. A component that appears twice in the template (Côte d'Ivoire's sorting code) is listed once here but still renders twice. | ["recipient","organization","streetAddress","locality","postalCode"] |
requiredFields | string[] | Components a valid address must carry, from the metadata's `require` value, ALWAYS beginning with `country` — exactly as `FormatInterpreter.getRequiredFields` seeds its set with `COUNTRY`. 157 regions carry exactly the fallback row's set (`country, streetAddress, locality`). | ["country","streetAddress","locality","postalCode"] |
uppercaseFields | string[] | Components the metadata's `upper` key marks for upper-casing. A HINT ONLY: no reference implementation in the repository reads this key, so `/render` never changes your casing. Empty array when the key is absent or present-but-empty — no fallback is applied. | ["locality","postalCode"] |
adminAreaType | string | What the state/province level is called: one of area, county, department, district, do_si, emirate, island, oblast, parish, prefecture, province, state. Inherited from the fallback row when the region declares none, mirroring libaddressinput's own default-rule copy — which is why the United Kingdom reports `province`. That is faithful inheritance, not a bug: check `fieldOrder` before you render the field at all. | province |
adminAreaLabel | string | The English UI label libaddressinput ships for that concept. | Province |
localityType | string | What the city level is called: one of city, district, post_town, suburb. | post_town |
localityLabel | string | The English UI label for the locality level. | Post Town |
sublocalityType | string | What the neighbourhood level is called: one of district, neighborhood, suburb, townland, village_township. | suburb |
sublocalityLabel | string | The English UI label for the sublocality level. | Suburb |
postalCodeType | string | What the postal code is called: one of eircode, pin, postal, zip. | postal |
postalCodeLabel | string | The English UI label: Postal code, ZIP code, Eircode or Pincode. | Postal code |
postalCodePrefix nullable | string | The `postprefix` hint for pre-filling a postal-code input (15 regions: CH-, SE-, FI-, L-, FL-, AX-, "AZ " …). `/render` does NOT prepend it: where upstream wants it on the envelope it is already baked into the template as a literal, so Switzerland's template is `%O%n%N%n%A%nCH-%Z %C`. | null |
fieldWidths | object | One entry per component in `fieldOrder`, `"short"` or `"long"`, from `AddressField.getDefaultWidthType` (postal code and sorting code short, everything else long) with the region's `width_overrides` applied. | {"recipient":"long","organization":"long","streetAddress":"long","locality":"long","postalCode":"short"} |
defaultLanguage nullable | string | The `lang` key — the default BCP 47 language of the region's address data. Null where the metadata declares none. | null |
languages | string[] | The `languages` key, split on the `~` separator `rule.cc` uses. Empty array when absent; nine regions list more than one (`CA` → en, fr; `ES` → es, ca, gl, eu). | [] |
countryCode string (ISO 3166-1 alpha-2) The region code as the metadata keys it. 249 are ISO 3166-1 officially assigned; `AC` and `TA` are exceptionally reserved and `XK` is user-assigned. `ZZ` — the fallback template, not a region — is reachable only through the lookup and render routes.
example: GB
postalName string nullable libaddressinput's own uppercase English postal label, verbatim. NOT an ISO 3166 name — dozens differ (`AX` is labelled `FINLAND`, `GG` and `JE` are both `CHANNEL ISLANDS`, `CZ` is `CZECH REP.`, `SZ` is `SWAZILAND`). Use `/api/countries/lookup?code=…` for the ISO name. Null only for `ZZ`.
example: UNITED KINGDOM
format string The local-script line template verbatim, or the fallback template when the region declares none. `%`-tokens are components, `%n` is a line break, and everything else is literal text that prints as-is.
example: %N%n%O%n%A%n%C%n%Z
templateLines string[] `format` split on `%n` — the template as printed lines, tokens still in place.
example: ["%N","%O","%A","%C","%Z"]
latinFormat string nullable The region's alternative Latin-script template, verbatim. Declared by only 14 regions and null for the other 238; it is genuinely different from `format` for just 8 (CN, HK, JP, KP, KR, MO, TH, TW).
example: null
usesDefaultFormat boolean True when `format` is the fallback template rather than one this region declares — the 54 regions that inherit `%N%n%O%n%A%n%C`, plus the `ZZ` row itself.
example: false
fieldOrder string[] The distinct components in template order, first occurrence winning — the same de-duplication `FormatInterpreter.getAddressFieldOrder` performs. This is the field order for a form. A component that appears twice in the template (Côte d'Ivoire's sorting code) is listed once here but still renders twice.
example: ["recipient","organization","streetAddress","locality","postalCode"]
requiredFields string[] Components a valid address must carry, from the metadata's `require` value, ALWAYS beginning with `country` — exactly as `FormatInterpreter.getRequiredFields` seeds its set with `COUNTRY`. 157 regions carry exactly the fallback row's set (`country, streetAddress, locality`).
example: ["country","streetAddress","locality","postalCode"]
uppercaseFields string[] Components the metadata's `upper` key marks for upper-casing. A HINT ONLY: no reference implementation in the repository reads this key, so `/render` never changes your casing. Empty array when the key is absent or present-but-empty — no fallback is applied.
example: ["locality","postalCode"]
adminAreaType string What the state/province level is called: one of area, county, department, district, do_si, emirate, island, oblast, parish, prefecture, province, state. Inherited from the fallback row when the region declares none, mirroring libaddressinput's own default-rule copy — which is why the United Kingdom reports `province`. That is faithful inheritance, not a bug: check `fieldOrder` before you render the field at all.
example: province
adminAreaLabel string The English UI label libaddressinput ships for that concept.
example: Province
localityType string What the city level is called: one of city, district, post_town, suburb.
example: post_town
localityLabel string The English UI label for the locality level.
example: Post Town
sublocalityType string What the neighbourhood level is called: one of district, neighborhood, suburb, townland, village_township.
example: suburb
sublocalityLabel string The English UI label for the sublocality level.
example: Suburb
postalCodeType string What the postal code is called: one of eircode, pin, postal, zip.
example: postal
postalCodeLabel string The English UI label: Postal code, ZIP code, Eircode or Pincode.
example: Postal code
postalCodePrefix string nullable The `postprefix` hint for pre-filling a postal-code input (15 regions: CH-, SE-, FI-, L-, FL-, AX-, "AZ " …). `/render` does NOT prepend it: where upstream wants it on the envelope it is already baked into the template as a literal, so Switzerland's template is `%O%n%N%n%A%nCH-%Z %C`.
example: null
fieldWidths object One entry per component in `fieldOrder`, `"short"` or `"long"`, from `AddressField.getDefaultWidthType` (postal code and sorting code short, everything else long) with the region's `width_overrides` applied.
example: {"recipient":"long","organization":"long","streetAddress":"long","locality":"long","postalCode":"short"}
defaultLanguage string nullable The `lang` key — the default BCP 47 language of the region's address data. Null where the metadata declares none.
example: null
languages string[] The `languages` key, split on the `~` separator `rule.cc` uses. Empty array when absent; nine regions list more than one (`CA` → en, fr; `ES` → es, ca, gl, eu).
example: []
/api/address-formats?requires=adminArea {
"data": [
{
"countryCode": "AE",
"postalName": "UNITED ARAB EMIRATES",
"format": "%N%n%O%n%A%n%S",
"templateLines": [
"%N",
"%O",
"%A",
"%S"
],
"latinFormat": "%N%n%O%n%A%n%S",
"usesDefaultFormat": false,
"fieldOrder": [
"recipient",
"organization",
"streetAddress",
"adminArea"
],
"requiredFields": [
"country",
"streetAddress",
"adminArea"
],
"uppercaseFields": [],
"adminAreaType": "emirate",
"adminAreaLabel": "Emirate",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "suburb",
"sublocalityLabel": "Suburb",
"postalCodeType": "postal",
"postalCodeLabel": "Postal code",
"postalCodePrefix": null,
"fieldWidths": {
"recipient": "long",
"organization": "long",
"streetAddress": "long",
"adminArea": "long"
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats?usesDefaultFormat=true {
"data": [
{
"countryCode": "AG",
"postalName": "ANTIGUA AND BARBUDA",
"format": "%N%n%O%n%A%n%C",
"templateLines": [
"%N",
"%O",
"%A",
"%C"
],
"latinFormat": null,
"usesDefaultFormat": true,
"fieldOrder": [
"recipient",
"organization",
"streetAddress",
"locality"
],
"requiredFields": [
"country",
"streetAddress"
],
"uppercaseFields": [],
"adminAreaType": "province",
"adminAreaLabel": "Province",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "suburb",
"sublocalityLabel": "Suburb",
"postalCodeType": "postal",
"postalCodeLabel": "Postal code",
"postalCodePrefix": null,
"fieldWidths": {
"recipient": "long",
"organization": "long",
"streetAddress": "long",
"locality": "long"
},
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats?uses=sortingCode {
"data": [
{
"countryCode": "BF",
"postalName": "BURKINA FASO",
"format": "%N%n%O%n%A%n%C %X",
"templateLines": [
"%N",
"%O",
"%A",
"%C %X"
],
"latinFormat": null,
"usesDefaultFormat": false,
"fieldOrder": [
"recipient",
"organization",
"streetAddress",
"locality",
"sortingCode"
],
"requiredFields": [
"country",
"streetAddress",
"locality"
],
"uppercaseFields": [],
"adminAreaType": "province",
"adminAreaLabel": "Province",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "suburb",
"sublocalityLabel": "Suburb",
"postalCodeType": "postal",
"postalCodeLabel": "Postal code",
"postalCodePrefix": null,
"fieldWidths": {
"recipient": "long",
"organization": "long",
"streetAddress": "long",
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats?format=csv&fields=countryCode,format,requiredFields,fieldOrder&offset=100 countryCode,format,requiredFields,fieldOrder
HU,%N%n%O%n%C%n%A%n%Z,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""locality"",""streetAddress"",""postalCode""]"
ID,%N%n%O%n%A%n%C%n%S %Z,"[""country"",""streetAddress"",""adminArea""]","[""recipient"",""organization"",""streetAddress"",""locality"",""adminArea"",""postalCode""]"
IE,%N%n%O%n%A%n%D%n%C%n%S%n%Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""dependentLocality"",""locality"",""adminArea"",""postalCode""]"
IL,%N%n%O%n%A%n%C %Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
IM,%N%n%O%n%A%n%C%n%Z,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
IN,%N%n%O%n%A%n%T%n%F%n%L%n%C %Z%n%S,"[""country"",""streetAddress"",""locality"",""adminArea"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""landmarkDescriptor"",""landmarkAffix"",""landmarkName"",""locality"",""postalCode"",""adminArea""]"
IO,%N%n%O%n%A%n%C%n%Z,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
IQ,"%O%n%N%n%A%n%C, %S%n%Z","[""country"",""streetAddress"",""locality"",""adminArea""]","[""organization"",""recipient"",""streetAddress"",""locality"",""adminArea"",""postalCode""]"
IR,"%O%n%N%n%S%n%C, %D%n%A%n%Z","[""country"",""streetAddress"",""locality""]","[""organization"",""recipient"",""adminArea"",""locality"",""dependentLocality"",""streetAddress"",""postalCode""]"
IS,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
IT,%N%n%O%n%A%n%Z %C %S,"[""country"",""streetAddress"",""locality"",""adminArea"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality"",""adminArea""]"
JE,%N%n%O%n%A%n%C%nJERSEY%n%Z,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
JM,%N%n%O%n%A%n%C%n%S %X,"[""country"",""streetAddress"",""locality"",""adminArea""]","[""recipient"",""organization"",""streetAddress"",""locality"",""adminArea"",""sortingCode""]"
JO,%N%n%O%n%A%n%C %Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
JP,〒%Z%n%S%n%A%n%O%n%N,"[""country"",""streetAddress"",""adminArea"",""postalCode""]","[""postalCode"",""adminArea"",""streetAddress"",""organization"",""recipient""]"
KE,%N%n%O%n%A%n%C%n%Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
KG,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
KH,%N%n%O%n%A%n%C %Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
KI,%N%n%O%n%A%n%S%n%C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""adminArea"",""locality""]"
KM,%N%n%O%n%A%n%C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality""]"
KN,"%N%n%O%n%A%n%C, %S","[""country"",""streetAddress"",""locality"",""adminArea""]","[""recipient"",""organization"",""streetAddress"",""locality"",""adminArea""]"
KP,%Z%n%S%n%C%n%A%n%O%n%N,"[""country"",""streetAddress"",""locality""]","[""postalCode"",""adminArea"",""locality"",""streetAddress"",""organization"",""recipient""]"
KR,%S %C%D%n%A%n%O%n%N%n%Z,"[""country"",""streetAddress"",""locality"",""adminArea"",""postalCode""]","[""adminArea"",""locality"",""dependentLocality"",""streetAddress"",""organization"",""recipient"",""postalCode""]"
KW,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
KY,%N%n%O%n%A%n%S %Z,"[""country"",""streetAddress"",""adminArea""]","[""recipient"",""organization"",""streetAddress"",""adminArea"",""postalCode""]"
KZ,%Z%n%S%n%C%n%A%n%O%n%N,"[""country"",""streetAddress"",""locality""]","[""postalCode"",""adminArea"",""locality"",""streetAddress"",""organization"",""recipient""]"
LA,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
LB,%N%n%O%n%A%n%C %Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
LC,%N%n%O%n%A%n%C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality""]"
LI,%O%n%N%n%A%nFL-%Z %C,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""organization"",""recipient"",""streetAddress"",""postalCode"",""locality""]"
LK,%N%n%O%n%A%n%C%n%Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
LR,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
LS,%N%n%O%n%A%n%C %Z,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
LT,%O%n%N%n%A%nLT-%Z %C %S,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""organization"",""recipient"",""streetAddress"",""postalCode"",""locality"",""adminArea""]"
LU,%O%n%N%n%A%nL-%Z %C,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""organization"",""recipient"",""streetAddress"",""postalCode"",""locality""]"
LV,"%N%n%O%n%A%n%S%n%C, %Z","[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""adminArea"",""locality"",""postalCode""]"
LY,%N%n%O%n%A%n%C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""locality""]"
MA,%N%n%O%n%A%n%Z %C,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality""]"
MC,%N%n%O%n%A%nMC-%Z %C %X,"[""country"",""streetAddress"",""locality""]","[""recipient"",""organization"",""streetAddress"",""postalCode"",""locality"",""sortingCode""]"
…
SG,%N%n%O%n%A%nSINGAPORE %Z,"[""country"",""streetAddress"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""postalCode""]"
SH,%N%n%O%n%A%n%C%n%Z,"[""country"",""streetAddress"",""locality"",""postalCode""]","[""recipient"",""organization"",""streetAddress"",""locality"",""postalCode""]"
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
country
required
| string | allowed: 2 – 2 example: JP | ISO 3166-1 alpha-2 region code, case-insensitive. `ZZ` returns the fallback template libaddressinput uses for a region it has no data for. |
country string required ISO 3166-1 alpha-2 region code, case-insensitive. `ZZ` returns the fallback template libaddressinput uses for a region it has no data for.
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
fields | list | example: countryCode,postalName | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: languages | Return all fields except these (comma-separated). |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
exclude list Return all fields except these (comma-separated).
pretty boolean Pretty-print the JSON response.
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
| Field | Type | Description | Example |
|---|---|---|---|
countryCode | string (ISO 3166-1 alpha-2) | The region code as the metadata keys it. 249 are ISO 3166-1 officially assigned; `AC` and `TA` are exceptionally reserved and `XK` is user-assigned. `ZZ` — the fallback template, not a region — is reachable only through the lookup and render routes. | GB |
postalName nullable | string | libaddressinput's own uppercase English postal label, verbatim. NOT an ISO 3166 name — dozens differ (`AX` is labelled `FINLAND`, `GG` and `JE` are both `CHANNEL ISLANDS`, `CZ` is `CZECH REP.`, `SZ` is `SWAZILAND`). Use `/api/countries/lookup?code=…` for the ISO name. Null only for `ZZ`. | UNITED KINGDOM |
format | string | The local-script line template verbatim, or the fallback template when the region declares none. `%`-tokens are components, `%n` is a line break, and everything else is literal text that prints as-is. | %N%n%O%n%A%n%C%n%Z |
templateLines | string[] | `format` split on `%n` — the template as printed lines, tokens still in place. | ["%N","%O","%A","%C","%Z"] |
latinFormat nullable | string | The region's alternative Latin-script template, verbatim. Declared by only 14 regions and null for the other 238; it is genuinely different from `format` for just 8 (CN, HK, JP, KP, KR, MO, TH, TW). | null |
usesDefaultFormat | boolean | True when `format` is the fallback template rather than one this region declares — the 54 regions that inherit `%N%n%O%n%A%n%C`, plus the `ZZ` row itself. | false |
fieldOrder | string[] | The distinct components in template order, first occurrence winning — the same de-duplication `FormatInterpreter.getAddressFieldOrder` performs. This is the field order for a form. A component that appears twice in the template (Côte d'Ivoire's sorting code) is listed once here but still renders twice. | ["recipient","organization","streetAddress","locality","postalCode"] |
requiredFields | string[] | Components a valid address must carry, from the metadata's `require` value, ALWAYS beginning with `country` — exactly as `FormatInterpreter.getRequiredFields` seeds its set with `COUNTRY`. 157 regions carry exactly the fallback row's set (`country, streetAddress, locality`). | ["country","streetAddress","locality","postalCode"] |
uppercaseFields | string[] | Components the metadata's `upper` key marks for upper-casing. A HINT ONLY: no reference implementation in the repository reads this key, so `/render` never changes your casing. Empty array when the key is absent or present-but-empty — no fallback is applied. | ["locality","postalCode"] |
adminAreaType | string | What the state/province level is called: one of area, county, department, district, do_si, emirate, island, oblast, parish, prefecture, province, state. Inherited from the fallback row when the region declares none, mirroring libaddressinput's own default-rule copy — which is why the United Kingdom reports `province`. That is faithful inheritance, not a bug: check `fieldOrder` before you render the field at all. | province |
adminAreaLabel | string | The English UI label libaddressinput ships for that concept. | Province |
localityType | string | What the city level is called: one of city, district, post_town, suburb. | post_town |
localityLabel | string | The English UI label for the locality level. | Post Town |
sublocalityType | string | What the neighbourhood level is called: one of district, neighborhood, suburb, townland, village_township. | suburb |
sublocalityLabel | string | The English UI label for the sublocality level. | Suburb |
postalCodeType | string | What the postal code is called: one of eircode, pin, postal, zip. | postal |
postalCodeLabel | string | The English UI label: Postal code, ZIP code, Eircode or Pincode. | Postal code |
postalCodePrefix nullable | string | The `postprefix` hint for pre-filling a postal-code input (15 regions: CH-, SE-, FI-, L-, FL-, AX-, "AZ " …). `/render` does NOT prepend it: where upstream wants it on the envelope it is already baked into the template as a literal, so Switzerland's template is `%O%n%N%n%A%nCH-%Z %C`. | null |
fieldWidths | object | One entry per component in `fieldOrder`, `"short"` or `"long"`, from `AddressField.getDefaultWidthType` (postal code and sorting code short, everything else long) with the region's `width_overrides` applied. | {"recipient":"long","organization":"long","streetAddress":"long","locality":"long","postalCode":"short"} |
defaultLanguage nullable | string | The `lang` key — the default BCP 47 language of the region's address data. Null where the metadata declares none. | null |
languages | string[] | The `languages` key, split on the `~` separator `rule.cc` uses. Empty array when absent; nine regions list more than one (`CA` → en, fr; `ES` → es, ca, gl, eu). | [] |
countryCode string (ISO 3166-1 alpha-2) The region code as the metadata keys it. 249 are ISO 3166-1 officially assigned; `AC` and `TA` are exceptionally reserved and `XK` is user-assigned. `ZZ` — the fallback template, not a region — is reachable only through the lookup and render routes.
example: GB
postalName string nullable libaddressinput's own uppercase English postal label, verbatim. NOT an ISO 3166 name — dozens differ (`AX` is labelled `FINLAND`, `GG` and `JE` are both `CHANNEL ISLANDS`, `CZ` is `CZECH REP.`, `SZ` is `SWAZILAND`). Use `/api/countries/lookup?code=…` for the ISO name. Null only for `ZZ`.
example: UNITED KINGDOM
format string The local-script line template verbatim, or the fallback template when the region declares none. `%`-tokens are components, `%n` is a line break, and everything else is literal text that prints as-is.
example: %N%n%O%n%A%n%C%n%Z
templateLines string[] `format` split on `%n` — the template as printed lines, tokens still in place.
example: ["%N","%O","%A","%C","%Z"]
latinFormat string nullable The region's alternative Latin-script template, verbatim. Declared by only 14 regions and null for the other 238; it is genuinely different from `format` for just 8 (CN, HK, JP, KP, KR, MO, TH, TW).
example: null
usesDefaultFormat boolean True when `format` is the fallback template rather than one this region declares — the 54 regions that inherit `%N%n%O%n%A%n%C`, plus the `ZZ` row itself.
example: false
fieldOrder string[] The distinct components in template order, first occurrence winning — the same de-duplication `FormatInterpreter.getAddressFieldOrder` performs. This is the field order for a form. A component that appears twice in the template (Côte d'Ivoire's sorting code) is listed once here but still renders twice.
example: ["recipient","organization","streetAddress","locality","postalCode"]
requiredFields string[] Components a valid address must carry, from the metadata's `require` value, ALWAYS beginning with `country` — exactly as `FormatInterpreter.getRequiredFields` seeds its set with `COUNTRY`. 157 regions carry exactly the fallback row's set (`country, streetAddress, locality`).
example: ["country","streetAddress","locality","postalCode"]
uppercaseFields string[] Components the metadata's `upper` key marks for upper-casing. A HINT ONLY: no reference implementation in the repository reads this key, so `/render` never changes your casing. Empty array when the key is absent or present-but-empty — no fallback is applied.
example: ["locality","postalCode"]
adminAreaType string What the state/province level is called: one of area, county, department, district, do_si, emirate, island, oblast, parish, prefecture, province, state. Inherited from the fallback row when the region declares none, mirroring libaddressinput's own default-rule copy — which is why the United Kingdom reports `province`. That is faithful inheritance, not a bug: check `fieldOrder` before you render the field at all.
example: province
adminAreaLabel string The English UI label libaddressinput ships for that concept.
example: Province
localityType string What the city level is called: one of city, district, post_town, suburb.
example: post_town
localityLabel string The English UI label for the locality level.
example: Post Town
sublocalityType string What the neighbourhood level is called: one of district, neighborhood, suburb, townland, village_township.
example: suburb
sublocalityLabel string The English UI label for the sublocality level.
example: Suburb
postalCodeType string What the postal code is called: one of eircode, pin, postal, zip.
example: postal
postalCodeLabel string The English UI label: Postal code, ZIP code, Eircode or Pincode.
example: Postal code
postalCodePrefix string nullable The `postprefix` hint for pre-filling a postal-code input (15 regions: CH-, SE-, FI-, L-, FL-, AX-, "AZ " …). `/render` does NOT prepend it: where upstream wants it on the envelope it is already baked into the template as a literal, so Switzerland's template is `%O%n%N%n%A%nCH-%Z %C`.
example: null
fieldWidths object One entry per component in `fieldOrder`, `"short"` or `"long"`, from `AddressField.getDefaultWidthType` (postal code and sorting code short, everything else long) with the region's `width_overrides` applied.
example: {"recipient":"long","organization":"long","streetAddress":"long","locality":"long","postalCode":"short"}
defaultLanguage string nullable The `lang` key — the default BCP 47 language of the region's address data. Null where the metadata declares none.
example: null
languages string[] The `languages` key, split on the `~` separator `rule.cc` uses. Empty array when absent; nine regions list more than one (`CA` → en, fr; `ES` → es, ca, gl, eu).
example: []
/api/address-formats/lookup?country=JP {
"data": {
"countryCode": "JP",
"postalName": "JAPAN",
"format": "〒%Z%n%S%n%A%n%O%n%N",
"templateLines": [
"〒%Z",
"%S",
"%A",
"%O",
"%N"
],
"latinFormat": "%N%n%O%n%A, %S%n%Z",
"usesDefaultFormat": false,
"fieldOrder": [
"postalCode",
"adminArea",
"streetAddress",
"organization",
"recipient"
],
"requiredFields": [
"country",
"streetAddress",
"adminArea",
"postalCode"
],
"uppercaseFields": [
"adminArea"
],
"adminAreaType": "prefecture",
"adminAreaLabel": "Prefecture",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "suburb",
"sublocalityLabel": "Suburb",
"postalCodeType": "postal",
"postalCodeLabel": "Postal code",
"postalCodePrefix": null,
"fieldWidths": {
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats/lookup?country=IE {
"data": {
"countryCode": "IE",
"postalName": "IRELAND",
"format": "%N%n%O%n%A%n%D%n%C%n%S%n%Z",
"templateLines": [
"%N",
"%O",
"%A",
"%D",
"%C",
"%S",
"%Z"
],
"latinFormat": null,
"usesDefaultFormat": false,
"fieldOrder": [
"recipient",
"organization",
"streetAddress",
"dependentLocality",
"locality",
"adminArea",
"postalCode"
],
"requiredFields": [
"country",
"streetAddress",
"locality"
],
"uppercaseFields": [],
"adminAreaType": "county",
"adminAreaLabel": "County",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "townland",
"sublocalityLabel": "Townland",
"postalCodeType": "eircode",
"postalCodeLabel": "Eircode",
"postalCodePrefix": null,
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats/lookup?country=ZZ {
"data": {
"countryCode": "ZZ",
"postalName": null,
"format": "%N%n%O%n%A%n%C",
"templateLines": [
"%N",
"%O",
"%A",
"%C"
],
"latinFormat": null,
"usesDefaultFormat": true,
"fieldOrder": [
"recipient",
"organization",
"streetAddress",
"locality"
],
"requiredFields": [
"country",
"streetAddress",
"locality"
],
"uppercaseFields": [
"locality"
],
"adminAreaType": "province",
"adminAreaLabel": "Province",
"localityType": "city",
"localityLabel": "City",
"sublocalityType": "suburb",
"sublocalityLabel": "Suburb",
"postalCodeType": "postal",
"postalCodeLabel": "Postal code",
"postalCodePrefix": null,
"fieldWidths": {
"recipient": "long",
"organization": "long",
"streetAddress": "long",
…
"generatedAt": "2026-07-30T15:14:08.000Z"
}
}Supply whichever components you have; the destination country's template decides the order, the line breaks and which of them print at all. Empty and whitespace-only values count as absent, which is what a form that posts every field wants.
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
country
required
| string | allowed: 2 – 2 example: JP | Destination region code, case-insensitive. `ZZ` renders with the fallback template. |
recipient | string | allowed: ≤ 200 example: Jane Doe | Person's name (`%N`). |
organization | string | allowed: ≤ 200 example: Acme Inc | Company or institution (`%O`). |
street | string | allowed: ≤ 200 example: 1600 Amphitheatre Parkway | First street-address line (`%A`). |
street2 | string | allowed: ≤ 200 example: Building 40 | Second street-address line. Requires `street` — street lines are ordered. |
dependentLocality | string | allowed: ≤ 120 example: Camberwell | Neighbourhood, district or townland (`%D`) — 14 regions print it. |
locality | string | allowed: ≤ 120 example: Mountain View | City or post town (`%C`). |
adminArea | string | allowed: ≤ 120 example: CA | State, province or prefecture (`%S`). |
postalCode | string | allowed: ≤ 40 example: 94043 | Postal code, ZIP, Eircode or Pincode (`%Z`). Never validated. |
sortingCode | string | allowed: ≤ 40 example: CEDEX 12 | CEDEX-style sorting code (`%X`) — 15 territories print it. |
script | enum | default: local allowed: local | latin example: latin | `latin` selects the region's Latin-script template where it declares one (14 do). Where it does not, the region's own template is used and `latinFormatAvailable` reports false. |
country string required Destination region code, case-insensitive. `ZZ` renders with the fallback template.
recipient string Person's name (`%N`).
organization string Company or institution (`%O`).
street string First street-address line (`%A`).
street2 string Second street-address line. Requires `street` — street lines are ordered.
dependentLocality string Neighbourhood, district or townland (`%D`) — 14 regions print it.
locality string City or post town (`%C`).
adminArea string State, province or prefecture (`%S`).
postalCode string Postal code, ZIP, Eircode or Pincode (`%Z`). Never validated.
sortingCode string CEDEX-style sorting code (`%X`) — 15 territories print it.
script enum `latin` selects the region's Latin-script template where it declares one (14 do). Where it does not, the region's own template is used and `latinFormatAvailable` reports false.
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
fields | list | example: countryCode,postalName | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: complete | Return all fields except these (comma-separated). |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
exclude list Return all fields except these (comma-separated).
pretty boolean Pretty-print the JSON response.
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
| Field | Type | Description | Example |
|---|---|---|---|
countryCode | string (ISO 3166-1 alpha-2) | The resolved, uppercased region code. | DE |
postalName nullable | string | libaddressinput's uppercase postal label. Not an ISO 3166 name. | GERMANY |
script | string | The requested script, resolved: `local` or `latin`. | local |
format | string | The template actually used. | %N%n%O%n%A%n%Z %C |
latinFormatAvailable | boolean | Whether the region declares a Latin-script template. When `script=latin` and this is false, the region's own local template was used instead. | false |
usesDefaultFormat | boolean | Whether the template used is the fallback one. | false |
lines | string[] | The rendered envelope lines. Empty lines are dropped, casing is never changed, and the destination country is not appended. | ["Erika Mustermann","Musterstrasse 12","10115 Berlin"] |
oneLine | string | `lines` joined with `lineSeparator`. | Erika Mustermann, Musterstrasse 12, 10115 Berlin |
lineSeparator | string | The separator used for `oneLine`. Derived from the region's own `defaultLanguage` (or forced to `", "` by `script=latin`) — upstream keys this on the address's language tag, which this route has no input for, so the substitution is ours. | , |
missingRequired | string[] | Required components you did not supply, in the metadata's own letter order. `country` is excluded — it is always supplied. | [] |
unusedComponents | string[] | Components you supplied that the template actually used has no slot for — the fields your form is collecting for nothing. `street2` counts as `streetAddress`. | ["adminArea"] |
uppercaseFields | string[] | The `upper` hint, for your own house style. Never applied here. | [] |
complete | boolean | `missingRequired` is empty. Says nothing about whether the address is real or deliverable. | true |
countryCode string (ISO 3166-1 alpha-2) The resolved, uppercased region code.
example: DE
postalName string nullable libaddressinput's uppercase postal label. Not an ISO 3166 name.
example: GERMANY
script string The requested script, resolved: `local` or `latin`.
example: local
format string The template actually used.
example: %N%n%O%n%A%n%Z %C
latinFormatAvailable boolean Whether the region declares a Latin-script template. When `script=latin` and this is false, the region's own local template was used instead.
example: false
usesDefaultFormat boolean Whether the template used is the fallback one.
example: false
lines string[] The rendered envelope lines. Empty lines are dropped, casing is never changed, and the destination country is not appended.
example: ["Erika Mustermann","Musterstrasse 12","10115 Berlin"]
oneLine string `lines` joined with `lineSeparator`.
example: Erika Mustermann, Musterstrasse 12, 10115 Berlin
lineSeparator string The separator used for `oneLine`. Derived from the region's own `defaultLanguage` (or forced to `", "` by `script=latin`) — upstream keys this on the address's language tag, which this route has no input for, so the substitution is ours.
example: ,
missingRequired string[] Required components you did not supply, in the metadata's own letter order. `country` is excluded — it is always supplied.
example: []
unusedComponents string[] Components you supplied that the template actually used has no slot for — the fields your form is collecting for nothing. `street2` counts as `streetAddress`.
example: ["adminArea"]
uppercaseFields string[] The `upper` hint, for your own house style. Never applied here.
example: []
complete boolean `missingRequired` is empty. Says nothing about whether the address is real or deliverable.
example: true
/api/address-formats/render?country=DE&recipient=Erika+Mustermann&street=Musterstrasse+12&postalCode=10115&locality=Berlin {
"data": {
"countryCode": "DE",
"postalName": "GERMANY",
"script": "local",
"format": "%N%n%O%n%A%n%Z %C",
"latinFormatAvailable": false,
"usesDefaultFormat": false,
"lines": [
"Erika Mustermann",
"Musterstrasse 12",
"10115 Berlin"
],
"oneLine": "Erika Mustermann, Musterstrasse 12, 10115 Berlin",
"lineSeparator": ", ",
"missingRequired": [],
"unusedComponents": [],
"uppercaseFields": [],
"complete": true
},
"meta": {
"endpoint": "address-formats",
"route": "/render",
"params": {
"country": "DE",
"recipient": "Erika Mustermann",
"street": "Musterstrasse 12",
"locality": "Berlin",
"postalCode": "10115",
"script": "local"
},
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats/render?country=JP&recipient=Taro+Yamada&street=1-1+Chiyoda&adminArea=Tokyo&postalCode=100-0001 {
"data": {
"countryCode": "JP",
"postalName": "JAPAN",
"script": "local",
"format": "〒%Z%n%S%n%A%n%O%n%N",
"latinFormatAvailable": true,
"usesDefaultFormat": false,
"lines": [
"〒100-0001",
"Tokyo",
"1-1 Chiyoda",
"Taro Yamada"
],
"oneLine": "〒100-0001Tokyo1-1 ChiyodaTaro Yamada",
"lineSeparator": "",
"missingRequired": [],
"unusedComponents": [],
"uppercaseFields": [
"adminArea"
],
"complete": true
},
"meta": {
"endpoint": "address-formats",
"route": "/render",
"params": {
"country": "JP",
"recipient": "Taro Yamada",
"street": "1-1 Chiyoda",
"adminArea": "Tokyo",
"postalCode": "100-0001",
"script": "local"
},
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats/render?country=JP&recipient=Taro+Yamada&street=1-1+Chiyoda&adminArea=Tokyo&postalCode=100-0001&script=latin {
"data": {
"countryCode": "JP",
"postalName": "JAPAN",
"script": "latin",
"format": "%N%n%O%n%A, %S%n%Z",
"latinFormatAvailable": true,
"usesDefaultFormat": false,
"lines": [
"Taro Yamada",
"1-1 Chiyoda, Tokyo",
"100-0001"
],
"oneLine": "Taro Yamada, 1-1 Chiyoda, Tokyo, 100-0001",
"lineSeparator": ", ",
"missingRequired": [],
"unusedComponents": [],
"uppercaseFields": [
"adminArea"
],
"complete": true
},
"meta": {
"endpoint": "address-formats",
"route": "/render",
"params": {
"country": "JP",
"recipient": "Taro Yamada",
"street": "1-1 Chiyoda",
"adminArea": "Tokyo",
"postalCode": "100-0001",
"script": "latin"
},
"generatedAt": "2026-07-30T15:14:08.000Z"
}
} /api/address-formats/render?country=US&recipient=Jane+Doe&street=1600+Amphitheatre+Parkway&adminArea=CA&postalCode=94043 {
"data": {
"countryCode": "US",
"postalName": "UNITED STATES",
"script": "local",
"format": "%N%n%O%n%A%n%C, %S %Z",
"latinFormatAvailable": false,
"usesDefaultFormat": false,
"lines": [
"Jane Doe",
"1600 Amphitheatre Parkway",
"CA 94043"
],
"oneLine": "Jane Doe, 1600 Amphitheatre Parkway, CA 94043",
"lineSeparator": ", ",
"missingRequired": [
"locality"
],
"unusedComponents": [],
"uppercaseFields": [
"locality",
"adminArea"
],
"complete": false
},
"meta": {
"endpoint": "address-formats",
"route": "/render",
"params": {
"country": "US",
"recipient": "Jane Doe",
"street": "1600 Amphitheatre Parkway",
"adminArea": "CA",
"postalCode": "94043",
"script": "local"
},
"generatedAt": "2026-07-30T15:14:08.000Z"
}
}Layout rules only. This endpoint answers which components an address needs, in what order they print, and what each level is called — for all 252 region codes Google's libaddressinput carries. It does not validate postal codes, does not list state or city names, and does not geocode or check deliverability. That boundary is deliberate rather than a gap: postal-code shapes are the sibling /api/postal-code-formats (masks and anchored regexes derived from GeoNames) and subdivision names are /api/country-subdivisions (ISO 3166-2), each from its own pinned source.
Three routes: the list route browses and filters the whole table, /lookup returns one region's rule, and /render actually assembles envelope lines from the components you supply.
Every rule is a line template. %n is a line break; each %<letter> is a component; anything else is literal text that prints verbatim (which is how GIBRALTAR, SINGAPORE and CH- end up on envelopes).
| Token | Component | Notes |
|---|---|---|
%N |
recipient |
|
%O |
organization |
|
%A |
streetAddress |
expands to every street line you supply |
%D |
dependentLocality |
neighbourhood / district / townland — 14 regions print it |
%C |
locality |
city / post town |
%S |
adminArea |
state / province / prefecture |
%Z |
postalCode |
69 regions have no slot for it at all |
%X |
sortingCode |
CEDEX-style — 15 territories print it |
%R |
country |
absent from every shipped template. Treated as absent here, because /render never appends the destination country; Java counts it as filled but prints nothing, the C++ prints the region code |
%T %F %L |
India's three Address Descriptor landmark fields | render as nothing — neither reference implementation fills them (below) |
%1 %2 |
deprecated address-line fields | absent from every shipped template. Treated as absent here; Java counts them as filled from the street lines but still prints nothing, the C++ ignores them entirely |
The token inventory across all 253 rows and both scripts is exactly A C D F L N O S T X Z n — every other token in the table above is documented because AddressField defines it, not because anything uses it.
libaddressinput keeps a fallback row under the key ZZ. format and the four *Type values fall back to it: 198 of the 252 regions declare a template of their own and the other 54 inherit %N%n%O%n%A%n%C, while 157 end up with exactly its required-field set (country, streetAddress, locality). latinFormat, postalCodePrefix, fieldWidths, defaultLanguage and languages do not fall back. Neither does uppercaseFields: although the fallback row does carry an upper value, nothing in either reference implementation reads that key, so inventing a fallback for it would be inventing a fact.
The visible consequence: the United Kingdom reports adminAreaType: "province". That is faithful inheritance — the UK declares no admin-area type — and the label is unused in practice, because fieldOrder for GB contains no adminArea at all. Read fieldOrder before you render a field.
/render/render is a transcription of cpp/src/address_formatter.cc :: GetFormattedNationalAddress, the implementation Chromium ships. It tokenizes the template, prunes field tokens with no value and separator literals whose neighbours vanished, then assembles lines — dropping empty ones. It never changes your casing (uppercaseFields is reported, not applied), never collapses runs of spaces, and never appends the destination country: add that line yourself when you post internationally, or you would double up on the GI/GG/JE/AX/SG templates that already print their own territory name.
The two reference implementations in the repository disagree in two places that are observable in the shipped templates, and both times this endpoint follows the C++:
FormatInterpreter.getFormatString falls back to the fallback row's template when Latin script is requested and the region has no latinFormat; address_formatter.cc falls back to the region's own template. Following the C++ means ?country=DE&script=latin renders Germany's real template (postal code intact) rather than the generic one, and latinFormatAvailable: false makes the choice auditable.CI, GN and Japan's Latin one — where something follows %A on the same line.They disagree a third time about India's landmark tokens %T, %F and %L. /render accepts no landmark input, so their value really is absent: Java keeps them as field substrings without a value, which prunes the literals beside them, while address_field_util.cc's ParseFieldToken accepts only R S C D X Z A O N and drops them from the element list entirely, where they cannot prune anything. Here they behave the Java way, which is unobservable in this snapshot — there is no position in any of the 253 rows where a literal sits next to %T, %F or %L (each sits alone on its own line), and the test suite asserts that, so the day upstream breaks the tie you get a failure rather than silent drift.
%R, %1 and %2 are a different case, and this endpoint matches neither reference on purpose. Both consider them filled: AddressData.getFieldValue returns the region code for COUNTRY and the address lines for the two deprecated tokens, and the C++ maps R to COUNTRY as well — so neither prunes a literal beside them. Java then prints nothing for all three anyway (case COUNTRY: break; and the assemble switch's default:), while the C++ prints the region code for %R. /render treats all three as absent instead, because it promises never to append the destination country and exposes the second street line as the street2 param rather than as a template token. That choice is also unreachable here: the measured token inventory above carries no R, 1 or 2, so no shipped template contains %R, %1 or %2 at all — asserted by the suite too.
lineSeparator is exposed so the oneLine join is auditable. Upstream keys it on the address's language tag; /render takes no language input, so it is keyed on the region's own defaultLanguage instead (Japanese and Chinese join with nothing, Thai and Korean with a space, Arabic-script languages with U+060C, everything else with ", ") — that substitution is ours, not upstream's.
adminAreaType tells you what the level is called, never which values are valid.complete: true means every required component was supplied. Nothing more.address_strings.xml.%T, %F and %L; neither reference implementation renders them, so /render accepts no landmark input and those tokens print nothing. fieldOrder still lists them so the fact is visible rather than hidden.postalName is not an ISO 3166 name, and AC, TA and XK are not officially assigned ISO codes.Extracted from RegionDataConstants.java in Google's libaddressinput, pinned at commit 81eb9628382b (2026-05-15) together with the seven other upstream files the transformation depends on, each by SHA-256. The upstream file is marked AUTOMATICALLY GENERATED FILE - DO NOT EDIT and changes without announcement, so scripts/refresh-address-formats.mjs --check re-fetches every file, re-derives the whole table and fails on drift. Nothing is fetched while your request is served.
Google's Address Data Service — the live service carrying the postal-code regexes, the post-office URLs and the subdivision name lists — is deliberately not used, and the reason is scope and staleness, not pinnability. A snapshot of that service is pinnable: the same repository ships one at testdata/countryinfo.txt at the very commit above, and it is pinned by SHA-256 here too — not because anything reads it, but so this paragraph's reasoning stays checkable. It is a test fixture that has drifted from the metadata this endpoint is built on — 66 of the 252 region codes have a template there that disagrees with RegionDataConstants.java at the same commit, and 19 disagree on which fields are required — so building on it would ship a stale table. Its subject matter is answered elsewhere on randomapi.dev anyway (/api/postal-code-formats, /api/country-subdivisions), and the live service publishes no licence text of its own.
Largest unit first: postal code (with the 〒 mark), prefecture, street, organisation, then the recipient — the template is 〒%Z%n%S%n%A%n%O%n%N. Pass script=latin on /render and you get Japan's own Latin-script template instead, which reverses to recipient-first.
Street address, locality and postal code, plus the country itself — /lookup?country=DE returns requiredFields as country, streetAddress, locality, postalCode. Germany's template has no state slot at all, so a state field on a German checkout form will never print.
No, deliberately — this is a layout reference, not a validator. It tells you whether a country's addresses have a postal-code slot at all and where it prints, never whether a value is well-formed or deliverable. The regular expressions are not in the pinned Apache-2.0 source file this dataset is built from; that is a scope decision, and randomapi.dev answers the question elsewhere: use the sibling /api/postal-code-formats for masks, anchored regexes and shape checking, and /api/country-subdivisions for state and province names.
Because the United Kingdom declares no admin-area type, so it inherits the fallback row's province — exactly as libaddressinput's own default-rule copy does. The label is unused in practice: check fieldOrder, which for GB contains no adminArea, before you render the field at all.
RegionDataConstants.java in Google's libaddressinput (Apache-2.0 source, CC BY 4.0 data), pinned by commit and SHA-256 at the 2026-05-15 snapshot and re-verified by scripts/refresh-address-formats.mjs --check. The upstream file is marked AUTOMATICALLY GENERATED, so that parity script is the only thing standing between this table and a silent drift.
Locale-aware fake postal addresses — street, city, state, zip, country and coordinates that all agree, plus a one-line formatted form in the local layout.
Postal code masks, copy-paste validation regexes and shape checking for 178 countries — plus the 68 that have no postal code system at all.
ISO 3166-2 states, provinces and regions: 5,046 subdivision codes for 200 countries, with English names, parent codes and an auditable per-country index.
All 249 ISO 3166-1 countries and territories with codes, regions, capitals, currencies, languages, calling codes, flags and label-safe land points.
How any BCP 47 locale formats numbers, currency, dates and lists — separators, digit grouping, currency position, hour cycle and first day of week.
Canonicalize BCP 47 language tags and run RFC 4647 lookup or basic filtering with bounded, deterministic matching.