Loqate Integration

Loqate is a third-party address standardization service that, when integrated with STEP, is used to return standardized addresses that adhere to the standards of local postal authorities such as the USPS. Standardized addresses are essential to securing safe postal deliveries and also help save money when doing mass mailings. A fully standardized address is also a first step in customer deduplication (finding and removing duplicate records containing these addresses) using Matching, Linking, and Merging, as covered in the Matching, Linking, and Merging documentation here.

Customers can receive an API key with a free trial account. Contact Stibo Systems to purchase a Loqate license through Stibo Systems.

The integration to Loqate services is implemented using the following STEP components:

  • Business actions and bulk updates that enable address standardization and verification of addresses
  • Address Component Model

Additionally, the integration to Loqate Local with CASS uses the following:

  • CASS Address Component Model
  • Event processor for the generation of CASS certification reports

To assist with proper configuration, easy setup actions are available to assist in the Loqate address field mappings as well as the creation of associated address object types, business rules, and event processors. By using Loqate, an address is first standardized and then verified. These are two separate processes that must be executed together to ensure an address is valid. To standardize an address, Loqate updates the address input information from STEP by ensuring that it uses the approved spelling, abbreviations, and formatting of the relevant postal authorities. However, a standardized address alone does not guarantee validity or deliverability. Once the address is standardized, it is matched against Loqate's reference data to be validated. If any city, state, or ZIP code information is missing from the input, Loqate may not be able to uniquely identify and add these to the standardized output. Therefore, the output from Loqate will have quality measures that indicate how valid the address is.

The following screenshot shows a simple example of street address and ZIP code values as they look before being sent to Loqate (Input Street and Input ZIP) and as they look after being standardized and returned from Loqate (Standardized Street and Standardized Zip):

STEP integrates with Loqate in three different ways: Cloud, Local, and Local with CASS. These are similar services but with slight variations. This introductory topic provides a brief overview of these three methods, along with the required configuration properties.

Regardless of your STEP deployment type (SaaS or on-prem), all the above integration options are applicable with Loqate.

Stibo Systems is a reseller of the Loqate solution, commercially licensing the Loqate software along with its reference data. For information on obtaining and deployment of the three variations of the Loqate address standardization service, contact Stibo Systems. Additional support information and deployment instructions can be found on the Loqate website. Users must have a Loqate account already set up to access the additional support section on the Loqate website.

Loqate Cloud

The Loqate Cloud API service is an integration that enables STEP to communicate with an off-premise Loqate cloud server, hosted by Loqate. Input (non-standardized) address information is stored in STEP in attribute values that are mapped to Loqate fields within the Address Component Model. This information is sent from STEP to the Loqate cloud where it is validated and standardized. Once Loqate parses the data, the standardized address information is returned to STEP and stored in standardized output address fields. Loqate charges users a small fee every time a call is made to the Loqate Cloud.

To integrate with the Loqate Cloud solution, STEP users must have a Loqate Cloud API license key.

The Loqate Cloud solution may be a preferred option for users with smaller data sets (less than 1 million records) looking to only pay for their predefined data needs. Also, users must be connected to a local Loqate engine in order to use the CASS program.

To begin integrating your STEP deployment with the Loqate Cloud API, contact Stibo Systems.

Important: The response times for the Loqate Cloud service vary. Commonly, the expected response time per request for Loqate Cloud is 190 - 250 milliseconds.

Loqate Local

The Loqate Local API service is an integration that enables STEP users to standardize address information against reference data stored on the STEP application server itself. Just like in the cloud service, input address information is stored in attribute values that are mapped to Loqate fields within the Address Component Model. However, instead of being sent to a Loqate-hosted cloud server, the address data is sent from STEP to the embedded Loqate engine, where it is validated and standardized. Once the Loqate engine parses the data, the standardized address information is returned and stored in standardized output address fields.

To integrate with the Loqate Local solution, STEP users must have a Loqate Local API license key.

Other reasons users might prefer the Loqate Local solution include:

  • Commercially more cost-effective for work with large data sets (over 1 million records)

  • Better performance and faster response times

  • Zero additional downtime

  • Option to use CASS address standardization

Loqate Local with CASS

The Loqate Local with CASS service is the same installation as the standard Loqate Local API solution but includes additional data packs of CASS reference data and some CASS-specific library files. An additional license is needed for CASS. For more information on CASS, refer to the CASS Address Component Model topic here.

Note: The CASS solution does not work with the Loqate Cloud API.

Address Validation Web Service

When STEP is deployed with Loqate Local, STEP offers an Address Validation web service. This web service can be used by third-party systems to perform the same address validation and standardization that is done in STEP. This allows for consistent address validation across the enterprise.

The Address Validation web service comes in REST and SOAP variants and supports CASS address certification (as applicable) and geocoding. For complete documentation for web services functionality related to Address Validation, access the Technical Documentation button on the Start Page and refer to the SOAP and REST API sections.

Web service endpoint

The Address Standardization Web Service supports both SOAP and REST API. To download the WSDL and obtain access to the Address Validation Web Service, users must have access to the Stibo SDK and API documentation.

Prior to using the Address Standardization Web Service, Loqate Local must already have been deployed in your target STEP environment.

The following is the endpoint for the REST API:

https://[URL for STEP environment]/restapi/loqate/address/verify

The following is the endpoint for the SOAP API:

https://[URL for STEP environment]/LoqateWS/loqate

For information on gaining access to the SDK and API documentation, refer to the Granting Access to the SDK and API Documentation topic in the System Setup documentation, or contact Stibo Systems for further details.

Address information provided by this web service is subject to the Loqate subscription license provisioning. For more information, contact Stibo Systems.

Examples

The Address Validation Web Service standardizes address information outside of STEP. For information on deciphering Loqate’s Address Verification Code, refer to the Evaluating Loqate Address Verification Codes topic in the Solutions Enablement documentation here.

Request

For the REST request, refer to the code below:

Copy 
{
    "Input": {
        "Address": [
            {
                "Address":"",
                "Address1":"4200 amphitheatre",
                "Address2":"",
                "Address3":"",
                "Address4":"",
                "Locality":"mountain view",
                "Country":"US",
                "AdministrativeArea":"",
                "Thoroughfare":"",
                "DependentThoroughfare":"",
                "ThoroughfareName":"",
                "Premise":"",
                "PostCode":"",
                "SubAdministrativeArea":"",
                "DependentLocality":"",
                "Building":"",
                "SubBuilding":"",
                "Organization":"",
                "PostBox":""
            }
        ]
    },
    "Options": {
        "AddressLineSeparator": "",
        "OutputAddressFormat": "",
        "EnhancedCountryTool": ""
    }
}   

For the SOAP request, refer to the code below:

Copy 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://stibo.com/step/ws/loqate/1.0">
<soapenv:Header/>
<soapenv:Body>
<ns:verify>
<VerifyAddressRequest>
<Authentification>
<userid>user</userid>
<password>secret</password>
</Authentification>
<Input>
<Address>
<Address/>
<Address1>Google</Address1>
<Address2>4200 amphitheatre</Address2>
<Address3/>
<Address4/>
<Locality>mountain view</Locality>
<Country>US</Country>
<CountryISO/>
<AdministrativeArea>CA</AdministrativeArea>
<Thoroughfare/>
<DependentThoroughfare/>
<ThoroughfareName/>
<Premise/>
<PostCode/>
<SubAdministrativeArea/>
<DependentLocality/>
<Building/>
<SubBuilding/>
<Organization/>
<PostBox/>
</Address>
</Input>
<Options>
<AddressLineSeparator>&#xA;</AddressLineSeparator>
<OutputAddressFormat/>
<EnhancedCountryTool/>
</Options>
<Process>
<CertifyProcess/>
<GeocodeProcess></GeocodeProcess>
</Process>
</VerifyAddressRequest>
</ns:verify>
</soapenv:Body>
</soapenv:Envelope>    

Response

For the REST response, refer to the code below:

Copy 
{"Output": {"Address": [{
   "AddressContent":    {
      "Address": "4200 Amphitheatre Pkwy<BR>Mountain View CA 94043-1381",
      "Address1": "4200 Amphitheatre Pkwy",
      "Address2": "Mountain View CA 94043-1381",
      "Address3": "",
      "Address4": "",
      "AdministrativeArea": "CA",
      "AddressFormat": "",
      "Building": "",
      "CountryName": "United States",
      "DeliveryAddress": "4200 Amphitheatre Pkwy",
      "DeliveryAddress1": "4200 Amphitheatre Pkwy",
      "DeliveryAddress2": "",
      "Department": "",
      "DependentLocality": "",
      "DependentThoroughfare": "",
      "DoubleDependentLocality": "",
      "Iso31662": "US",
      "Iso31663": "USA",
      "Iso3166N": "840",
      "Latitude": "",
      "LocalityExtra": "",
      "Longitude": "",
      "Locality": "Mountain View",
      "Organization": "",
      "PostBox": "",
      "PostalCode": "94043-1381",
      "Premise": "4200",
      "PremiseNumber": "4200",
      "SubAdministrativeArea": "Santa Clara",
      "SubBuilding": "",
      "SuperAdministrativeArea": "",
      "Thoroughfare": "Amphitheatre Pkwy",
      "ThoroughfareName": "",
      "ThoroughfareType": ""
   },
   "AddressQuality":    {
      "AddressVerificationCode": "V42-I44-P3-092",
      "AddressQualityIndex": "C",
      "GeoAccuracy": "",
      "GeoDistance": ""
   },
   "AddressVerificationDetails":    {
      "ValidationTime": 1667241105193,
      "ValidationStatus": "psOK",
      "ValidationStatusDetails": "",
      "ValidationHash": "OEsCDGuSCMWvfYvv9LCaRQ=="
   },
   "AddressCertificationDetails": null
}]}}   

For the SOAP response, refer to the code below:

Copy 
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:verifyResponse xmlns:ns2="http://stibo.com/step/ws/loqate/1.0">
<VerifyAddressResponse>
<Output>
<Address>
<AddressContent>
<Address>Google
								4200 Amphitheatre Pkwy
								Mountain View CA 94043-1381</Address>
<Address1>Google</Address1>
<Address2>4200 Amphitheatre Pkwy</Address2>
<Address3>Mountain View CA 94043-1381</Address3>
<Address4/>
<AdministrativeArea>CA</AdministrativeArea>
<AddressFormat/>
<Building/>
<CountryName>United States</CountryName>
<DeliveryAddress>4200 Amphitheatre Pkwy</DeliveryAddress>
<DeliveryAddress1>4200 Amphitheatre Pkwy</DeliveryAddress1>
<Department/>
<DependentLocality/>
<DependentThoroughfare/>
<DoubleDependentLocality/>
<Iso31662>US</Iso31662>
<Iso31663>USA</Iso31663>
<Iso3166N>840</Iso3166N>
<Latitude/>
<Longitude/>
<LocalityExtra/>
<Locality>Mountain View</Locality>
<Organization>Google</Organization>
<PostBox/>
<PostalCode>94043-1381</PostalCode>
<Premise>4200</Premise>
<PremiseNumber>4200</PremiseNumber>
<SubAdministrativeArea>Santa Clara</SubAdministrativeArea>
<SubBuilding/>
<SuperAdministrativeArea/>
<Thoroughfare>Amphitheatre Pkwy</Thoroughfare>
<ThoroughfareName>Amphitheatre</ThoroughfareName>
<ThoroughfareType/>
</AddressContent>
<AddressQuality>
<AddressVerificationCode>V42-I45-P3-094</AddressVerificationCode>
<AddressQualityIndex>C</AddressQualityIndex>
<GeoAccuracy/>
<GeoDistance/>
</AddressQuality>
<AddressVerificationDetails>
<ValidationHash>mPl6Z8j98vYiMxYzb1XC2A==</ValidationHash>
<ValidationTime>1664478336487</ValidationTime>
<ValidationStatus>psOK</ValidationStatus>
</AddressVerificationDetails>
</Address>
</Output>
</VerifyAddressResponse>
</ns2:verifyResponse>
</S:Body>
</S:Envelope>    

To access the Address Validation Web Service endpoint for a given system, navigate to the following URL: [your system URL: port]/LoqateWS/loqate.