Address Search

The Address Search service returns a formatted address based on the unformatted address input by you. The formatted address is useful for matching with customer addresses that may be stored in third-party systems. The Address Search service can utilize one of three different third-party address processors: Azure Address Search, Google's Geocode Search, or HERE Geocode Search.

If no service type is specified, the Azure Address Search is used.

Service Configuration

Branches

• validAddress: A valid result was found.

• invalidAddress: No valid result was found.

Input

• address: The unformatted address to resolve.

• apiKey: API key for the Address API to be used. This field is optional; if left empty, a key owned by Parloa will be used for the service requests. If you want to use your own key, enter it as the value of this field.

• service: One of azure, google, or here.

• language: Language of the input, for example, de.

• country: Restrict results to this country. Google and Azure require a 2-letter country code (e.g., DE), while HERE expects a 3-letter country code (for example, DEU).

• postalCode: Optional value that restricts results to this postal code.

• limit: Optional value that limits the number of results. Min=1, Max=3. If left empty, the default value is 3.

• skipUnset: Set to a non-empty value to activate. If active, output parameters with empty values will not be set. Note: This will cause Parloa to retain old values instead of resetting them when calling the service multiple times.

• rawOutput: Optional value that returns the raw result from the Address API. Set to a non-empty value to activate.

Output

• formattedAddress: The first result as a properly formatted address string.

The fields listed below will contain the values of the formatted address separately, according to the variable name:

• postalCode

• city

• street

• streetNumber

• country

• state

• county

• apartment

• position

  • lat

  • lng

These parameters are repeated for the second and third results when multiple results are returned: formattedAddress2, postalCode2, city2, street2, streetNumber2, country2, state2, county2, formattedAddress3, postalCode3, city3, street3, streetNumber3, country3, state3, county3.

• rawOutput: Direct API result if activated.

Technical Configuration

• URL: https://parloaservices.azurewebsites.net/api/AddressResolver?clientId=<CLIENT_ID>

• x-functions-key: <AUTHCODE> (You can obtain your AUTHCODE and CLIENTID from your Parloa representative).

Note: The URL provided does not include the API key, which is required in the header (x-functions-key) to access the API.

Dialog Usage

Add the service to your dialog as usual. A sample input set is shown below:

Sample input values for the Address Search service

Result Examples

Sample Request and Response

Address search using Azure search with input fields:

address

Schönhauser Allee 9, Berlin

service

azure

country

DE

limit

1

Output fields showing the results, limited to the first address only.

formattedAddress

Schönhauser Allee 9, 10119 Berlin

postalCode

10119

city

Berlin

street

Schönhauser Allee

streetNumber

9

country

Deutschland

state

county

Berlin

position

lat: 52.53007
lng: 13.41091

The rest of the output fields will be set to empty.

Sample Request with Raw Output

Address search using Azure search with input fields:

address

Schönhauser Allee 9, 10119 Berlin

service

azure

country

DE

limit

1

rawOutput

1

Output fields showing the results, limited to the first address only. The raw output field at the bottom shows the raw result format for the Azure Search service; the other two search services may have differing raw formats:

formattedAddress

Schönhauser Allee 9, 10119 Berlin

postalCode

10119

city

Berlin

street

Schönhauser Allee

streetNumber

9

country

Deutschland

state

county

Berlin

rawOutput

{
    "summary": {
        "query": "schönhauser allee 9 10119 berlin",
        "queryType": "NON_NEAR",
        "queryTime": 23,
        "numResults": 1,
        "offset": 0,
        "totalResults": 2,
        "fuzzyLevel": 1,
        "geoBias": {
            "lat": 51.163375,
            "lon": 10.447683
        }
    },
    "results": [
        {
            "type": "Point Address",
            "id": "BTdC_I73pJf-Z3PP4oy0vQ",
            "score": 1,
            "dist": 253990.83071992802,
            "matchConfidence": {
                "score": 1
            },
            "address": {
                "streetNumber": "9",
                "streetName": "Schönhauser Allee",
                "municipalitySubdivision": "Prenzlauer Berg",
                "municipality": "Berlin",
                "countrySecondarySubdivision": "Berlin",
                "countrySubdivision": "Berlin",
                "countrySubdivisionName": "Berlin",
                "countrySubdivisionCode": "BE",
                "postalCode": "10119",
                "countryCode": "DE",
                "country": "Deutschland",
                "countryCodeISO3": "DEU",
                "freeformAddress": "Schönhauser Allee 9, 10119 Berlin",
                "localName": "Berlin"
            },
            "position": {
                "lat": 52.53008,
                "lon": 13.41091
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 52.53098,
                    "lon": 13.40943
                },
                "btmRightPoint": {
                    "lat": 52.52918,
                    "lon": 13.41239
                }
            },
            "entryPoints": [
                {
                    "type": "main",
                    "position": {
                        "lat": 52.53018,
                        "lon": 13.41068
                    }
                }
            ]
        }
    ]
}

The rest of the output fields will be set to empty.

FAQ

Which of the three service providers should I choose?

Internal tests have shown that the HERE API provides more accurate results, especially when there is missing information in the address API request. Therefore, it is recommended to start with the HERE API.