Contact Us
Core, Standard, Enterprise, and OEM feature comparison

Features by license

Core gives developers a free Apache 2.0 local Java parser with dedicated country parsers and universal fallback parsing. Standard, Enterprise, and OEM licenses add curated reference data, data healing, richer country-specific parsing, field-level confidence, and trace logs for team review and operational audit needs.

Request LicenseView LicensingSubmit Edge Case

Feature summary

Core is the open-source Apache 2.0 package for development and production use. Standard, Enterprise, and OEM licenses are the commercial paths for harder international data, operational review, redistribution, and support.

The same commercial parsing capabilities are available across Standard, Enterprise, and OEM agreements; licenses differ by usage scope, redistribution rights, and commercial terms. See pricing.

CapabilityCoreStandard / Enterprise / OEM
LicenseApache License 2.0 · FreeCommercial license or agreement
DistributionGitHub: PassionCoreTech/addresstokenizer-corePrivate distribution or OEM agreement
DeploymentLocal/offline JavaLocal/offline Java
Build toolingMaven and Gradle-friendly integrationMaven and Gradle-friendly integration
Country parsersAU, CA, CA Quebec/French, DE, FR, UK, and USEverything in Core, plus HK, BR, JP, and SG
Country detectionGeoNames-assisted city-to-country resolutionCurated open-data reference datasets for enhanced country detection and enrichment
Universal fallback parser✓✓ with enhanced behavior for harder international inputs
Data healing and normalization—✓ for incomplete or inconsistent addresses
Confidence scoringOverall confidence levelField-based confidence level
Trace log—✓ for debugging and explainability
SupportCommunityCommercial support, private distribution, and enterprise or OEM terms by license
Next stepView GitHubSend Enquiry
Standard, Enterprise, Enterprise Group, and OEM use the commercial feature set. See licensing for pricing, usage-scope, and redistribution differences.

How confidence works

Core and commercial licenses both provide confidence signals, but they support different decisions. Core tells you how strong the overall parse is. Standard, Enterprise, and OEM output helps you inspect confidence field by field and understand why the parser made a decision.

Core version

Overall structural confidence

Core returns a general confidence level for the whole parsed address, based on structural signals such as street, building number, postal code, city, region, and country.

Standard / Enterprise / OEM

Field-level confidence and traceability

Commercial licenses add field-based confidence and trace logs. Teams can inspect which address fields are strong, uncertain, or reviewable, and see the detection and parser steps behind the result.

Important note

A higher confidence score does not guarantee postal deliverability. It means the tokenizer found stronger parsing, country-detection, and/or enrichment signals for the address.

Input and expected output

Core returns a parsed address, detected country, fallback behavior, and an overall confidence value. Standard, Enterprise, and OEM output returns a richer record with curated reference-data enrichment, data healing where supported, ISO 20022 mapping, field confidence, and traceable output for review.

More Countries
CA

Canada (Québec French) — street-type-first

French layout ('3700, rue Saint-Denis'); Québec French detection is included in Core.

Input

3700, rue Saint-Denis, Montreal, QC H2X 3L7

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "3700, RUE SAINT-DENIS, MONTREAL, QC H2X 3L7",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "H2X 3L7"
    },
    {
      "type": "STATE_CODE",
      "value": "QC"
    },
    {
      "type": "CITY",
      "value": "MONTREAL"
    },
    {
      "type": "HOUSE_NO",
      "value": "3700"
    },
    {
      "type": "STREET_TYPE",
      "value": "RUE"
    },
    {
      "type": "STREET_NAME",
      "value": "SAINT-DENIS"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "CA"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "3700, rue Saint-Denis, Montreal, QC H2X 3L7",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "H2X 3L7"
    },
    {
      "type": "STATE_CODE",
      "value": "QC"
    },
    {
      "type": "CITY",
      "value": "MONTREAL"
    },
    {
      "type": "HOUSE_NO",
      "value": "3700"
    },
    {
      "type": "STREET_TYPE",
      "value": "RUE"
    },
    {
      "type": "STREET_NAME",
      "value": "SAINT-DENIS"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "CA"
    },
    {
      "type": "COUNTRY",
      "value": "Canada"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.93,
      "final": 0.93
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.93
      },
      "country": {
        "confidence": 0.93
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "RUE SAINT-DENIS",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "3700",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "H2X 3L7",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "CA",
        "reason": "Country code 'CA' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "MONTREAL",
        "reason": "P3-GN-ASCII: matched in GeoNames ASCII names; base=0.93-> final=0.93"
      },
      {
        "field": "subDivision",
        "value": "CA-QC",
        "reason": "Sub-division 'CA-QC' resolved via exact ISO 3166-2 match"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "3700, rue Saint-Denis, Montreal, QC H2X 3L7",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.93,
      "final": 0.93
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "RUE SAINT-DENIS",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "3700",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "H2X 3L7",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "CA",
        "reason": "Country code 'CA' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "MONTREAL",
        "reason": "P3-GN-ASCII: matched in GeoNames ASCII names; base=0.93-> final=0.93"
      },
      {
        "field": "subDivision",
        "value": "CA-QC",
        "reason": "Sub-division 'CA-QC' resolved via exact ISO 3166-2 match"
      }
    ]
  },
  "general": {
    "countryCode": "CA",
    "countryName": "Canada",
    "streetName": "RUE SAINT-DENIS",
    "buildingName": "3700",
    "city": "MONTREAL",
    "state": "QC",
    "postalCode": "H2X 3L7",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.93
      },
      "country": {
        "confidence": 0.93
      }
    }
  },
  "iso20022Result": {
    "strtNm": "RUE SAINT-DENIS",
    "bldgNb": "3700",
    "pstCd": "H2X 3L7",
    "twnNm": "MONTREAL",
    "ctry": "CA",
    "ctrySubDvsn": "CA-QC",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.93
      },
      "ctry": {
        "confidence": 0.93
      },
      "ctrySubDvsn": {
        "confidence": 0.93
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>3700</BldgNb>
    <StrtNm>RUE SAINT-DENIS</StrtNm>
    <PstCd>H2X 3L7</PstCd>
    <TwnNm>MONTREAL</TwnNm>
    <CtrySubDvsn>CA-QC</CtrySubDvsn>
    <Ctry>CA</Ctry>
</PstlAdr>
AU

Australia — state abbreviation + G-NAF postcode

Level/unit prefix, state abbreviation NSW before a 4-digit postcode; G-NAF data confirms the postcode/locality pair.

Input

Level 3, 80 Pacific Highway, North Sydney NSW 2060

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "LEVEL 3, 80 PACIFIC HIGHWAY, NORTH SYDNEY NSW 2060",
  "tokens": [
    {
      "type": "STATE_CODE",
      "value": "NSW"
    },
    {
      "type": "POSTAL_CODE",
      "value": "2060"
    },
    {
      "type": "CITY",
      "value": "NORTH SYDNEY"
    },
    {
      "type": "UNIT",
      "value": "LEVEL 3"
    },
    {
      "type": "HOUSE_NO",
      "value": "80"
    },
    {
      "type": "STREET_NAME",
      "value": "PACIFIC"
    },
    {
      "type": "STREET_TYPE",
      "value": "HIGHWAY"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "AU"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Level 3, 80 Pacific Highway, North Sydney NSW 2060",
  "tokens": [
    {
      "type": "STATE_CODE",
      "value": "NSW"
    },
    {
      "type": "POSTAL_CODE",
      "value": "2060"
    },
    {
      "type": "CITY",
      "value": "NORTH SYDNEY"
    },
    {
      "type": "UNIT",
      "value": "LEVEL 3"
    },
    {
      "type": "HOUSE_NO",
      "value": "80"
    },
    {
      "type": "STREET_NAME",
      "value": "PACIFIC"
    },
    {
      "type": "STREET_TYPE",
      "value": "HIGHWAY"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "AU"
    },
    {
      "type": "COUNTRY",
      "value": "Australia"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.93,
      "final": 0.93
    },
    "needsReview": true,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.93
      },
      "country": {
        "confidence": 0.8
      },
      "unit": {
        "confidence": 0.65
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "PACIFIC HIGHWAY",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "80",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "2060",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: NORTH SYDNEY, NSW (AU)"
      },
      {
        "field": "country",
        "value": "AU",
        "reason": "Geographic triangulation found a low correlation (postal-code locality vs city 'NORTH SYDNEY' = 0.8; postal code '2060' vs country 'AU' = 1.0; city 'NORTH SYDNEY' vs country 'AU' = 0.93); country field confidence set to the MIN of the available signals"
      },
      {
        "field": "townName",
        "value": "NORTH SYDNEY",
        "reason": "P3-GN-ASCII: matched in GeoNames ASCII names; base=0.93-> final=0.93"
      },
      {
        "field": "subDivision",
        "value": "AU-NSW",
        "reason": "Sub-division 'AU-NSW' resolved via exact ISO 3166-2 match"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Level 3, 80 Pacific Highway, North Sydney NSW 2060",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.93,
      "final": 0.93
    },
    "needsReview": true,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "PACIFIC HIGHWAY",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "80",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "2060",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: NORTH SYDNEY, NSW (AU)"
      },
      {
        "field": "country",
        "value": "AU",
        "reason": "Geographic triangulation found a low correlation (postal-code locality vs city 'NORTH SYDNEY' = 0.8; postal code '2060' vs country 'AU' = 1.0; city 'NORTH SYDNEY' vs country 'AU' = 0.93); country field confidence set to the MIN of the available signals"
      },
      {
        "field": "townName",
        "value": "NORTH SYDNEY",
        "reason": "P3-GN-ASCII: matched in GeoNames ASCII names; base=0.93-> final=0.93"
      },
      {
        "field": "subDivision",
        "value": "AU-NSW",
        "reason": "Sub-division 'AU-NSW' resolved via exact ISO 3166-2 match"
      }
    ]
  },
  "general": {
    "countryCode": "AU",
    "countryName": "Australia",
    "streetName": "PACIFIC HIGHWAY",
    "buildingName": "80",
    "unit": "LEVEL 3",
    "city": "NORTH SYDNEY",
    "state": "NSW",
    "postalCode": "2060",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.93
      },
      "country": {
        "confidence": 0.8
      },
      "unit": {
        "confidence": 0.65
      }
    }
  },
  "iso20022Result": {
    "strtNm": "PACIFIC HIGHWAY",
    "bldgNb": "80",
    "bldgNm": "LEVEL 3",
    "pstCd": "2060",
    "twnNm": "NORTH SYDNEY",
    "ctry": "AU",
    "ctrySubDvsn": "AU-NSW",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "bldgNm": {
        "confidence": 0.65
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.93
      },
      "ctry": {
        "confidence": 0.8
      },
      "ctrySubDvsn": {
        "confidence": 0.8
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>80</BldgNb>
    <BldgNm>LEVEL 3</BldgNm>
    <StrtNm>PACIFIC HIGHWAY</StrtNm>
    <PstCd>2060</PstCd>
    <TwnNm>NORTH SYDNEY</TwnNm>
    <CtrySubDvsn>AU-NSW</CtrySubDvsn>
    <Ctry>AU</Ctry>
</PstlAdr>
DE

Germany — house number after street

German convention: street name before house number, 5-digit postcode before city.

Input

Unter den Linden 6, 10117 Berlin

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "UNTER DEN LINDEN 6, 10117 BERLIN",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "10117"
    },
    {
      "type": "CITY",
      "value": "BERLIN"
    },
    {
      "type": "HOUSE_NO",
      "value": "6"
    },
    {
      "type": "STREET_NAME",
      "value": "UNTER DEN LINDEN"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "DE"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Unter den Linden 6, 10117 Berlin",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "10117"
    },
    {
      "type": "CITY",
      "value": "BERLIN"
    },
    {
      "type": "HOUSE_NO",
      "value": "6"
    },
    {
      "type": "STREET_NAME",
      "value": "UNTER DEN LINDEN"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "DE"
    },
    {
      "type": "COUNTRY",
      "value": "Germany"
    },
    {
      "type": "TOWN_LOCATION_NAME",
      "value": "BERLIN, STADT",
      "source": "postal derived"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "UNTER DEN LINDEN",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "6",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "10117",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: BERLIN, Berlin (DE)"
      },
      {
        "field": "country",
        "value": "DE",
        "reason": "Country code 'DE' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "BERLIN",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "DE-BE",
        "reason": "Sub-division 'DE-BE' resolved via exact ISO 3166-2 match"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Unter den Linden 6, 10117 Berlin",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "UNTER DEN LINDEN",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "6",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "10117",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: BERLIN, Berlin (DE)"
      },
      {
        "field": "country",
        "value": "DE",
        "reason": "Country code 'DE' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "BERLIN",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "DE-BE",
        "reason": "Sub-division 'DE-BE' resolved via exact ISO 3166-2 match"
      }
    ]
  },
  "general": {
    "countryCode": "DE",
    "countryName": "Germany",
    "streetName": "UNTER DEN LINDEN",
    "buildingName": "6",
    "city": "BERLIN",
    "townLocation": "BERLIN, STADT",
    "postalCode": "10117",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    }
  },
  "iso20022Result": {
    "strtNm": "UNTER DEN LINDEN",
    "bldgNb": "6",
    "pstCd": "10117",
    "twnNm": "BERLIN",
    "ctry": "DE",
    "ctrySubDvsn": "DE-BE",
    "twnLctnNm": "BERLIN, STADT",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      },
      "ctrySubDvsn": {
        "confidence": 0.97
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>6</BldgNb>
    <StrtNm>UNTER DEN LINDEN</StrtNm>
    <PstCd>10117</PstCd>
    <TwnNm>BERLIN</TwnNm>
    <CtrySubDvsn>DE-BE</CtrySubDvsn>
    <Ctry>DE</Ctry>
</PstlAdr>
FR

France — street type before name

'Rue' street type precedes the name; BAN postcode data confirms 75001 → PARIS.

Input

75 Rue de Rivoli, 75001 Paris

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "75 RUE DE RIVOLI, 75001 PARIS",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "75001"
    },
    {
      "type": "CITY",
      "value": "PARIS"
    },
    {
      "type": "HOUSE_NO",
      "value": "75"
    },
    {
      "type": "STREET_TYPE",
      "value": "RUE"
    },
    {
      "type": "STREET_NAME",
      "value": "DE RIVOLI"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "FR"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "75 Rue de Rivoli, 75001 Paris",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "75001"
    },
    {
      "type": "CITY",
      "value": "PARIS"
    },
    {
      "type": "HOUSE_NO",
      "value": "75"
    },
    {
      "type": "STREET_TYPE",
      "value": "RUE"
    },
    {
      "type": "STREET_NAME",
      "value": "DE RIVOLI"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "FR"
    },
    {
      "type": "COUNTRY",
      "value": "France"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": true,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "RUE DE RIVOLI",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "75",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "75001",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: PARIS, 75 (FR)"
      },
      {
        "field": "country",
        "value": "FR",
        "reason": "Country code 'FR' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "PARIS",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "75",
        "reason": "Sub-division '75' passed through unvalidated"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "75 Rue de Rivoli, 75001 Paris",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": true,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "RUE DE RIVOLI",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "75",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "75001",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: PARIS, 75 (FR)"
      },
      {
        "field": "country",
        "value": "FR",
        "reason": "Country code 'FR' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "PARIS",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "75",
        "reason": "Sub-division '75' passed through unvalidated"
      }
    ]
  },
  "general": {
    "countryCode": "FR",
    "countryName": "France",
    "streetName": "RUE DE RIVOLI",
    "buildingName": "75",
    "city": "PARIS",
    "postalCode": "75001",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    }
  },
  "iso20022Result": {
    "strtNm": "RUE DE RIVOLI",
    "bldgNb": "75",
    "pstCd": "75001",
    "twnNm": "PARIS",
    "ctry": "FR",
    "ctrySubDvsn": "75",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      },
      "ctrySubDvsn": {
        "confidence": 0.55
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>75</BldgNb>
    <StrtNm>RUE DE RIVOLI</StrtNm>
    <PstCd>75001</PstCd>
    <TwnNm>PARIS</TwnNm>
    <CtrySubDvsn>75</CtrySubDvsn>
    <Ctry>FR</Ctry>
</PstlAdr>
HK

Hong Kong — Standard / Enterprise / OEM parser

Flat/floor/building tokens, no postal code. HK parsing is a Standard / Enterprise / OEM parser — see the Core output for what the free tier does with it.

Input

Flat 25, 12/F, Acacia Building, 150 Kennedy Road, Wan Chai, Hong Kong

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "FLAT 25, 12/F, ACACIA BUILDING, 150 KENNEDY ROAD, WAN CHAI, HONG KONG",
  "tokens": [
    {
      "type": "STREET_NAME",
      "value": "FLAT 25"
    },
    {
      "type": "CITY",
      "value": "12/F"
    },
    {
      "type": "CITY",
      "value": "ACACIA BUILDING"
    },
    {
      "type": "CITY",
      "value": "150 KENNEDY ROAD"
    },
    {
      "type": "CITY",
      "value": "WAN CHAI"
    },
    {
      "type": "CITY",
      "value": "HONG KONG"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "HK"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.77,
      "gazetteer": 0.77,
      "final": 0.77
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Flat 25, 12/F, Acacia Building, 150 Kennedy Road, Wan Chai, Hong Kong",
  "tokens": [
    {
      "type": "UNIT",
      "value": "FLAT 25"
    },
    {
      "type": "FLOOR",
      "value": "12/F"
    },
    {
      "type": "BUILDING_NAME",
      "value": "ACACIA BUILDING"
    },
    {
      "type": "HOUSE_NO",
      "value": "150"
    },
    {
      "type": "STREET_NAME",
      "value": "KENNEDY ROAD"
    },
    {
      "type": "DISTRICT",
      "value": "WAN CHAI"
    },
    {
      "type": "CITY",
      "value": "HONG KONG"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "HK"
    },
    {
      "type": "COUNTRY",
      "value": "Hong Kong SAR China",
      "original": "HK"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.82,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      },
      "unit": {
        "confidence": 0.65
      },
      "district": {
        "confidence": 0.6
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "KENNEDY ROAD",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "150",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "country",
        "value": "HK",
        "reason": "Country code 'HK' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "HONG KONG",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Flat 25, 12/F, Acacia Building, 150 Kennedy Road, Wan Chai, Hong Kong",
  "diagnostics": {
    "confidence": {
      "parse": 0.82,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "KENNEDY ROAD",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "150",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "country",
        "value": "HK",
        "reason": "Country code 'HK' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "HONG KONG",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      }
    ]
  },
  "general": {
    "countryCode": "HK",
    "countryName": "Hong Kong SAR China",
    "streetName": "KENNEDY ROAD",
    "buildingName": "150",
    "unit": "FLAT 25",
    "floor": "12/F",
    "city": "HONG KONG",
    "district": "WAN CHAI",
    "parseConfidence": 0.82,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      },
      "unit": {
        "confidence": 0.65
      },
      "district": {
        "confidence": 0.6
      }
    }
  },
  "iso20022Result": {
    "strtNm": "KENNEDY ROAD",
    "bldgNb": "150",
    "bldgNm": "FLAT 25 ACACIA BUILDING",
    "twnNm": "HONG KONG",
    "ctry": "HK",
    "dstrct": "WAN CHAI",
    "flr": "12/F",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "bldgNm": {
        "confidence": 0.65
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <Flr>12/F</Flr>
    <BldgNb>150</BldgNb>
    <BldgNm>FLAT 25 ACACIA BUILDING</BldgNm>
    <StrtNm>KENNEDY ROAD</StrtNm>
    <TwnNm>HONG KONG</TwnNm>
    <Dstrct>WAN CHAI</Dstrct>
    <Ctry>HK</Ctry>
</PstlAdr>
GB

United Kingdom — 10 Downing Street

Postcode at end (SW1A 2AA). Core detects GB from the postcode pattern; Standard / Enterprise / OEM validates LONDON against the gazetteer.

Input

10 Downing Street, London SW1A 2AA

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "10 DOWNING STREET, LONDON SW1A 2AA",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "SW1A 2AA"
    },
    {
      "type": "CITY",
      "value": "LONDON"
    },
    {
      "type": "HOUSE_NO",
      "value": "10"
    },
    {
      "type": "STREET_NAME",
      "value": "DOWNING"
    },
    {
      "type": "STREET_TYPE",
      "value": "STREET"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "GB"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "10 Downing Street, London SW1A 2AA",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "SW1A 2AA"
    },
    {
      "type": "CITY",
      "value": "LONDON"
    },
    {
      "type": "HOUSE_NO",
      "value": "10"
    },
    {
      "type": "STREET_NAME",
      "value": "DOWNING"
    },
    {
      "type": "STREET_TYPE",
      "value": "STREET"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "GB"
    },
    {
      "type": "COUNTRY",
      "value": "United Kingdom"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "DOWNING STREET",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "10",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "SW1A 2AA",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "GB",
        "reason": "Country code 'GB' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "LONDON",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "10 Downing Street, London SW1A 2AA",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "DOWNING STREET",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "10",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "SW1A 2AA",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "GB",
        "reason": "Country code 'GB' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "LONDON",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      }
    ]
  },
  "general": {
    "countryCode": "GB",
    "countryName": "United Kingdom",
    "streetName": "DOWNING STREET",
    "buildingName": "10",
    "city": "LONDON",
    "postalCode": "SW1A 2AA",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    }
  },
  "iso20022Result": {
    "strtNm": "DOWNING STREET",
    "bldgNb": "10",
    "pstCd": "SW1A 2AA",
    "twnNm": "LONDON",
    "ctry": "GB",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>10</BldgNb>
    <StrtNm>DOWNING STREET</StrtNm>
    <PstCd>SW1A 2AA</PstCd>
    <TwnNm>LONDON</TwnNm>
    <Ctry>GB</Ctry>
</PstlAdr>
US

United States — civic address, New York

House number precedes street, ZIP at end, 2-letter state. Gazetteer confirms NEW YORK via OurAirports municipality (P2); sub-division resolved to US-NY.

Input

350 Fifth Avenue, New York, NY 10118

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "350 FIFTH AVENUE, NEW YORK, NY 10118",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "10118"
    },
    {
      "type": "STATE_CODE",
      "value": "NY"
    },
    {
      "type": "CITY",
      "value": "NEW YORK"
    },
    {
      "type": "HOUSE_NO",
      "value": "350"
    },
    {
      "type": "STREET_NAME",
      "value": "FIFTH"
    },
    {
      "type": "STREET_TYPE",
      "value": "AVENUE"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "US"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "350 Fifth Avenue, New York, NY 10118",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "10118"
    },
    {
      "type": "STATE_CODE",
      "value": "NY"
    },
    {
      "type": "CITY",
      "value": "NEW YORK"
    },
    {
      "type": "HOUSE_NO",
      "value": "350"
    },
    {
      "type": "STREET_NAME",
      "value": "FIFTH"
    },
    {
      "type": "STREET_TYPE",
      "value": "AVENUE"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "US"
    },
    {
      "type": "COUNTRY",
      "value": "United States"
    },
    {
      "type": "DISTRICT",
      "value": "NEW YORK",
      "source": "postal derived"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "FIFTH AVENUE",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "350",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "10118",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: NEW YORK, New York (US)"
      },
      {
        "field": "country",
        "value": "US",
        "reason": "Country code 'US' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "NEW YORK",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "US-NY",
        "reason": "Sub-division 'US-NY' resolved via exact ISO 3166-2 match"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "350 Fifth Avenue, New York, NY 10118",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "FIFTH AVENUE",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "350",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "10118",
        "reason": "Parsed from raw input (confidence=0.8); confirmed: NEW YORK, New York (US)"
      },
      {
        "field": "country",
        "value": "US",
        "reason": "Country code 'US' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "NEW YORK",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "US-NY",
        "reason": "Sub-division 'US-NY' resolved via exact ISO 3166-2 match"
      }
    ]
  },
  "general": {
    "countryCode": "US",
    "countryName": "United States",
    "streetName": "FIFTH AVENUE",
    "buildingName": "350",
    "city": "NEW YORK",
    "district": "NEW YORK",
    "state": "NY",
    "postalCode": "10118",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      }
    }
  },
  "iso20022Result": {
    "strtNm": "FIFTH AVENUE",
    "bldgNb": "350",
    "pstCd": "10118",
    "twnNm": "NEW YORK",
    "ctry": "US",
    "ctrySubDvsn": "US-NY",
    "dstrct": "NEW YORK",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      },
      "ctrySubDvsn": {
        "confidence": 0.97
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>350</BldgNb>
    <StrtNm>FIFTH AVENUE</StrtNm>
    <PstCd>10118</PstCd>
    <TwnNm>NEW YORK</TwnNm>
    <Dstrct>NEW YORK</Dstrct>
    <CtrySubDvsn>US-NY</CtrySubDvsn>
    <Ctry>US</Ctry>
</PstlAdr>
CA

Canada (English) — multiple unit tokens

Two unit tokens (Unit 100, Suite 1002) ahead of the civic address; alternating letter-digit postal code.

Input

Unit 100, Suite 1002, 123 Bay Street, Toronto, ON M5H 2N2

Core version

Core interface and expected output

InterfaceAddressTokenizer.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "UNIT 100, SUITE 1002, 123 BAY STREET, TORONTO, ON M5H 2N2",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "M5H 2N2"
    },
    {
      "type": "STATE_CODE",
      "value": "ON"
    },
    {
      "type": "UNIT",
      "value": "UNIT 100"
    },
    {
      "type": "UNIT",
      "value": "SUITE 1002"
    },
    {
      "type": "HOUSE_NO",
      "value": "123"
    },
    {
      "type": "STREET_NAME",
      "value": "BAY"
    },
    {
      "type": "STREET_TYPE",
      "value": "STREET"
    },
    {
      "type": "CITY",
      "value": "TORONTO"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "CA"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.95,
      "final": 0.95
    },
    "needsReview": false
  }
}
Standard / Enterprise / OEM

Commercial interface and expected output

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Unit 100, Suite 1002, 123 Bay Street, Toronto, ON M5H 2N2",
  "tokens": [
    {
      "type": "POSTAL_CODE",
      "value": "M5H 2N2"
    },
    {
      "type": "STATE_CODE",
      "value": "ON"
    },
    {
      "type": "UNIT",
      "value": "UNIT 100"
    },
    {
      "type": "UNIT",
      "value": "SUITE 1002"
    },
    {
      "type": "HOUSE_NO",
      "value": "123"
    },
    {
      "type": "STREET_NAME",
      "value": "BAY"
    },
    {
      "type": "STREET_TYPE",
      "value": "STREET"
    },
    {
      "type": "CITY",
      "value": "TORONTO"
    },
    {
      "type": "COUNTRY_CODE",
      "value": "CA"
    },
    {
      "type": "COUNTRY",
      "value": "Canada"
    }
  ],
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      },
      "unit": {
        "confidence": 0.65
      }
    },
    "traceLogs": [
      {
        "field": "streetName",
        "value": "BAY STREET",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "123",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "M5H 2N2",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "CA",
        "reason": "Country code 'CA' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "TORONTO",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "CA-ON",
        "reason": "Sub-division 'CA-ON' resolved via exact ISO 3166-2 match"
      }
    ]
  }
}
GET /enrich · Standard / Enterprise / OEM

Full enrichment output — reference data, healing, and ISO 20022 mapping

Same parse, taken further: curated reference-data enrichment, data healing where supported, field-level confidence, traceable output, and ISO 20022 / pacs.008 mapping.

InterfaceAddressEnrichmentService.parse(String rawAddress)io.passioncore.addresstokenizer.model.ParsedAddress
Expected output
{
  "raw": "Unit 100, Suite 1002, 123 Bay Street, Toronto, ON M5H 2N2",
  "diagnostics": {
    "confidence": {
      "parse": 0.95,
      "gazetteer": 0.97,
      "final": 0.97
    },
    "needsReview": false,
    "countryCodeStatus": "VALID_ISO3166",
    "inputStructure": "STRUCTURED",
    "cbprStructured": true,
    "fintracPoBoxInvalid": false,
    "traceLogs": [
      {
        "field": "streetName",
        "value": "BAY STREET",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "buildingName",
        "value": "123",
        "reason": "Parsed from raw input (token confidence=0.7)"
      },
      {
        "field": "postalCode",
        "value": "M5H 2N2",
        "reason": "Parsed from raw input (confidence=0.8)"
      },
      {
        "field": "country",
        "value": "CA",
        "reason": "Country code 'CA' is a valid ISO 3166-1 alpha-2 code"
      },
      {
        "field": "townName",
        "value": "TORONTO",
        "reason": "P2-OA-MUNI: matched in OurAirports municipality; base=0.97-> final=0.97"
      },
      {
        "field": "subDivision",
        "value": "CA-ON",
        "reason": "Sub-division 'CA-ON' resolved via exact ISO 3166-2 match"
      }
    ]
  },
  "general": {
    "countryCode": "CA",
    "countryName": "Canada",
    "streetName": "BAY STREET",
    "buildingName": "123",
    "unit": "UNIT 100",
    "city": "TORONTO",
    "state": "ON",
    "postalCode": "M5H 2N2",
    "parseConfidence": 0.95,
    "fieldConfidences": {
      "streetName": {
        "confidence": 0.7
      },
      "buildingName": {
        "confidence": 0.7
      },
      "postalCode": {
        "confidence": 0.8
      },
      "townName": {
        "confidence": 0.97
      },
      "country": {
        "confidence": 0.97
      },
      "unit": {
        "confidence": 0.65
      }
    }
  },
  "iso20022Result": {
    "strtNm": "BAY STREET",
    "bldgNb": "123",
    "bldgNm": "UNIT 100 SUITE 1002",
    "pstCd": "M5H 2N2",
    "twnNm": "TORONTO",
    "ctry": "CA",
    "ctrySubDvsn": "CA-ON",
    "fieldConfidence": {
      "strtNm": {
        "confidence": 0.7
      },
      "bldgNb": {
        "confidence": 0.7
      },
      "bldgNm": {
        "confidence": 0.65
      },
      "pstCd": {
        "confidence": 0.8
      },
      "twnNm": {
        "confidence": 0.97
      },
      "ctry": {
        "confidence": 0.97
      },
      "ctrySubDvsn": {
        "confidence": 0.97
      }
    }
  }
}
pacs.008 XMLPacs008AddressSerializer.serialize(PostalAddress)pacs.008 PostalAddress XML fragment
pacs.008 XML serializer output
<PstlAdr>
    <BldgNb>123</BldgNb>
    <BldgNm>UNIT 100 SUITE 1002</BldgNm>
    <StrtNm>BAY STREET</StrtNm>
    <PstCd>M5H 2N2</PstCd>
    <TwnNm>TORONTO</TwnNm>
    <CtrySubDvsn>CA-ON</CtrySubDvsn>
    <Ctry>CA</Ctry>
</PstlAdr>
Real-world cases

Edge cases carousel

A few selected cases show how the parser behaves when input is valid but imperfect: PO boxes, country aliases, city typos, long street names, and multi-line payment-style addresses.

View all edge casesSubmit an edge case
Edge case

PO Box — FINTRAC non-compliant (CA)

Canadian FINTRAC rules for cross-border EFT require a civic street address. A PO Box without a street line sets fintracPoBoxInvalid=true.

Input

PO Box 9000, Victoria, BC V8W 9V6

Review summary
{
  "country": "CA",
  "confidence": {
    "parse": 0.9,
    "gazetteer": 0.75,
    "final": 0.75
  },
  "needsReview": false,
  "inputStructure": "STRUCTURED",
  "countryCodeStatus": "VALID_ISO3166",
  "fieldConfidence": "available in commercial output"
}
Edge case

City + country only — HYBRID pacs.008 shape

No street name is present, so PostalAddress.resolveType() falls through to HYBRID. TwnNm and Ctry are emitted as structured elements; nothing goes into AdrLine.

Input

London, United Kingdom

Review summary
{
  "country": "GB",
  "confidence": {
    "parse": 0.63,
    "gazetteer": 0,
    "final": 0
  },
  "needsReview": true,
  "inputStructure": "UNSTRUCTURED",
  "countryCodeStatus": "VALID_ISO3166",
  "fieldConfidence": "available in commercial output"
}
Edge case

Country name variant — normalised to ISO code

PostalAddress.Builder.normalizeCountry() converts 'United States of America'-> 'US'. countryCodeStatus = KNOWN_ALIAS_NORMALIZED (not VALID_ISO3166) so needsReview may be set.

Input

1600 Pennsylvania Avenue NW, Washington DC 20500, United States of America

Review summary
{
  "country": "US",
  "confidence": {
    "parse": 0.95,
    "gazetteer": 0.97,
    "final": 0.97
  },
  "needsReview": false,
  "inputStructure": "STRUCTURED",
  "countryCodeStatus": "VALID_ISO3166",
  "fieldConfidence": "available in commercial output"
}
Edge case

City typo — still resolved by gazetteer

'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.

Input

123 Bay Street, Tronoto, ON M5J 2T3

Review summary
{
  "country": "CA",
  "confidence": {
    "parse": 0.95,
    "gazetteer": 0.55,
    "final": 0.45000000000000007
  },
  "needsReview": true,
  "inputStructure": "STRUCTURED",
  "countryCodeStatus": "VALID_ISO3166",
  "fieldConfidence": "available in commercial output"
}
Universal fallback

Fallback parser behavior

Countries without a dedicated parser are still handled on a best-effort basis. The output remains deterministic, but confidence is usually lower and needsReview is used to keep review workflows honest.

View out-of-scope examplesSend us a fallback case

What fallback means

The fallback parser extracts what it can from unknown or unsupported country formats instead of failing hard. It is useful for intake, triage, and review queues.

How to interpret it

When a country has no dedicated parser, treat lower confidence and needsReview = true as a signal for manual review, custom parser work, or commercial support.

China (romanised)1 Zhongshan East 1st Road, Huangpu District, Shanghai 200002, China
China (native script)上海市黄浦区中山东一路1号
IndiaFlat 4B, 12 MG Road, Bengaluru, Karnataka 560001, India
South Korea166 Sejong-daero, Jung-gu, Seoul 04520, South Korea
These examples are representative product showcase outputs. Actual output may vary by license, version, enabled country data, and parser configuration. Core examples focus on general parsing confidence. Standard, Enterprise, and OEM examples may include field-level confidence, traceable enrichment, and ISO 20022 mapping where supported. Annotation fields in the source showcase file are used for page context and are not displayed as customer output fields. For deeper edge cases, hostile-input checks, and current out-of-scope examples, see the showcase cases. Think an address should parse differently? Submit the edge case.