{ "openapi": "3.1.1", "info": { "title": "LocaleKit Country Format Rules API", "version": "1.0.0", "summary": "Address form fields, postal-code regex, calling code and date formats for any country.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://localekit.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Address form fields, postal-code regex, calling code and date formats for any country.", "description": "Pick a country to get its address form as an ordered field schema (with required flags and local labels like PIN code or Prefecture), the postal-code pattern with examples and validation, the calling code with basic E.164 normalisation, and date/number formatting examples for the country’s likely locale.\n\nMethodology:\n- Address rules come from Google’s Address Data Service (the libaddressinput metadata used by Chromium and Android): fmt gives field order and line breaks (%N name, %O organisation, %A street, %D dependent locality, %C city, %S state/province, %Z postal code, %X sorting code), require/upper list required and upper-cased fields; missing keys fall back to the ZZ defaults.\n- Field labels use the country’s zip/state/locality/sublocality name types (e.g. PIN code, Eircode, Prefecture). Tokens not documented in the public metadata (e.g. %T, %F, %L for India) are reported as unmapped rather than guessed.\n- Postal-code validation trims, upper-cases and collapses whitespace, then tests the full string against the anchored data pattern ^(?:zip)$.\n- Phone: calling code, international and national (trunk) prefixes and possible lengths come from libphonenumber’s PhoneNumberMetadata.xml. Normalisation removes punctuation, handles \"+\" or the international prefix, otherwise strips the trunk prefix only if libphonenumber defines one (so Italy keeps its leading 0) and prepends the calling code. This is basic: carrier codes, national-prefix-for-parsing rules and number-type validation are not applied.\n- Locale: the country’s likely locale is derived with Intl.Locale(\"und-CC\").maximize() (CLDR likely subtags) and used with Intl.DateTimeFormat/NumberFormat on the fixed date 2026-12-31 13:45 UTC so day/month order is unambiguous.\n\nAddress and phone metadata change; always accept free-form input as a fallback and never reject an order solely because a postal code or phone number fails a pattern.", "tags": [ "developer" ], "x-mcp-tool": "localekit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalekitInput" }, "examples": { "example1": { "summary": "Germany: postal code + phone", "value": { "country": "DE", "postalCode": "10115", "phone": "030 901820" } }, "example2": { "summary": "India: PIN code and state field", "value": { "country": "IN", "postalCode": "110001", "phone": "+91 98765 43210" } }, "example3": { "summary": "Japan: big-to-small address order", "value": { "country": "JP", "postalCode": "154-0023" } }, "example4": { "summary": "United Kingdom: invalid postcode", "value": { "country": "GB", "postalCode": "SW1A 1AAA", "phone": "020 7946 0018" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalekitResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "LocalekitInput": { "type": "object", "additionalProperties": false, "properties": { "country": { "title": "Country", "type": "string", "enum": [ "AC", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TA", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "default": "DE" }, "postalCode": { "title": "Postal code to validate (optional)", "type": "string", "maxLength": 20 }, "phone": { "title": "Phone number to normalise (optional)", "description": "National or international format; extensions (ext. 12) are dropped.", "type": "string", "maxLength": 40 } }, "required": [ "country" ] }, "LocalekitResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "country", "countryName", "form", "postal", "subdivisions", "phone", "locale" ], "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "countryName": { "type": "string" }, "form": { "type": "object", "additionalProperties": false, "required": [ "format", "latinFormat", "fields", "unmappedTokens" ], "properties": { "format": { "type": "string" }, "latinFormat": { "type": [ "string", "null" ] }, "unmappedTokens": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "token", "label", "required", "uppercase", "line" ], "properties": { "key": { "type": "string" }, "token": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "uppercase": { "type": "boolean" }, "line": { "type": "integer", "minimum": 1 } } } } } }, "postal": { "type": "object", "additionalProperties": false, "required": [ "used", "label", "pattern", "examples", "input", "normalisedInput", "valid", "lookupUrl" ], "properties": { "used": { "type": "boolean" }, "label": { "type": "string" }, "pattern": { "type": [ "string", "null" ] }, "examples": { "type": "array", "items": { "type": "string" } }, "input": { "type": [ "string", "null" ] }, "normalisedInput": { "type": [ "string", "null" ] }, "valid": { "type": [ "boolean", "null" ] }, "lookupUrl": { "type": [ "string", "null" ] } } }, "subdivisions": { "type": "object", "additionalProperties": false, "required": [ "label", "count", "items" ], "properties": { "label": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "name", "isoCode" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "isoCode": { "type": [ "string", "null" ] } } } } } }, "phone": { "type": "object", "additionalProperties": false, "required": [ "callingCode", "internationalPrefix", "nationalPrefix", "possibleNationalLengths", "input", "e164", "nationalNumber", "plausibleLength", "steps" ], "properties": { "callingCode": { "type": [ "string", "null" ] }, "internationalPrefix": { "type": [ "string", "null" ] }, "nationalPrefix": { "type": [ "string", "null" ] }, "possibleNationalLengths": { "type": "array", "items": { "type": "integer" } }, "input": { "type": [ "string", "null" ] }, "e164": { "type": [ "string", "null" ], "pattern": "^\\+[1-9]\\d{1,14}$" }, "nationalNumber": { "type": [ "string", "null" ] }, "plausibleLength": { "type": [ "boolean", "null" ] }, "steps": { "type": "array", "items": { "type": "string" } } } }, "locale": { "type": "object", "additionalProperties": false, "required": [ "assumedLocale", "dateShort", "dateMedium", "dateLong", "time", "number", "firstDayOfWeek", "currency" ], "properties": { "assumedLocale": { "type": "string" }, "dateShort": { "type": "string" }, "dateMedium": { "type": "string" }, "dateLong": { "type": "string" }, "time": { "type": "string" }, "number": { "type": "string" }, "firstDayOfWeek": { "type": [ "string", "null" ] }, "currency": { "type": "null", "description": "ECMA-402 Intl has no region→currency mapping, so this is never guessed." } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }