Use this page to review representative parser behavior without exposing internal implementation details. The homepage and feature pages show the most attractive supported-country examples; this page keeps the deeper edge cases available for technical evaluators.
Representative outputs for currently showcased dedicated parsers. These examples are suitable for product evaluation and quick understanding.
House number precedes street, ZIP at end, 2-letter state. Gazetteer confirms NEW YORK via OurAirports municipality (P2); sub-division resolved to US-NY.
350 Fifth Avenue, New York, NY 10118
{
"country": "US",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Postcode at end (SW1A 2AA). Core detects GB from the postcode pattern; Pro validates LONDON against the gazetteer.
10 Downing Street, London SW1A 2AA
{
"country": "GB",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}German convention: street name before house number, 5-digit postcode before city.
Unter den Linden 6, 10117 Berlin
{
"country": "DE",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}'Rue' street type precedes the name; BAN postcode data confirms 75001 → PARIS.
75 Rue de Rivoli, 75001 Paris
{
"country": "FR",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Level/unit prefix, state abbreviation NSW before a 4-digit postcode; G-NAF data confirms the postcode/locality pair.
Level 3, 80 Pacific Highway, North Sydney NSW 2060
{
"country": "AU",
"confidence": {
"parse": 0.95,
"gazetteer": 0.93,
"final": 0.93
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Two unit tokens (Unit 100, Suite 1002) ahead of the civic address; alternating letter-digit postal code.
Unit 100, Suite 1002, 123 Bay Street, Toronto, ON M5H 2N2
{
"country": "CA",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}French layout ('3700, rue Saint-Denis'); Québec French detection is included in Core.
3700, rue Saint-Denis, Montreal, QC H2X 3L7
{
"country": "CA",
"confidence": {
"parse": 0.95,
"gazetteer": 0.93,
"final": 0.93
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Flat/floor/building tokens, no postal code. HK parsing is a Pro-tier parser — see the Core output for what the free tier does with it.
Flat 25, 12/F, Acacia Building, 150 Kennedy Road, Wan Chai, Hong Kong
{
"country": "HK",
"confidence": {
"parse": 0.82,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Selected real-world edge cases that show review signals, field confidence, compliance flags, and parser behavior when input is incomplete or unusual.
Found an address that should parse differently? Send us the anonymized input and expected behavior.
Canadian FINTRAC rules for cross-border EFT require a civic street address. A PO Box without a street line sets fintracPoBoxInvalid=true.
PO Box 9000, Victoria, BC V8W 9V6
{
"country": "CA",
"confidence": {
"parse": 0.9,
"gazetteer": 0.75,
"final": 0.75
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166",
"fintracPoBoxInvalid": true
}No street name is present, so PostalAddress.resolveType() falls through to HYBRID. TwnNm and Ctry are emitted as structured elements; nothing goes into AdrLine.
London, United Kingdom
{
"country": "GB",
"confidence": {
"parse": 0.63,
"gazetteer": 0,
"final": 0
},
"needsReview": true,
"inputStructure": "UNSTRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}PostalAddress.Builder.normalizeCountry() converts 'United States of America'-> 'US'. countryCodeStatus = KNOWN_ALIAS_NORMALIZED (not VALID_ISO3166) so needsReview may be set.
1600 Pennsylvania Avenue NW, Washington DC 20500, United States of America
{
"country": "US",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}'Tronoto' is not in OurAirports directly. The gazetteer falls through its priority levels; if no fuzzy match fires, confidence drops to P8 (0.55) and needsReview=true.
123 Bay Street, Tronoto, ON M5J 2T3
{
"country": "CA",
"confidence": {
"parse": 0.95,
"gazetteer": 0.55,
"final": 0.45000000000000007
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}Some US addresses encode the unit in the civic number field ('1234A'). The parser emits a HOUSE_NO token with the full value; it should not be split.
1234A Main Street, Springfield, IL 62701
{
"country": "US",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}MT103 field 70 delivers addresses as 35-char lines. parseLines preserves line boundaries so parsers can use positional logic across lines.
10 Downing Street London SW1A 2AA United Kingdom
{
"country": "GB",
"confidence": {
"parse": 0.95,
"gazetteer": 0.75,
"final": 0.75
},
"needsReview": false,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}pacs.008 limits StrtNm to 70 characters. Any excess is silently truncated by PostalAddress.Builder.streetName(). The raw street name is preserved in iso20022Result.
1 Extraordinarily Long Boulevard Name That Exceeds The Seventy Character Limit Street, New York, NY 10001
{
"country": "FR",
"confidence": {
"parse": 0.82,
"gazetteer": 0.55,
"final": 0.55
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}When no country is detected and no postal code pattern fires, CountryDetector returns UNKNOWN. Without a valid Ctry, PostalAddress resolveType() returns UNSTRUCTURED, and the serializer emits a WARNING comment in the XML output.
somewhere on a street in a place
{
"country": "GB",
"confidence": {
"parse": 0.63,
"gazetteer": 0,
"final": 0
},
"needsReview": true,
"inputStructure": "UNSTRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}"Hong Kong" appears twice as an unrelated organization/building name, tied on length with the trailing "AUSTRALIA" declaration — CountryDetector's tie-break resolves to the trailing one. The suburb ("SYDNEY") has no comma separating it from the street, so AuAddressParser reads it from the text after the street type instead. Postcode 2000 maps to several named localities (Sydney, Barangaroo, Darling Harbour, ...); the parsed city is checked against all of them, not just one arbitrary pick, so it resolves at high confidence instead of a false CROSS_CITY_MISMATCH penalty.
Hong Kong Tourism Board - Sydney Office Level 4 Hong Kong House 80 Druitt Street SYDNEY NSW 2000 ,NEW SOUTH WALES, AUSTRALIA
{
"country": "AU",
"confidence": {
"parse": 0.9,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}AU commercial buildings commonly number suites as <level>.<unit> ("Suite 14.02" = suite 02 on level 14). The UNIT value must retain the dot rather than truncating at it.
Suite 14.02, Level 14, 31 Market Street, Sydney, NSW 2009
{
"country": "AU",
"confidence": {
"parse": 0.95,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "VALID_ISO3166"
}No Latin characters at all — CountryDetector recognises this via its CJK-character branch (unrelated to the COUNTRY_NAME_HINT text-scan used for Latin-script addresses), and HkChineseAddressHealer.translateToEnglish() runs before SWIFT normalisation to convert region (香港 -> Hong Kong), district (灣仔 -> Wan Chai), street (堅尼地道 -> Kennedy Road), house number, floor (楼 -> /F), and unit (室 -> Unit) into the Latin-script line order HkAddressParser expects.
香港灣仔堅尼地道105號雅佳大廈12樓25室
{
"country": "HK",
"confidence": {
"parse": 0.68,
"gazetteer": 0.97,
"final": 0.97
},
"needsReview": false,
"inputStructure": "HYBRID",
"countryCodeStatus": "VALID_ISO3166"
}Small examples used to show that the Core parser handles blank, punctuation-only, and ambiguous inputs without crashing.
Punctuation-only input: nothing survives normalisation; country UNKNOWN.
!!!???
{
"country": null,
"tokens": [
{
"type": "STREET_NAME",
"value": "???"
}
]
}Blank address returns an empty parse rather than an error.
(empty string)
{
"country": null,
"tokens": []
}A bare UK postcode is enough for Core to detect GB.
SW1A 2AA
{
"country": "GB",
"tokens": [
{
"type": "POSTAL_CODE",
"value": "SW1A 2AA"
},
{
"type": "COUNTRY_CODE",
"value": "GB"
}
]
}Diacritics (Gauchetière, Montréal) are normalised to SWIFT-safe ASCII.
1000 rue de la Gauchetière Ouest, Bureau 2500, Montréal, QC H3B 4W5
{
"country": "CA",
"tokens": [
{
"type": "POSTAL_CODE",
"value": "H3B 4W5"
},
{
"type": "STATE_CODE",
"value": "QC"
},
{
"type": "CITY",
"value": "BUREAU 2500 MONTREAL"
},
{
"type": "HOUSE_NO",
"value": "1000"
},
{
"type": "STREET_TYPE",
"value": "RUE"
},
{
"type": "STREET_NAME",
"value": "DE LA GAUCHETIERE"
}
]
}'75001 Paris' with no street context: the 5-digit pattern is ambiguous between DE and FR — Core picks DE. Honest limitation: postcode alone cannot disambiguate.
75001 Paris
{
"country": "DE",
"tokens": [
{
"type": "POSTAL_CODE",
"value": "75001"
},
{
"type": "CITY",
"value": "PARIS"
},
{
"type": "COUNTRY_CODE",
"value": "DE"
}
]
}'10117 Berlin' — same ambiguity, and here DE happens to be correct.
10117 Berlin
{
"country": "DE",
"tokens": [
{
"type": "POSTAL_CODE",
"value": "10117"
},
{
"type": "CITY",
"value": "BERLIN"
},
{
"type": "COUNTRY_CODE",
"value": "DE"
}
]
}Examples outside current dedicated parser coverage. These are intentionally shown as limitations so users know when review or custom parser work may be needed.
If one of these fallback-style cases matters to your workflow, submit the case you expected us to handle.
Country detected from the trailing name, but no CN parser exists: the district lands in the city field and confidence drops to the P8 floor (0.55), needsReview=true.
1 Zhongshan East 1st Road, Huangpu District, Shanghai 200002, China
{
"country": "CN",
"confidence": {
"parse": 0.9,
"gazetteer": 0.55,
"final": 0.55
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "UNSUPPORTED"
}Core has no CJK handling — SWIFT normalisation strips the script entirely, leaving '1'. Pro returns UNKNOWN with confidence 0.0. Fully out of scope.
上海市黄浦区中山东一路1号
{
"country": "UNKNOWN",
"confidence": {
"parse": 0.53,
"gazetteer": 0,
"final": 0
},
"needsReview": true,
"inputStructure": "UNSTRUCTURED",
"countryCodeStatus": "KNOWN_ALIAS_NORMALIZED"
}The 6-digit PINCODE pattern is recognised for country detection, but with no IN parser the street ('12 MG Road') is misread as the city. Confidence 0.25, needsReview=true.
Flat 4B, 12 MG Road, Bengaluru, Karnataka 560001, India
{
"country": "IN",
"confidence": {
"parse": 0.9,
"gazetteer": 0.55,
"final": 0.55
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "UNSUPPORTED"
}Country detected from the name; the district (Jung-gu) is misread as the city. Confidence 0.35, needsReview=true.
166 Sejong-daero, Jung-gu, Seoul 04520, South Korea
{
"country": "KR",
"confidence": {
"parse": 0.9,
"gazetteer": 0.55,
"final": 0.55
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "UNSUPPORTED"
}The gazetteer resolves CUAUHTEMOC (0.93) because it is a real municipality — but it is the borough, not the town, and needsReview is still raised. Plausible-looking output still needs a dedicated MX parser.
Av. Paseo de la Reforma 483, Cuauhtémoc, 06500 Ciudad de México, CDMX, Mexico
{
"country": "MX",
"confidence": {
"parse": 0.9,
"gazetteer": 0.93,
"final": 0.93
},
"needsReview": true,
"inputStructure": "STRUCTURED",
"countryCodeStatus": "UNSUPPORTED"
}Address Tokenizer is designed for parsing, tokenization, normalization, confidence analysis, and data harmonization. It is not a geocoder, postal deliverability checker, or official government address verification service.
The library does not return latitude/longitude or route-planning results.
A successful parse does not mean the address can receive mail.
Countries without dedicated parsers use fallback behavior and should be treated as reviewable when confidence is low.
Native-script addresses outside supported parsers may normalize poorly and can require custom parser work.