Parse Address

Intelligent Address Parsing is an optional addon that delivers preprocessing capability for difficult, incomplete, or OCR-derived addresses. It identifies structured components in raw address input before the address is sent through the existing validation workflow.

Intelligent Address Parsing complements validation. It does not replace validation and does not, by itself, confirm that an address is deliverable. It is available through the REST interface only.

Before configuring the capability, review the Prerequisites.

Make sure that you have:

• Batch REST version 8.13 or later.
• A valid product licence and the required Batch API configuration files:
  qalicn.ini, qawserve.ini, and qaworld.ini.

Installing

Intelligent Address Parsing is packaged in a separate installer. Run the installer and complete the neccessary steps. It is recommended that the installation is done within the same environment where Batch REST is installed.

During installation, the user must decide on a port number, where Intelligent Address Parsing service will run. After completing the installation, the service will run on this port.

How it works

The setup requires two services:

• Intelligent Address Parsing is an ASP.NET Core service that does the address parsing.
• Batch REST is a Java REST server that exposes the parsing end-point.

Configure

Within Batch installation folder, you must locate “application.properties” file. The file is part of the “config” folder. Edit the “application.properties“ and reflect the Intelligent Address Parsing port number.

Example:

mlparser.grpc.host=myserver
mlparser.grpc.port=9090
mlparser.grpc.deadline=PT30S

Once this is done, restart the Batch REST service.
After the restart, both services should have an additional end-point in the swagger:

/batch/address/parse/v1
/batch/address/expand/v1

Licence requirements

The parsing and expansion endpoints are licence-guarded. All of the following conditions must be met:

1. A valid product licence is present in qalicn.ini.
2. InstalledData and DataMappings in qawserve.ini are configured for the country covered by the licence.
3. qaworld.ini contains a layout with CountryBase set to the country covered by the licence.

Workflow process

1. Send the raw and unstructured address to Intelligent Address Parsing end-point.
2. Use the structured components from the response to prepare the validation request.
3. Send the structured address to the existing validation endpoint.
4. Use the validation response and status information as the source of truth for the validated address.

Use parsing before validation when the input is difficult to interpret or incomplete.

Parse an address

Use POST /batch/address/parse/v1 to identify components in an address.

Example request:

{
  "inputs": [
    {
      "reference_id": "a1",
      "input": "781 Franklin Ave Crown Heights Brooklyn NY 11216"
    }
  ]
}

Example response:

{
  "results": [
    {
      "reference_id": "a1",
      "original_search": "781 Franklin Ave Crown Heights Brooklyn NY 11216",
      "parsed_components": [
        { 
          "name": "building_number",
          "value": "781" 
        },
        { 
          "name": "street",
          "value": "franklin ave" 
        },
        { 
          "name": "sub_district", 
          "value": "crown heights" 
        },
        { 
          "name": "town", 
          "value": "brooklyn" 
        },
        { 
          "name": "region", 
          "value": "ny" 
        },
        { 
          "name": "postal_code", 
          "value": "11216" 
        }
      ]
    }
  ]
}

Expand an address

Use POST /batch/address/expand/v1 to return possible expansions for abbreviated or ambiguous address text.

Example request:

{
  "inputs": [
    {
      "reference_id": "e1",
      "input": "One-hundred twenty E 96th St"
    }
  ]
}

Example response:

{
  "results": [
    {
      "reference_id": "e1",
      "original_search": "One-hundred twenty E 96th St",
      "expansions": [
        "120 e 96th street",
        "120 east 96th street"
      ]
    }
  ]
}