rest web services guide - pitney...

Spectrum Technology PlatformVersion 9.0

REST Web Services Guide

Contents

Chapter 1: Getting Started..................................................................................5The REST Interface...............................................................................................6Exposing a Service as a Web Service.................................................................7Sample Web Application.......................................................................................8

Chapter 2: Web Services....................................................................................9Address Now Module..........................................................................................10

BuildGlobalAddress....................................................................................10GetGlobalCandidateAddresses..................................................................21ValidateGlobalAddress...............................................................................28

Enterprise Routing Module................................................................................49GetTravelBoundary.....................................................................................49GetTravelCostMatrix...................................................................................59GetTravelDirections....................................................................................59

Enterprise Tax Module........................................................................................60AssignGeoTAXInfo.....................................................................................60CalculateDistance.......................................................................................86

GeoConfidence Module......................................................................................89GeoConfidenceSurface..............................................................................89

Global Sentry Module.........................................................................................90GlobalSentry...............................................................................................90

Location Intelligence Module.............................................................................97Where to Find Documentation?..................................................................97

Universal Addressing Module............................................................................98AutoCompleteLoqate..................................................................................98GetCandidateAddresses..........................................................................103GetCandidateAddressesLoqate...............................................................112GetCityStateProvince...............................................................................117GetCityStateProvinceLoqate....................................................................120GetPostalCodes.......................................................................................123ValidateAddress........................................................................................126ValidateAddressGlobal.............................................................................180ValidateAddressLoqate.............................................................................198

Universal Name Module....................................................................................217OpenNameParser.....................................................................................217

Appendix..........................................................................................................225

Appendix A: The ACR Code.................................................................227The ACR Code.........................................................................................228

Appendix B: Buffering..........................................................................231Buffering...................................................................................................232

Appendix C: Country Codes.................................................................233Country ISO Codes and Module Support.................................................234

Appendix D: ValidateAddress Confidence Algorithm........................251Introduction to the Validate Address Confidence Algorithm.....................252Confidence Algorithm for U.S. and Canadian Addresses........................252Confidence Algorithm for International Addresses...................................253

Spectrum Technology Platform 9.04

1Getting Started

In this section:

• The REST Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6• Exposing a Service as a Web Service . . . . . . . . . . . . . . . . .7• Sample Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . .8

The REST InterfaceThe REST interface can return results in XML and JSON format. To view the RESTweb services availableon your Spectrum™ Technology Platform server, go to:

http://server:port/rest

By default Spectrum™ Technology Platform uses port 8080 for HTTP communication. Youradministrator may have configured a different port.

Note:

REST services are bound to one of the following:

http://server:port/rest/service_name/results.xml

http://server:port/rest/service_name/results.json

Note the following limitations on REST web services:

• Only the GET method is supported. As a result, you can include only one record at a time in a request.In addition, hierarchical data is not supported.

• We recommend that you limit parameters to 2,048 characters due to URL length limits.

WADL URL

The WADL for Spectrum™ Technology Platform web services is in the form:

http://server:port/rest/service_name?_wadl

For example:

http://myserver:8080/rest/ValidateAddress?_wadl

User Fields

You can pass extra fields through the web service even if the web service does not use them. Thesefields are returned, unmodified, in the user_fields section of the response. For example, if you wantedto pass a field called "customID", the following text would be added to the request URL:

Data.customID=xxx

User field names may not contain characters that are invalid in XML or JSON element names.For example, spaces are not valid.

Note:

Sample REST Request with XML Response

The following REST request calls the ValidateAddress service.

http://localhost:8080/rest/ValidateAddress/results.xml?Option.Database.US=USA&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

The sample request would result in this response since an XML response was requested:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xml.ValidateAddressResponsexmlns="http://www.pb.com/spectrum/services/ValidateAddress">

<output_port><Address>

<Confidence>82</Confidence><RecordType>Normal</RecordType><CountryLevel>A</CountryLevel><ProcessedBy>USA</ProcessedBy><MatchScore>0</MatchScore><AddressLine1>1825 Kramer Ln</AddressLine1>


The REST Interface

<City>Austin</City><StateProvince>TX</StateProvince><PostalCode>78758-4260</PostalCode><PostalCode.Base>78758</PostalCode.Base><PostalCode.AddOn>4260</PostalCode.AddOn><Country>United States Of America</Country><user_fields/>

</Address></output_port>

</xml.ValidateAddressResponse>

Sample REST Request with JSON Response

Below is a sample JSON request.

http://localhost:8080/rest/ValidateAddress/results.json?Option.Database.US=USA&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759

The sample request wold result in this response since a JSON response was requested:

{"ns1.json.ValidateAddressResponse" :{"ns1.output_port" :{"ns1.Confidence" : 82,"ns1.RecordType" : "Normal","ns1.CountryLevel" : "A","ns1.ProcessedBy" : "USA","ns1.MatchScore" : 0,"ns1.AddressLine1" : "1825 Kramer Ln","ns1.City" : "Austin","ns1.StateProvince" : "TX","ns1.PostalCode" : "78758-4260","ns1.PostalCode.Base" : 78758,"ns1.PostalCode.AddOn" : 4260,"ns1.Country" : "United States Of America"}}}

Exposing a Service as a Web ServiceSpectrum™ Technology Platform services can be made available as REST and/or SOAP web services.To make a service available on your server as a web service:

1. Open Enterprise Designer.2. Open the service that you want to expose as a web service.3. Go to Edit > Web Service Options.4. Select one of the following options:

Expose the service via enhanced SOAP, which provides more options,including faults, basic authentication, and more.

SOAP

Expose the service via REST.REST

5. Click OK.

To verify that the service is now exposed as a web service, go to one of the following URLs:

• For REST: http://server:port/rest• For SOAP: http://server:port/soap

7REST Web Services Guide

Chapter 1: Getting Started

Where server is the name or IP address of your Spectrum™ Technology Platform server and port is theport used for HTTP communication.

Sample Web ApplicationThe following sample class for .NET is written in C# on Visual Studio 2010. Proxy class implementationsfor the web service data types ValidateAddressClient, requestRow, context , options and responseRowwere generated using Visual Studio .NET's "Add Web Reference" command. This example uses theValidateAddress web service. It is important to note that in this example, the appropriate credentialsmust be provided or the call will fail.

namespace Test{

class Program{

static void Main(string[] args){

var validateClient = new ValidateAddress {Credentials = newNetworkCredential("admin", "admin")};

var address1 = new input_portAddress{

AddressLine1 = "1825B Kramer Lane",AddressLine2 = "Suite 100",PostalCode = "78758",City = "Austin",StateProvince = "Texas"

};

var address2 = new input_portAddress{

AddressLine1 = "100 Congress",PostalCode = "78701",City = "Austin",StateProvince = "Texas"

};

var addresses = new input_portAddress[2];addresses[0] = address1;addresses[1] = address2;

var options = new options {OutputCasing = OutputCasing.M};output_portAddress[] results =

validateClient.CallValidateAddress(options, addresses);

for (int i = 0; i < results.Length; i++){

System.Console.WriteLine("Record " + (i+1) + ":");System.Console.WriteLine("AddressLine1=" +

results[i].AddressLine1);System.Console.WriteLine("City=" + results[i].City);System.Console.WriteLine("StateProvince=" +

results[i].StateProvince);System.Console.WriteLine("PostalCode=" +

results[i].PostalCode + "\n");}

System.Console.Write("Press any key to continue...");System.Console.ReadKey();

}}

}


Sample Web Application

2Web Services

In this section:

• Address Now Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10• Enterprise Routing Module . . . . . . . . . . . . . . . . . . . . . . . .49• Enterprise Tax Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .60• GeoConfidence Module . . . . . . . . . . . . . . . . . . . . . . . . . . .89• Global Sentry Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90• Location Intelligence Module . . . . . . . . . . . . . . . . . . . . . . .97• Universal Addressing Module . . . . . . . . . . . . . . . . . . . . . .98• Universal Name Module . . . . . . . . . . . . . . . . . . . . . . . . . .217

Address Now Module

BuildGlobalAddressBuildGlobalAddress allows you to build a valid address starting with just a single address element or afew address elements. BuildGlobalAddress is part of the Address Now Module.

Resource URL

JSON endpoint:

http://server:port/rest/BuildGlobalAddress/results.json

XML endpoint:

http://server:port/rest/BuildGlobalAddress/results.xml

Example with JSON Response

The following example requests a JSON response:

http://myserver:8080/rest/BuildGlobalAddress/results.json?Data.Action=init&Data.Country=USA

The JSON returned by this request would be:

{"output_port": [{"Action": "init","Country": "USA","SessionId": "n5hiliawx0","SearchFieldIndex": "-1","Field.0.Name": "Zip","Field.0.Index": "0","Field.0.Value": "","Field.0.CommitFlag": "N","Field.1.Name": "City","Field.1.Index": "1","Field.1.Value": "","Field.1.CommitFlag": "N","Field.2.Name": "State","Field.2.Index": "2","Field.2.Value": "","Field.2.CommitFlag": "N","Field.3.Name": "County","Field.3.Index": "3","Field.3.Value": "","Field.3.CommitFlag": "N","Field.4.Name": "Street","Field.4.Index": "4","Field.4.Value": "","Field.4.CommitFlag": "N","Field.5.Name": "Company","Field.5.Index": "5","Field.5.Value": "","Field.5.CommitFlag": "N","Field.6.Name": "Building","Field.6.Index": "6","Field.6.Value": "","Field.6.CommitFlag": "N","Field.7.Name": "Premise-No","Field.7.Index": "7",


Address Now Module

"Field.7.Value": "","Field.7.CommitFlag": "N","Field.8.Name": "Sub-Building","Field.8.Index": "8","Field.8.Value": "","Field.8.CommitFlag": "N","Field.9.Name": "PO-Box","Field.9.Index": "9","Field.9.Value": "","Field.9.CommitFlag": "N","Field.10.Name": "+4","Field.10.Index": "10","Field.10.Value": "","Field.10.CommitFlag": "N","Alternatives.InContext": "","Alternatives.InContext.Count": "0","Alternatives.OutContext": "","Alternatives.OutContext.Count": "0","user_fields": []

}]}

Example with XML Response

The following example requests an XML response. This request performs the initialization (init) actionto obtain a session ID from BuildGlobalAddress.

http://myserver:8080/rest/BuildGlobalAddress/results.xml?Data.Action=init&Data.Country=USA

The XML returned by this request would be:

<ns2:xml.BuildGlobalAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/BuildGlobalAddress">

<ns2:output_port><ns2:Result>

<ns2:Action>init</ns2:Action><ns2:Country>USA</ns2:Country><ns2:SessionId>qbximydxf0</ns2:SessionId><ns2:Field.0.Name>Zip</ns2:Field.0.Name><ns2:Field.0.Index>0</ns2:Field.0.Index><ns2:Field.0.Value/><ns2:Field.0.CommitFlag>N</ns2:Field.0.CommitFlag><ns2:Field.1.Name>City</ns2:Field.1.Name><ns2:Field.1.Index>1</ns2:Field.1.Index><ns2:Field.1.Value/><ns2:Field.1.CommitFlag>N</ns2:Field.1.CommitFlag><ns2:Field.2.Name>State</ns2:Field.2.Name><ns2:Field.2.Index>2</ns2:Field.2.Index><ns2:Field.2.Value/><ns2:Field.2.CommitFlag>N</ns2:Field.2.CommitFlag><ns2:Field.3.Name>County</ns2:Field.3.Name><ns2:Field.3.Index>3</ns2:Field.3.Index><ns2:Field.3.Value/><ns2:Field.3.CommitFlag>N</ns2:Field.3.CommitFlag><ns2:Field.4.Name>Street</ns2:Field.4.Name><ns2:Field.4.Index>4</ns2:Field.4.Index><ns2:Field.4.Value/><ns2:Field.4.CommitFlag>N</ns2:Field.4.CommitFlag><ns2:Field.5.Name>Company</ns2:Field.5.Name><ns2:Field.5.Index>5</ns2:Field.5.Index><ns2:Field.5.Value/><ns2:Field.5.CommitFlag>N</ns2:Field.5.CommitFlag><ns2:Field.6.Name>Building</ns2:Field.6.Name><ns2:Field.6.Index>6</ns2:Field.6.Index><ns2:Field.6.Value/><ns2:Field.6.CommitFlag>N</ns2:Field.6.CommitFlag><ns2:Field.7.Name>Premise-No</ns2:Field.7.Name><ns2:Field.7.Index>7</ns2:Field.7.Index>


Chapter 2: Web Services

<ns2:Field.7.Value/><ns2:Field.7.CommitFlag>N</ns2:Field.7.CommitFlag><ns2:Field.8.Name>Sub-Building</ns2:Field.8.Name><ns2:Field.8.Index>8</ns2:Field.8.Index><ns2:Field.8.Value/><ns2:Field.8.CommitFlag>N</ns2:Field.8.CommitFlag><ns2:Field.9.Name>PO-Box</ns2:Field.9.Name><ns2:Field.9.Index>9</ns2:Field.9.Index><ns2:Field.9.Value/><ns2:Field.9.CommitFlag>N</ns2:Field.9.CommitFlag><ns2:Field.10.Name>+4</ns2:Field.10.Name><ns2:Field.10.Index>10</ns2:Field.10.Index><ns2:Field.10.Value/><ns2:Field.10.CommitFlag>N</ns2:Field.10.CommitFlag><ns2:SearchFieldIndex>-1</ns2:SearchFieldIndex><ns2:Alternatives.InContext/><ns2:Alternatives.InContext.Count>

0</ns2:Alternatives.InContext.Count><ns2:Alternatives.OutContext/><ns2:Alternatives.OutContext.Count>

0</ns2:Alternatives.OutContext.Count><ns2:user_fields/>

</ns2:Result></ns2:output_port>

</ns2:xml.BuildGlobalAddressResponse>

Using BuildGlobalAddressBuilding an address is an interactive process that requires you to select address elements at each stepof the address building process. This means that building an address requires a sequence of calls toBuildGlobalAddress, not a single call. To start, you make an initialization call to BuildGlobalAddress.This call returns a session ID. You then use this session ID in subsequent calls. With each call,BuildGlobalAddress presents a list of alternative values for an address element. You select the valueyou want, then move on to the next address element until the complete address is built. With someexceptions, you need to make a separate call for each address element.

The overall process works like this:

• First, you make an initialization call to open a session and receive a system-assigned session ID.• Make a search call to find possible values for a given address element.• When you have selected the value you want, you make a commit call to indicate the value you wantfor the given address element.

• Continue to make search/commit calls until all address elements are committed.• Finally, you make a close call to end the session.

To familiarize yourself with how the process works, use the Management Console's Preview tab to stepthrough the following procedure.

1. Open the Management Console.2. Under the Services node, select Build Global Address.3. On the Options tab, specify the options you want. For information on the options, see Parameters

for Options on page 16.4. Click the Preview tab.5. In the Action field type init.6. In the Country field enter the country of the address you want to build.7. Click Run Preview.8. Under Preview Output, find the SessionId field, right-click the value, and select Copy from the pop-up

menu.


Address Now Module

9. Under Preview Input, right-click the SessionId field and select Paste.

10. Enter the following values in the input fields:

• Action—Type search.• Country—Keep this field the same.• FieldIndex—Type the index value of the first field you want to search. For example, if you knowyou want to search for an address in Chicago, you would type "1" because for U.S. addresses,field index 1 corresponds to the City field.

• SearchValue—Type the value you want to search for. For example, if you want to build an addressin Chicago, you would type "chicago".

• SessionId—Keep the same value.



The values in the other input fields are ignored.Note:

11. Click Run Preview again.12. The results of the search are placed in up to two output fields: Alternatives.InContext and

AlternativesOutContext. For an explanation of the difference between in context results and out ofcontext results, see What Is Context? on page 21.

13. When you have found the value you want, enter the following values in the input fields:

• Action—Type commit.• AlternativeIndex—Type the index number for the alternative you choose. Index values start with0, not 1. For example, if you search for Chicago the alternatives returned by BuildGlobalAddresswould be indexed as follows. If you want to commit the value "CHICAGO" you would type "0" inthe AlternativeIndex field.

• 0—CHICAGO• 1—CHICAGO HTS• 2—CHICAGO PARK• 3—CHICAGO RIDGE• 4—EAST CHICAGO• 5—NORTH CHICAGO• 6—WEST CHICAGO

• AlternativeContext—Type in or out to indicate whether the index value you specified inAlternativeIndex is for the list of alternatives in the Alternatives.InContext field or theAlternatives.OutContext field.

• SessionId—Keep this value the same.


14. Click Run Preview again. The value you specified will now be in the Field.n.Value field for theappropriate address element.

15. Repeat the search and commit steps as often as needed until you have built the address.16. Close the session by entering the following values in the input fields:

• Action—Type close.• SessionId—Keep this value the same.


Request

Parameters for Input Data

Table 1: BuildGlobalAddress Input

DescriptionFormatParameter

Specifies the action to take. One of the following:StringData.Action

Initialization. This action opens a session andreturns a session ID which is required for all other

init

actions. The init action requires the Country inputfield.

Searches for values for a specific addresselement and returns a list of alternative values for

search

you to choose. The search action requires thefollowing input fields:


Address Now Module


• FieldIndex• SearchValue• SessionId

Assigns one of the values returned by the searchaction to the field. The commit action requires thefollowing input fields:

commit

• AlternativeIndex• AlternativeContext• SessionId

Un-commits the field specified in the FieldIndexfield. The clear action requires the following inputfields:

clear

• FieldIndex• SessionID

Ends a session. The close action requires theSessionId input field.

close

For the commit action, indicates whether you are choosing avalue from the Alternatives.InContext field or the

StringData.AlternativeContext

Alternatives.OutContext field. This field is ignored for otheractions. One of the following:

You are committing a value from theAlternatives.InContext field. This means that the

in

value you specify in the AlternativeIndex input fieldcorresponds to a value in theAlternatives.InContextoutput field.

You are committing a value from theAlternatives.OutContext field. This means that the

out

value you specify in the AlternativeIndex input fieldcorresponds to a value in theAlternatives.OutContext output field.

For the commit action, specifies the value you want to use inthe address you are building. For example, if you searched

String[79]

Data.AlternativeIndex

for a city and BuildGlobalAddress returns a list of three cities,you would indicate the city you want by specifying the indexvalue for your choice. Index values for the alternativespresented by BuildGlobalAddress are zero-based, meaningthat the first alternative has an index of 0, the secondalternative has a value of 1, and so on.

The input field is ignored for actions other than commit.

For the init action, specifies the country in which you want tobuild an address. Specify the country using the format you

String[79]

Data.Country

chose for input country format (English name two-characterISO 3116-1 Alpha-2 code, or three-character ISO 3116-1Alpha-3 code). For a list of ISO codes, see Country ISOCodes and Module Support on page 234.




This input field is ignored for actions other than init.

For the search action, specifies the address element that youwant to search on. For the clear action, specifies the addresselement you want to un-commit. One of the following:

String[79]

Data.FieldIndex

performs the "clear" action on all addresselements. This option applies to the "clear"action only.

all

Performs the action on a specific addresselement. To determine the index of an

<IndexNumber>

address element, first look at theField.n.Name fields and locate the fieldyou want. The value n indicates the field'sindex. For example, you want to look upZIP Codes for U.S. addresses. After theinit call you see that Field.0.Name is "Zip"indicating that the ZIP Code has a fieldindex of "0".

This input field is ignored for actions other than search andclear.

For the search action, specifies the value you want to searchfor. This value must be appropriate for the field you specified

String[79]

Data.SearchValue

in FieldIndex. For example, if you specified the ZIP Code fieldin FieldIndex, then you would enter a ZIP Code or partial ZIPCode in this field. Likewise if you chose the city field inFieldIndex you would specify a city name or partial city namein this field. if you leave the field blank the search will returnall values that are in context. For more information about incontext and out of context values, see What Is Context? onpage 21.

This input field is ignored for actions other than search.

Specifies the session ID you want to use for this call. To obtaina session ID use the init action. If a session is inactive for 5

String[79]

Data.SessionId

minutes it will expire and you will need to perform a new initcall to start a new session.

This field is required for all actions except init.

Parameters for Options

Table 2: BuildGlobalAddress Options

DescriptionParameter

Specifies the default country. You should specify the country wheremost of the addresses in your data are located. For example, if most of

Option.HomeCountry

your addresses are in Canada, specify Canada. BuildGlobalAddressuses the country you specify to attempt validation when it cannotdetermine the country from the StateProvince, PostalCode, and Countryaddress fields.


Address Now Module


Specifies the format to use for the country name in the output. One ofthe following:

Option.OutputCountryFormat

The country in the output in English (default).E

The country in the output as the two-character ISO code.I

The country in the output as the three-character UPU code.U

Specifies whether or not to use separators (spaces or hyphens) in ZIPCodes or Canadian postal codes.

Option.OutputPostalCodeSeparator

For example, a ZIP + 4® Code with the separator would be 20706-1844and without the separator it would be 207061844. A Canadian postalcode with the separator would be P5E"1S7 and without the separatorit would be P5E1S7.

Yes, use separator (default).Y

No, do not use separator.N

Spaces are used in Canadian postal codes and hyphens inU.S. ZIP + 4® Codes.

Note:

Specifies whether or not to include the city, state/province, and postalcode in one of the AddressLine output fields. Regardless of what you

Option.ShowExtraAddressLine

specify with this option, the output fields City, State/Province, andPostalCode will always contain the city, state/province, and postal code.

Yes, include city, state/province, and postal code in anAddressLine output field (default).

Y

No, do not include city, state/province, and postal code in anAddressLine output field.

N

Allows you to set the default value for this option to any value from 1 to10000; it has a default value of 50 records. Note that values set inEnterprise Designer override those set in Management Console

Option.MaximumResults

Response

Address Data

Table 3: BuildGlobalAddress Output

DescriptionFormatResponse Element

Shows the value specified in the Action input fieldfor this call. For more information on this input fieldsee Parameters for Input Data on page 14.

String [79]Action

The formatted first address line.String [79]AddressLine1

The formatted second address line.String [79]AddressLine2

The formatted third address line.String [79]AddressLine3

The formatted fourth address line.String [79]AddressLine4

The formatted fifth address line.String [79]AddressLine5

The formatted sixth address line.String [79]AddressLine6




The formatted seventh address line.String [79]AddressLine7

The formatted eighth address line.String [79]AddressLine8

Shows the value specified in the AlternativeContextinput field for this call. For more information, seeParameters for Input Data on page 14.

String [79]AlternativeContext

Shows the value specified in the AlternativeIndexinput field for this call. For more information on this

String [79]AlternativeIndex

input field see Parameters for Input Data on page14.

A comma-delimited list of the possible values forthe field you searched on which fit the context of

String [79]Alternatives.InContext

fields you have already committed. For informationon context see What Is Context? on page 21.

The number of "in context" results returned by yoursearch. For information on context see What IsContext? on page 21.

String [79]Alternatives.InContext.Count

A comma-delimited list of the possible values forthe field you searched on which do not fit the

String [79]Alternatives.OutContext

context of fields you have already committed. Forinformation on context see What Is Context? onpage 21.

The number of "out of context" results returned byyour search. For information about context, seeWhat Is Context? on page 21.

String [79]Alternatives.OutContext.Count

Apartment designator (such as STE or APT). Forexample:

String [79]ApartmentLabel

123 E Main St. APT 3

Apartment number. For example:String [79]ApartmentNumber


The name of a building.String [79]Building

The city name.String [79]City

Shows the value specified in the Country input fieldfor this call. For more information about this inputfield, see Parameters for Input Data on page 14.

String [79]Country

The two- or three-character ISO code, or Englishname of the country. For a list of ISO codes, see

String [79]Country

Country ISO Codes and Module Support on page234.

The name of a distinct part of anything arrangedinto divisions. For example, the FinanceDepartment in a corporation.

String [79]Department

Indicates whether you have chosen a value for fieldn (i.e. "committed" a value). One of the following:

String [79]Field.n.CommitFlag

Yes, the value of this field has beencommitted.

Y


Address Now Module


No, the value of this field has not beencommitted.

N

An index value used to refer to field n, where n is0 though 10. For example, for U.S. addresses theindex value of the ZIP field is "0".

String [79]Field.n.Index

The name of the address element contained in fieldn, where n is 0 through 10. For example, for U.S.addresses Field.0.Name is ZIP.

String [79]Field.n.Name

The value that has been committed to field n, wheren is 0 through 10.

String [79]Field.n.Value

This field is blank on the init call.

Shows the value specified in the FieldIndex inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.

String [79]FieldIndex

The name of a company. For example:String [79]FirmName

Pitney Bowes Software4200 PARLIAMENT PL STE 600LANHAM MD 20706-1844USA

House number. For example:String [79]HouseNumber

123 E Main St. Apt 3

The post office box number. If the address is a ruralroute address, the rural route box number willappear here.

String [79]POBox

The postal code. In the U.S. this is the ZIP Code™.String [79]PostalCode

The 4-digit add-on part of the ZIP + 4® Code. Forexample, in the ZIP Code™ 60655-1844, 1844 isthe 4-digit add-on. (U.S. addresses only.)

String [79]PostalCode.AddOn

The 5-digit ZIP Code™. For example 20706 (U.S.addresses only.)

String [79]PostalCode.Base

An area within a country. For example, England,Scotland, and Wales are principalities. This fieldwill normally be blank.

String [79]Principality

The index value of the field searched in theprevious search action.

String [79]SearchFieldIndex

Shows the value specified in the SearchValue inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.

String [79]SearchValue

Shows the value specified in the SessionId inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.

String [79]SessionId

The state or province abbreviation.String [79]StateProvince

Street name. For example:String [79]StreetName





Street suffix. For example:String [79]StreetSuffix


A district or suburb. The subcity is used in countrieswhere it is common to include the district or suburbwithin the address. For example,

String [79]SubCity

27 Crystal WayBradley StokeBristol BS32 8GA

In this case, "Bradley Stoke" is the subcity.

The second street address used to identify anaddress. Substreets are used in countries where

String [79]SubStreet

it is common to give two street names in theaddress. For example,

12 The MewsHigh Street

In this example, "High Street" is the substreet.Substreets can be used to precisely identify thedelivery location. In the example, "The Mews" maybe a small street that needs another streetidentification to properly locate the address, so"High Street" is included. In this case, "High Street"is the main or known street.

For U.S. addresses, the name of the county wherethe address is located.

String [79]USCountyName

Return Codes

Table 4: BuildGlobalAddress Return Codes


Reports the success or failure of the match attempt.String [79]Status

Successnull

FailureF

Reason for failure, if there is one.String [79]Status.Code

• SessionError• SeverError• CountryNotFound

Description of the problem, if there is one.String [79]Status.Description

This value will appear ifStatus.Code=SessionError.

Please initializenew session


Null or emptyaction


Unknownaction


Address Now Module



Invalid session


Invalid value for


Cannot SearchCommittedField

This value will appear ifStatus.Code=ServerError.

Module notlicensed

This value will appear ifStatus.Code=CountryNotFound

Could NotIdentify Country

What Is Context?When you perform a search for an address element, BuildGlobalAddress looks at the address elementsthat you have already committed and splits up the values it returns based on whether or not the returnedvalues exist within the context of the address elements you have already committed. For example, inthe U.S. the following cities exist:

In Illinois:

• CHICAGO• CHICAGO HTS• CHICAGO RIDGE• NORTH CHICAGO• WEST CHICAGO

In Indiana:

• EAST CHICAGO

In Nevada:

• CHICAGO PARK

If you have already committed a value of "IN" (Indiana) for the state and then searched for the city"chicago", BuildGlobalAddress would return EAST CHICAGO as an "in context" result because it existsin Indiana, and it would return all the other matches for "chicago" as out-of-context results. Likewise, ifyou committed a value of "IL" (Illinois) for the state, BuildGlobalAddress would return EAST CHICAGOand CHICAGO PARK as out of context, and CHICAGO, CHICAGO HTS, CHICAGO RIDGE, NORTHCHICAGO, and WEST CHICAGO as "in context."

GetGlobalCandidateAddressesGetGlobalCandidateAddresses returns a list of addresses that are considered matches for a given inputaddress. If the input address matches multiple addresses in the Address Now database, the possiblematches are returned. If the input address matches only one address in the Address Now database, noaddress data is returned.

GetGlobalCandidateAddresses is part of the Address Now Module.



Resource URL

JSON endpoint:

http://server:port/rest/GetGlobalCandidateAddresses/results.json

XML endpoint:

http://server:port/rest/GetGlobalCandidateAddresses/results.xml



http://myserver:8080/rest/GetGlobalCandidateAddresses/results.json?Data.AddressLine1=1070+Maple&Data.City=Batavia&Data.StateProvince=NY


Empty response elements have been removed from this example. Only the first two candidateaddress are shown.

Note:

{"output_port": [{"Confidence": "80","AddressLine1": "1 Maple St","AddressLine2": "Batavia NY 14020-3116","HouseNumber": "1","StreetName": "Maple","StreetSuffix": "St","City": "Batavia","USCountyName": "Genesee","StateProvince": "NY","PostalCode": "14020-3116","Country": "United States","ACRCode": "L5-P5S5A0T4R4Z6C4-080","PostalCode.Base": "14020","PostalCode.AddOn": "3116","user_fields": []

},{"Confidence": "80","AddressLine1": "3 Maple St","AddressLine2": "Batavia NY 14020-3116","HouseNumber": "3","StreetName": "Maple","StreetSuffix": "St","City": "Batavia","USCountyName": "Genesee","StateProvince": "NY","PostalCode": "14020-3116","Country": "United States","ACRCode": "L5-P5S5A0T4R4Z6C4-080","PostalCode.Base": "14020","PostalCode.AddOn": "3116","user_fields": []

}]}


The following example requests an XML response:

http://myserver:8080/rest/GetGlobalCandidateAddresses/results.xml?Data.AddressLine1=1070+Maple&Data.City=Batavia&Data.StateProvince=NY


Address Now Module



Note:

<ns2:xml.GetGlobalCandidateAddressesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetGlobalCandidateAddresses">

<ns2:output_port><ns2:Address>

<ns2:Confidence>80</ns2:Confidence><ns2:AddressLine1>1 Maple St</ns2:AddressLine1><ns2:AddressLine2>Batavia NY 14020-3116</ns2:AddressLine2><ns2:HouseNumber>1</ns2:HouseNumber><ns2:StreetName>Maple</ns2:StreetName><ns2:StreetSuffix>St</ns2:StreetSuffix><ns2:City>Batavia</ns2:City><ns2:USCountyName>Genesee</ns2:USCountyName><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>14020-3116</ns2:PostalCode><ns2:PostalCode.Base>14020</ns2:PostalCode.Base><ns2:PostalCode.AddOn>3116</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:ACRCode>L5-P5S5A0T4R4Z6C4-080</ns2:ACRCode>

</ns2:Address><ns2:Address>

<ns2:Confidence>80</ns2:Confidence><ns2:AddressLine1>3 Maple St</ns2:AddressLine1><ns2:AddressLine2>Batavia NY 14020-3116</ns2:AddressLine2><ns2:HouseNumber>3</ns2:HouseNumber><ns2:StreetName>Maple</ns2:StreetName><ns2:StreetSuffix>St</ns2:StreetSuffix><ns2:City>Batavia</ns2:City><ns2:USCountyName>Genesee</ns2:USCountyName><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>14020-3116</ns2:PostalCode><ns2:PostalCode.Base>14020</ns2:PostalCode.Base><ns2:PostalCode.AddOn>3116</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:ACRCode>L5-P5S5A0T4R4Z6C4-080</ns2:ACRCode>

</ns2:Address></ns2:output_port>

</ns2:xml.GetGlobalCandidateAddressesResponse>

Request

Parameters for Input DataGetGlobalCandidateAddresses takes a standard address as input. All addresses use this format nomatter what country the address is from. AddressLine1 and Country are required input fields. The otherfields are optional.

Table 5: GetGlobalCandidateAddresses Input


First address line. This is a required field.String[79]

Data.AddressLine1

Second address lineString[79]

Data.AddressLine2

Third address lineString[79]

Data.AddressLine3




Fourth address lineString[79]

Data.AddressLine4

Fifth address lineString[79]

Data.AddressLine5

Sixth address lineString[79]

Data.AddressLine6

Seventh address lineString[79]

Data.AddressLine7

Eighth address lineString[79]

Data.AddressLine8

City nameString[79]

Data.City

State or province.String[79]

Data.StateProvince

The postal code for the address in one of these formats:String[10]

Data.PostalCode

9999999999-9999A9A9A9A9A 9A99999 999

The country. Specify the country using the format you chose for inputcountry format (English name or ISO code). For a list of ISO codes, seeCountry ISO Codes and Module Support on page 234.

StringData.County

Company or firm nameString[79]

Data.FirmName


Table 6: GetGlobalCandidateAddresses Options


Specifies the default country. Specify the country that is the destinationof most of your mailpieces. For example, if most of your mailpieces are

Option.HomeCountry

going to Canada, specify Canada. GetGlobalCandidateAddresses usesthe country you specify to attempt validation when it cannot determinethe country from the StateProvince, PostalCode, and Country addressfields.



The country in the output in English (default).E

The country in the output in the two-character ISO code.I

The country in the output in the three-character UPU code.U


Address Now Module


Specifies the casing of the output data. One of the following:Option.OutputCasing

The output in mixed case (default). For example: 123 MainSt Mytown FL 12345

M

The output in upper case. For example: 123 MAIN STMYTOWN FL 12345

U

Specifies whether or not to use separators (spaces or hyphens) in ZIP™

Codes or Canadian postal codes.Option.OutputPostalCodeSeparator


Yes, use separator (default)Y

No, do not use separatorN


Note:

Specifies whether or not to include the city, state/province, and postalcode in one of the AddressLine output fields. Regardless of what you


specify with this option, the output fields City, State/Province, andPostalCode will always contain the city, state/province, and postal code.


Y


N

The maximum number of candidate addresses to output. The default is50. The maximum value is 100.


Specifies whether or not to include in the output data from the inputaddress that could not be validated.

Option.ReturnUserData

Yes, include input data that could not be validated.Y

No, do not include input data that could not be validated(default).

N

Response

Address Data

Table 7: GetGlobalCandidateAddresses Address Data Output

DescriptionFormatResponseElement

The formatted first address line.String[79]

AddressLine1

The formatted second address line.String[79]

AddressLine2

The formatted third address line.String[79]

AddressLine3




The formatted fourth address line.String[79]

AddressLine4

The formatted fifth address line.String[79]

AddressLine5

The formatted sixth address line.String[79]

AddressLine6

The formatted seventh address line.String[79]

AddressLine7

The formatted eighth address line.String[79]

AddressLine8

Apartment designator (such as STE or APT). For example:String[79]

ApartmentLabel


Apartment number. For example:String[79]

ApartmentNumber


The name of a building.String[79]

Building

The city name.String[79]

City

The ISO code or English name of the country. For a list of ISO codes,see Country ISO Codes and Module Support on page 234.

String[79]

Country

The name of a distinct part of anything arranged into divisions. Forexample, the Finance Department in a corporation.

String[79]

Department

The name of a company. For example:String[79]

FirmName

Pitney Bowes Software4200 PARLIAMENT PLSTE 600LANHAM MD 20706-1844USA

House number. For example:String[79]

HouseNumber


Post office box number. If the address is a rural route address, the ruralroute box number will appear here.

String[79]

POBox

The postal code as required by the local postal authority. For example,in the U.S. the postal code is the ZIP Code.

String[79]

PostalCode

For U.S. addresses, the last four digits of the ZIP + 4® Code.String[79]

PostalCode.AddOn

For U.S. addresses, the five-digit ZIP Code.String[79]

PostalCode.Base

An area within a country. For example, England, Scotland, and Walesare principalities. This field will normally be blank.

String[79]

Principality

The state or province abbreviation.String[79]

StateProvince


Address Now Module


Street name. For example:String[79]

StreetName


Street suffix. For example:String[79]

StreetSuffix


A district or suburb. The subcity is used in countries where it is commonto include the district or suburb within the address. For example,

String[79]

SubCity



The second street address used to identify an address. Substreets areused in countries where it is common to give two street names in theaddress. For example,

String[79]

SubStreet


In this example, "High Street" is the substreet. Substreets can be usedto precisely identify the delivery location. In the example, "The Mews"may be a small street that needs another street identification to properlylocate the address, so "High Street" is included. In this case, "HighStreet" is the main or known street.

For U.S. addresses, the name of the county where the address islocated.

String[79]

USCountyName

Return Codes

Table 8: GetGlobalCandidateAddresses Return Codes


The Address Correction Result (ACR) code describes whatdata has been changed in each record. For information onwhat this code means, see The ACR Code on page 228.

String [79]ACRCode

The level of confidence assigned to the address beingreturned. Range is from zero (0) to 100; zero indicates failure,

String [79]Confidence

100 indicates a very high level of confidence that the matchresults are correct.

Reports the success or failure of the match attempt.String [79]Status

SuccessNull

FailureF

Reason for failure, if there is one.String [79]Status.Code

• RequestFailed• ServerError• CountryNotFound




Description of the problem, if there is one.String [79]Status.Description

This value will appear ifStatus.Code=RequestFailed.

Maximum recordscannot be set to 0.Minimum value shouldbe 1

This value will appear ifStatus.Code=RequestFailed.

Address Not Found

This value will appear ifStatus.Code=ServerError.

Module not licensed

This value will appear ifStatus.Code=CountryNotFound.

Could Not IdentifyCountry

ValidateGlobalAddressValidateGlobalAddress provides enhanced address standardization and validation for addresses outsidethe U.S. and Canada. ValidateGlobalAddress can also validate addresses in the U.S. and Canada butits strength is validation of addresses in other countries. If you need to validate addresses outside theU.S. and Canada, you should consider using ValidateGlobalAddress.

ValidateGlobalAddress is part of the Address Now Module.

Resource URL

JSON endpoint:

http://server:port/rest/ValidateGlobalAddress/results.json

XML endpoint:

http://server:port/rest/ValidateGlobalAddress/results.xml

Resource URL

JSON endpoint:

http://server:port/rest/ValidateAddressGlobal/results.json

XML endpoint:

http://server:port/rest/ValidateAddressGlobal/results.xml



http://myserver:8080/rest/ValidateGlobalAddress/results.json?Data.AddressLine1=1825+Kramer+Ln&Data.City=Austin&Data.StateProvince=TX


{"output_port": [{"Confidence": "100","AddressLine1": "1825 Kramer Ln","AddressLine2": "Austin TX 78758",


Address Now Module

"AddressLine3": "","AddressLine4": "","AddressLine5": "","AddressLine6": "","AddressLine7": "","AddressLine8": "","Department": "","Building": "","SubStreet": "","SubCity": "","Principality": "","City": "Austin","StateProvince": "TX","PostalCode": "78758","Country": "United States","FirmName": "","HouseNumber": "1825","StreetName": "Kramer","StreetSuffix": "Ln","ApartmentLabel": "","POBox": "","USCountyName": "Travis","WCRCode": "","URL1": "","URL2": "","Email1": "","Email2": "","ACRCode": "L5-P4S4A0T4R4Z6C4-100","OuterMatchScore": "40","Latitude": "","Longitude": "","ECRCode": "CoBoPeSeXoCeRoPo","PostalCode.Base": "78758","PostalCode.AddOn": "","user_fields": []

}]}



http://myserver:8080/rest/ValidateGlobalAddress/results.xml?Data.AddressLine1=1825+Kramer+Ln&Data.City=Austin&Data.StateProvince=TX


Empty response elements have been removed from this example.Note:

<ns2:xml.ValidateGlobalAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateGlobalAddress">


<ns2:Confidence>100</ns2:Confidence><ns2:AddressLine1>1825 Kramer Ln</ns2:AddressLine1><ns2:AddressLine2>Austin TX 78758</ns2:AddressLine2><ns2:City>Austin</ns2:City><ns2:StateProvince>TX</ns2:StateProvince><ns2:PostalCode>78758</ns2:PostalCode><ns2:PostalCode.Base>78758</ns2:PostalCode.Base><ns2:PostalCode.AddOn/><ns2:Country>United States</ns2:Country><ns2:HouseNumber>1825</ns2:HouseNumber><ns2:StreetName>Kramer</ns2:StreetName><ns2:StreetSuffix>Ln</ns2:StreetSuffix><ns2:USCountyName>Travis</ns2:USCountyName><ns2:ACRCode>L5-P4S4A0T4R4Z6C4-100</ns2:ACRCode><ns2:OuterMatchScore>40</ns2:OuterMatchScore><ns2:ECRCode>CoBoPeSeXoCeRoPo</ns2:ECRCode>




</ns2:xml.ValidateGlobalAddressResponse>

Request

Parameters for Input DataValidateGlobalAddress takes a standard address as input. All addresses use this format no matter whatcountry the address is from.

Table 9: ValidateGlobalAddress Input


First address lineString[79]

Data.AddressLine1


Data.AddressLine2


Data.AddressLine3


Data.AddressLine4


Data.AddressLine5


Data.AddressLine5

Seventh address lineString[79]

Data.AddressLine7

Eighth address lineString[79]

Data.AddressLine7

City nameString[79]

Data.City


Data.StateProvince

The postal code for the address. In the U.S. this is the ZIPCode™.

String[79]:

9999999999-9999

Data.PostalCode

A9A9A9A9A 9A99999999

Specify the country using the format you chose for inputcountry format (English name or ISO code). For a list of ISO

String[79]

Data.Country

codes, see Country ISO Codes and Module Support onpage 234.


Address Now Module



Data.FirmName

Parameters for OptionsInput Data Options

Table 10: ValidateGlobalAddress Input Data Options


Specifies the default country. You should specify the country wheremost of the addresses are located. For example, if most of the addresses

Option.HomeCountry

you process are in Canada, specify Canada. ValidateGlobalAddressuses the home country to attempt validation when it cannot determinethe country from the StateProvince, PostalCode, and Country addressfields. For a list of valid values, see Country ISO Codes and ModuleSupport on page 234.

Output Data Options

Table 11: ValidateGlobalAddress Output Data Options




The country in the output is English (default).E

The country in the output in the two-character ISO code.I

The country in the output in the three-character UPU code.U


The output in mixed case (default). For example: 123 MainSt Mytown FL 12345

M

The output in upper case. For example: 123 MAIN STMYTOWN FL 12345

U

Specifies whether to use a separator (spaces or hyphens) in ZIP™ Codesor Canadian postal codes.



Yes, use separator (default)Y

No, do not use separatorN


Note:

Specifies whether to include the city, state/province, and postal code inone of the AddressLine output fields. Regardless of what you specify





with this option, the output fields City, State/Province, and PostalCodewill always contain the city, state/province, and postal code.


Y


N

Specifies whether to return a standardized address when an addresscannot be validated. The address is formatted using the preferred

Option.StandardizeAddressOnFail

address format for the address's country. If this option is not selected,the output address component fields (StreetName, HouseNumber, etc.)are blank when address validation fails.

No, do not format failed addresses (default).N

Yes, standardize failed addresses.Y

Specifies whether to return a formatted address when an address cannotbe validated. The address is formatted using the preferred addressformat for the address's country.

Option.FormatOnFail

Yes, return a formatted address when an address cannot bevalidated.

Y

No, do not return a formatted address when an addresscannot be validated (default).

N

Enables address validation. Address validation does the following:Option.ValidateAddress

• Matches components to the relevant country's reference data• Corrects spelling errors• Adds missing components• Corrects or adds postal codes

Yes, validate addresses (default).Y

No, do not validate addresses.N

Formats the address components into the statutory postal or customformats.

Option.FormatAddress

Yes, format addresses (default).Y

No, do not format addresses.N

Standardization Options

Table 12: ValidateGlobalAddress Standardization Options


Specifies whether or not to populate the Department field whenstandardizing an address.

Option.StandardizeComponent.Department

Yes (default)Y

NoN

Specifies whether or not to populate the FirmName field whenstandardizing an address.

Option.StandardizeComponent.FirmName

Yes (default)Y


Address Now Module


NoN

Specifies whether or not to populate the Building field when standardizingan address.

Option.StandardizeComponent.Building

Yes (default)Y

NoN

Specifies whether or not to populate the SubBuilding field whenstandardizing an address.

Option.StandardizeComponent.SubBuilding

Yes (default)Y

NoN

Specifies whether or not to populate the HouseNumber field whenstandardizing an address.

Option.StandardizeComponent.HouseNumber

Yes (default)Y

NoN

Specifies whether or not to populate the SubStreet field whenstandardizing an address.

Option.StandardizeComponent.SubStreet

Yes (default)Y

NoN

Specifies whether or not to populate the StreetName field whenstandardizing an address.

Option.StandardizeComponent.StreetName

Yes (default)Y

NoN

Specifies whether or not to populate the POBox field when standardizingan address.

Option.StandardizeComponent.POBox

Yes (default)Y

NoN

Specifies whether or not to populate the SubCity field when standardizingan address.

Option.StandardizeComponent.SubCity

Yes (default)Y

NoN

Specifies whether or not to populate the City field when standardizingan address.

Option.StandardizeComponent.City

Yes (default)Y

NoN

Specifies whether or not to populate the USCountyName field whenstandardizing an address.

Option.StandardizeComponent.USCountyName

Yes (default)Y

NoN

Specifies whether or not to populate the StateProvince field whenstandardizing an address.

Option.StandardizeComponent.StateProvince

Yes (default)Y




NoN

Specifies whether or not to populate the Principality field whenstandardizing an address.

Option.StandardizeComponent.Principality

Yes (default)Y

NoN

Specifies whether or not to populate the PostalCode field whenstandardizing an address.

Option.StandardizeComponent.PostalCode

Yes (default)Y

NoN

Specifies whether or not to populate the +4 field when standardizing anaddress.

Option.StandardizeComponent.Plus4

Yes (default)Y

NoN

Specifies whether or not to populate the Country field when standardizingan address.

Option.StandardizeComponent.Country

Yes (default)Y

NoN

Specifies whether or not to look for vulgar words. If this option is enabled,ValidateGlobalAddress returns a value in the WCRCode output field toindicate the results.

Option.ReportVulgarWords

YesY

No (default)N

Specifies whether or not to mark vulgar words in the output using theformat ">VulgarWord<".

Option.FlagVulgarWords

YesY

No (default)N

This option controls whether or not to include troubleshooting informationin the output fields Email1, Email2, URL1, and URL2.

Option.DebugOutput

YesY

No (default)N

Validation Options

Table 13: ValidateGlobalAddress Validation Options


Specifies whether or not to include the Department field when validatingan address.

Option.ValidateComponent.Department

YesY

No (default)N


Address Now Module


Specifies whether or not to include the FirmName field when validatingan address.

Option.ValidateComponent.FirmName

YesY

No (default)N

Specifies whether or not to include the Building field when validating anaddress.

Option.ValidateComponent.Building

Yes (default)Y

NoN

Specifies whether or not to include the SubBuilding field when validatingan address.

Option.ValidateComponent.SubBuilding

Yes (default)Y

NoN

Specifies whether or not to include the HouseNumber field whenvalidating an address.

Option.ValidateComponent.HouseNumber

Yes (default)Y

NoN

Specifies whether or not to include the SubStreet field when validatingan address.

Option.ValidateComponent.SubStreet

Yes (default)Y

NoN

Specifies whether or not to include the StreetName field when validatingan address.

Option.ValidateComponent.StreetName

Yes (default)Y

NoN

Specifies whether or not to include the POBox field when validating anaddress.

Option.ValidateComponent.POBox

Yes (default)Y

NoN

Specifies whether or not to include the SubCity field when validating anaddress.

Option.ValidateComponent.SubCity

Yes (default)Y

NoN

Specifies whether or not to include the City field when validating anaddress.

Option.ValidateComponent.City

Yes (default)Y

NoN




Specifies whether or not to include the USCountyName field whenvalidating an address.

Option.ValidateComponent.USCountyName

Yes (default)Y

NoN

Specifies whether or not to include the StateProvince field whenvalidating an address.

Option.ValidateComponent.StateProvince

Yes (default)Y

NoN

Specifies whether or not to include the Principality field when validatingan address.

Option.ValidateComponent.Principality

Yes (default)Y

NoN

Specifies whether or not to include the PostalCode field when validatingan address.

Option.ValidateComponent.PostalCode

Yes (default)Y

NoN

Specifies whether or not to include the +4 field when validating anaddress.

Option.ValidateComponent.Plus4

Yes (default)Y

NoN

Specifies whether or not to include the Country field when validating anaddress.

Option.ValidateComponent.Country

Yes (default)Y

NoN

Specifies whether or not to correct the Country field when validating anaddress.

Option.ForceUpdate.Department

Yes (default)Y

NoN

Specifies whether or not to correct the FirmName field when validatingan address.

Option.ForceUpdate.FirmName

Yes (default)Y

NoN

Specifies whether or not to correct the Building field when validating anaddress.

Option.ForceUpdate.Building

Yes (default)Y

NoN


Address Now Module


Specifies whether or not to correct the SubBuilding field when validatingan address.

Option.ForceUpdate.SubBuilding

Yes (default)Y

NoN

Specifies whether or not to correct the HouseNumber field whenvalidating an address.

Option.ForceUpdate.HouseNumber

Yes (default)Y

NoN

Specifies whether or not to correct the SubStreet field when validatingan address.

Option.ForceUpdate.SubStreet

Yes (default)Y

NoN

Specifies whether or not to correct the StreetName field when validatingan address.

Option.ForceUpdate.StreetName

Yes (default)Y

NoN

Specifies whether or not to correct the POBox field when validating anaddress.

Option.ForceUpdate.POBox

Yes (default)Y

NoN

Specifies whether or not to correct the SubCity field when validating anaddress.

Option.ForceUpdate.SubCity

Yes (default)Y

NoN

Specifies whether or not to correct the City field when validating anaddress.

Option.ForceUpdate.City

Yes (default)Y

NoN

Specifies whether or not to correct the USCountyName field whenvalidating an address.

Option.ForceUpdate.USCountyName

Yes (default)Y

NoN

Specifies whether or not to correct the StateProvince field whenvalidating an address.

Option.ForceUpdate.StateProvince

Yes (default)Y

NoN




Specifies whether or not to correct the Principality field when validatingan address.

Option.ForceUpdate.Principality

Yes (default)Y

NoN

Specifies whether or not to correct the PostalCode field when validatingan address.

Option.ForceUpdate.PostalCode

Yes (default)Y

NoN

Specifies whether or not to correct the +4 field when validating anaddress.

Option.ForceUpdate.Plus4

Yes (default)Y

NoN

Specifies whether or not to correct the Country field when validating anaddress.

Option.ForceUpdate.Country

Yes (default)Y

NoN

Specifies whether or not to overwrite the Department field if an alias isfound in the Address Now database.

Option.ReplaceAlias.Department

YesY

No (default)N

Specifies whether or not to overwrite the FirmName field if an alias isfound in the Address Now database.

Option.ReplaceAlias.FirmName

YesY

No (default)N

Specifies whether or not to overwrite the Building field if an alias is foundin the Address Now database.

Option.ReplaceAlias.Building

YesY

No (default)N

Specifies whether or not to overwrite the SubBuilding field if an alias isfound in the Address Now database.

Option.ReplaceAlias.SubBuilding

YesY

No (default)N

Specifies whether or not to overwrite the HouseNumber field if an aliasis found in the Address Now database.

Option.ReplaceAlias.HouseNumber

YesY

No (default)N


Address Now Module


Specifies whether or not to overwrite the SubStreet field if an alias isfound in the Address Now database.

Option.ReplaceAlias.SubStreet

YesY

No (default)N

Specifies whether or not to overwrite the StreetName field if an alias isfound in the Address Now database.

Option.ReplaceAlias.StreetName

YesY

No (default)N

Specifies whether or not to overwrite the POBox field if an alias is foundin the Address Now database.

Option.ReplaceAlias.POBox

YesY

No (default)N

Specifies whether or not to overwrite the Subcity field if an alias is foundin the Address Now database.

Option.ReplaceAlias.SubCity

YesY

No (default)N

Specifies whether or not to overwrite the City field if an alias is found inthe Address Now database.

Option.ReplaceAlias.City

YesY

No (default)N

Specifies whether or not to overwrite the USCountyName field if an aliasis found in the Address Now database.

Option.ReplaceAlias.USCountyName

YesY

No (default)N

Specifies whether or not to overwrite the StateProvince field if an aliasis found in the Address Now database.

Option.ReplaceAlias.StateProvince

YesY

No (default)N

Specifies whether or not to overwrite the Principality field if an alias isfound in the Address Now database.

Option.ReplaceAlias.Principality

YesY

No (default)N

Specifies whether or not to overwrite the PostalCode field if an alias isfound in the Address Now database.

Option.ReplaceAlias.PostalCode

Yes (default)Y

NoN




Specifies whether or not to overwrite the +4 field if an alias is found inthe Address Now database.

Option.ReplaceAlias.Plus4

YesY

No (default)N

Specifies whether or not to overwrite the Country field if an alias is foundin the Address Now database.

Option.ReplaceAlias.Country

YesY

No (default)N

This option, used in conjunction with the "Force Update", ensures thatno major changes are made to the data during processing.

Option.CautiousUpdate

YesY

No (default)N

Specifies whether or not to correct common address standardizationand validation errors by performing cross-component matching.

Option.CrossComponentMatch

Cross-component matching checks for matches between data found inone field in the input data and another field in the Address Now database.

YesY

No (default)N

Specifies whether or not ValidateGlobalAddress modifies the addressto match the diacritics (accents, umlauts, etc.) in the postal database

Option.UseReferenceDiacritics

when the only changes to the address are the diacritics . One of thefollowing:

Yes (default)Y

NoN

For example, ifUseReferenceDiacritics is enabled, the following wouldoccur:

Input City: Chalon-Sur-SaôneCity in the postal database: CHALON SUR SAONEOutput City: CHALON SUR SAONE

Input City: ARTEMIVS'KCity in the postal database: ARTEMIVSKOutput City: ARTEMIVSK

If UseReferenceDiacritics is not enabled, the following would occur:

Input City: Chalon-Sur-SaôneReference City: CHALON SUR SAONEOutput City: Chalon-Sur-Saône

Input City: ARTEMIVS'KReference City: ARTEMIVSKOutput City: ARTEMIVS'K

Note that this option has no effect on the Transliteration option.


Address Now Module


Specifies whether or not standardization changes such as changing"ROAD" to "RD" should be reported in the ACR code.

Option.KeepStandardizationChanges

YesY

No (default)N

The Acceptance Level setting specifies the minimum number of addresscomponents that must be validated in order for the whole address to be

Option.AcceptanceLevel

considered validated. The value specified for AcceptanceLevelcorresponds to the second character of the ACR code. For moreinformation, see The ACR Code on page 228.

The acceptance level differs from the InnerMatchScore option in thatacceptance level measures how many components Validate GlobalAddress validated, regardless of how well the validated componentsmatched to address components in the postal databases, whereasInnerMatchScore indicates the probability that the output address is thecorrect, validated version of the input address.

One of the following:

The acceptance level is automatically set to an appropriatelevel based on the address's country. For example, U.S.addresses are processed with an acceptance level of 4.

-1

No components validated (default)0

Country only validated1

City and country validated2

City, postal code and country validated3

Street, city, postal code and country validated4

Premise number, building name, sub-building, PO box,company, street, city, postal code, and country validated

5

Specifies the minimum confidence level for address validation.Addresses with a value in the Confidence output field greater than or

Option.InnerMatchScore

equal to this value is validated, and those that have a lower value willnot be validated (the output field Status will contain F.)

Specify any value between 0 and 100. The higher the value, the higherthe degree of confidence necessary for effective address validation.The default is 60.

A whole number from 0 to 10, indicating the relative importance of theFirmName field compared to the data in the Address Now database.

Option.CompanyWeight

This affects the confidence value, and can be used to tailor theconfidence to distinguish correct and incorrect updates. For moreinformation, see The ACR Code on page 228.

The default value is 1.

A whole number from 0 to 10, indicating the relative importance of theStreetName field compared to the data in the Address Now database.

Option.StreetWeight

A whole number from 0 to 10, indicating the relative importance of thisfield compared to the others. For more information, see The ACR Codeon page 228.





A whole number from 0 to 10, indicating the relative importance of theCity field compared to the data in the Address Now database. A whole

Option.CityWeight

number from 0 to 10, indicating the relative importance of this fieldcompared to the others. For more information, see The ACR Code onpage 228.


A whole number from 0 to 10, indicating the relative importance of thePostalCode field compared to the data in the Address Now database.

Option.PostcodeWeight

A whole number from 0 to 10, indicating the relative importance of thisfield compared to the others. For more information, see The ACR Codeon page 228.

The default value is 8

A value from 0 to 8 indicating the number of address lines to use whencalculating the outer match score. The default is 8. For more informationon the outer match score, see The Outer Match Score on page 48.

Option.OuterMatchScoreLines

Output Format Options

Table 14: ValidateGlobalAddress Output Format Options


Specifies whether or not the Department field should be included in theoutput of a formatted address.

Option.FormatComponent.Department

Yes (default)Y

NoN

Specifies whether or not the FirmName field should be included in theoutput of a formatted address.

Option.FormatComponent.FirmName

Yes (default)Y

NoN

Specifies whether or not the Building field should be included in theoutput of a formatted address.

Option.FormatComponent.Building

Yes (default)Y

NoN

Specifies whether or not the SubBuilding field should be included in theoutput of a formatted address.

Option.FormatComponent.SubBuilding

Yes (default)Y

NoN

Specifies whether or not the HouseNumber field should be included inthe output of a formatted address.

Option.FormatComponent.HouseNumber

Yes (default)Y

NoN


Address Now Module


Specifies whether or not the SubStreet field should be included in theoutput of a formatted address.

Option.FormatComponent.SubStreet

Yes (default)Y

NoN

Specifies whether or not the StreetName field should be included in theoutput of a formatted address.

Option.FormatComponent.StreetName

Yes (default)Y

NoN

Specifies whether or not the POBox field should be included in the outputof a formatted address.

Option.FormatComponent.POBox

Yes (default)Y

NoN

Specifies whether or not the SubCity field should be included in theoutput of a formatted address.

Option.FormatComponent.SubCity

Yes (default)Y

NoN

Specifies whether or not the City field should be included in the outputof a formatted address.

Option.FormatComponent.City

Yes (default)Y

NoN

Specifies whether or not the USCountyName field should be includedin the output of a formatted address.

Option.FormatComponent.USCountyName

Yes (default)Y

NoN

Specifies whether or not the StateProvince field should be included inthe output of a formatted address.

Option.FormatComponent.StateProvince

Yes (default)Y

NoN

Specifies whether or not the Principality field should be included in theoutput of a formatted address.

Option.FormatComponent.Principality

Yes (default)Y

NoN

Specifies whether or not the PostalCode field should be included in theoutput of a formatted address.

Option.FormatComponent.PostalCode

Yes (default)Y

NoN

Specifies whether or not the +4 field should be included in the outputof a formatted address.

Option.FormatComponent.Plus4

Yes (default)Y

NoN




Specifies whether or not the Country field should be included in theoutput of a formatted address.

Option.FormatComponent.Country

YesY

No (default)N

Specifies how to format diacritics in the output address. One of thefollowing:

Option.Transliteration

No transliteration is performed. Diacritic characters are left asspecified in the input and/or postal database. Default.

0

Diacritic characters are removed and replaced with theequivalent unadorned character.

1

Diacritic characters are transliterated to an equivalent unadornedcharacter or character sequence using language-specifictransliteration rules.

2

For example, the following shows the effect of each of the threetransliteration options on a Swedish address. Note the differences in"Västra Frölunda".

0

Gustaf Wernersgata 12 S-42132 Västra Frölunda

1

Gustaf Wernersgata 12 S-42132 Vastra Frolunda

2

Gustaf Wernersgata 12 S-42132 Vaestra Froelunda

Response

Address Data Output

Table 15: ValidateGlobalAddress Address Data Output


The formatted first address line.String[79]

AddressLine1

The formatted second address line.String[79]

AddressLine2

The formatted third address line.String[79]

AddressLine3

The formatted fourth address line.String[79]

AddressLine4

The formatted fifth address line.String[79]

AddressLine5

The formatted sixth address line.String[79]

AddressLine6

The formatted seventh address line.String[79]

AddressLine7


Address Now Module


The formatted eighth address line.String[79]

AddressLine8

Apartment designator (such as STE or APT). For example:String[79]

ApartmentLabel


Apartment number. For example:String[79]

ApartmentNumber


The name of a building.String[79]

Building


City

The ISO code or English name of the country. For a list ofISO codes, see Country ISO Codes and Module Supporton page 234.

String[79]

Country

A subdivision of a country used in French and Spanishspeaking countries. For example, France is divided into 100departments.

String[79]

Department

The name of a company. For example:String[79]

FirmName

Pitney Bowes Software4200 PARLIAMENT PLSTE 600LANHAM MD 20706-1844USA

House number. For example:String[79]

HouseNumber


The most precise latitude that could be determined for theaddress. This could be a point level location or a centroid.

String[79]

Latitude

The level of precision can be determined by looking at theECRCode output field. For more information, see The ECRCode on page 47.

The most precise longitude that could be determined for theaddress. This could be a point level location or a centroid.

String[79]

Longitude

The level of precision can be determined by looking at theECRCode output field. For more information, see The ECRCode on page 47.

The post office box number. If the address is a rural routeaddress, the rural route box number will appear here.

String[79]

POBox

The postal code. In the U.S. this is the ZIP Code™.String[79]

PostalCode

The 4-digit add-on part of the ZIP + 4® Code. For example,in the ZIP Code™ 60655-1844, 1844 is the 4-digit add-on.(U.S. addresses only.)

String[79]

PostalCode.AddOn

The 5-digit ZIP Code™. For example 20706 (U.S. addressesonly.)

String[79]

PostalCode.Base

An area within a country. For example, England, Scotland,and Wales are principalities. This field will normally be blank.

String[79]

Principality




The state or province abbreviation.String[79]

StateProvince

Street name. For example:String[79]

StreetName


Street suffix. For example:String[79]

StreetSuffix


A district or suburb. The subcity is used in countries where itis common to include the district or suburb within the address.For example,

String[79]

SubCity



The second street address used to identify an address.Substreets are used in countries where it is common to givetwo street names in the address. For example,

String[79]

SubStreet


In this example, "High Street" is the substreet. Substreets canbe used to precisely identify the delivery location. In theexample, "The Mews" may be a small street that needsanother street identification to properly locate the address,so "High Street" is included. In this case, "High Street" is themain or known street.

For U.S. addresses, the name of the county where theaddress is located.

String[79]

USCountyName

Return Codes

Table 16: ValidateGlobalAddress Return Codes


The Address Correction Result (ACR) code describes whatdata has been changed in each record. For information onwhat this code means, see The ACR Code on page 228.

String[79]

ACRCode


String[79]

Confidence

100 indicates a very high level of confidence that the matchresults are correct. This value is the same as the last threedigits of the ACR code, referred to as the validation matchscore. For more information, see The ACR Code on page228.

The Enhanced Correction Result (ECR) code describes thelevel of precision of the latitude and longitude returned for the

String[79]

ECRCode

address. For mroe information, see The ECR Code on page47.


Address Now Module


Extra standardization information.String[79]

Email1


Email2

A score that measures changes to each address line. Formore information, see The Outer Match Score on page 48.

String[79]

OuterMatchScore

Reports the success or failure of the match attempt.String[79]

Status

• null—Success• F—Failure

Reason for failure, if there is one.String[79]

Status.Code

• UnableToValidate• ServerError• CountryNotFound

Description of the problem, if there is one.String[79]

Status.Description

• Address Not Found—This value will appear ifStatus.Code=UnableToValidate.

• Module not licensed—This value will appear ifStatus.Code=ServerError.

• Could Not Identify Country—This value will appear ifStatus.Code=CountryNotFound.


URL1


URL2

The Word Correction Result (WCR) code describes vulgarwords found in the input address. The code has twocomponents:

String[79]

WCRCode

• Location code—One of the following:• AB—Indicates a vulgarity was found in the address.• NB—Indicates a vulgarity was found in the name.• Count—The number of vulgar words found in the locationindicated by the location code.

For example, AB2 indicates that two vulgar words were foundin the input address.

The ECR CodeThe Enhanced Correction Result (ECR) code describes the level of precision of the latitude/longitudecoordinates returned for the address. The code consists of a prefix followed by a dash then the body ofthe code.

The prefix always begins with "EL" followed by a number from 1 to 5 indicating the overall level ofprecision:

• 5—Point geocode• 4—Street centroid• 3—Postcode centroid



• 2—City centroid• 1—Region centroid

The body of the code identifies the components that were used to match the address to a geocode. Notethat the body consists of letters and numerals. Here's what they mean:

• P—Premise/house number, building or PO box• S—Street• T—City• R—Region/state• Z—Postal code• C—Country

There are only two numeric options in the body: 4 or 0

• 4—The component data was available to make the geocode-address match.• 0—The component date was not available.

For example: EL4-P0S4T4R4Z4C4

In this example, the 0 following the P tells us that premise/house number data was not available to makethis address match; everything from street to country, however, was used in the assignment.

The Outer Match ScoreThe outer match score indicates howmuch ValidateGlobalAddress changed each address line to validatethe address. The score compares the address lines before standardization and after validation andformatting. This score is only generated if you set the option to a value greater than 0.

The outer match score is similar to the validation match score, which is part of the ACR code (see TheACR Code on page 228). The difference is that the outer match scoremeasures any change to an addressline, including formatting, whereas the validation match score measures only whether or not the datacould be validated,

For example, take the following input address lines before processing:

Address Line 1: 5 camden cresAddress Line 2: bathAddress Line 3: uk

After processing the address lines are:

Address Line 1: 5 Camden CrescentAddress Line 2: BathAddress Line 3: BA1 5HYAddress Line 4: United Kingdom

This has a validation match score of 84% and in outer match score of 23%.

The validationmatch score is high because the address components were fairly accurate before validation.The street name was valid except for casing and use of an abbreviation. The city and country were bothvalid. The only thing not correct was the postal code (in this case it was missing). Hence the relativelyhigh validation match score of 84%.

The outer match score is low because after formatting, the address lines are considerably different fromthe input. In this case, Address Line 3 contained "uk" on input, and contains "BA1 5HY" on output. Line4 was empty on input, and in populated on output. Address line 1 has also changed. The outer score istherefore quite low.


Address Now Module

Enterprise Routing Module

GetTravelBoundaryGetTravelBoundary determines a drive or walk time or distance boundary from a location. This featureobtains polygons corresponding to an isochrone or isodistance calculation. An isochrone is a polygonor set of points representing an area that can be traversed in a network from a starting point in a givenamount of time. An isodistance is a polygon or set of points representing the area that is a certain distancefrom the starting point. The Get Travel Boundary operation (also known as an iso definition) takes astarting point, a unit (linear or time), one or more costs and their associated tags as input and returnsthe resulting travel boundary. Cost refers to the amount of time or distance to use in calculating an iso.A tag is a string that identifies the cost and is used to match the corresponding result.

GetTravelBoundary is part of the Enterprise Routing Module.

GetTravelBoundary is only available as a web service. The Get Travel Boundary is not availablethrough the Java, C++, C, .NET, or COM APIs.

Note:

Resource URL

JSON endpoint:

http://server:port/rest/GetTravelBoundary/results.json

XML endpoint:

http://server:port/rest/GetTravelBoundary/results.xml



http://myserver:8080/rest/GetTravelBoundary/results.json?Data.Latitude=33.751748&Data.Longitude=-84.364014&Data.TravelBoundaryCost=10&Data.TravelBondaryCostUnits=Kilometers


Some of the points have been removed from this example to shorten it.Note:

{"output_port": [{"IsoNodeResponse": [],"IsoPolygonResponse": {

"srsName": "epsg:4326","Polygon": [ {

"srsName": "epsg:4326","Exterior": {"LineString": [{"Pos": [

{"X": -84.34868168466456,"Y": 33.68373169496257

},{

"X": -84.36945064055561,"Y": 33.69293307108579

},{

"X": -84.3694506405556,"Y": 33.69293307108579

},



{"X": -84.3694506405556,"Y": 33.69303002973829

},{

"X": -84.37104825254721,"Y": 33.69391558543121

},{

"X": -84.37104825254721,"Y": 33.6936408692491

},{

"X": -84.42163929894845,"Y": 33.716054477754355

},{

"X": -84.4440058668311,"Y": 33.710741143596806

},{

"X": -84.43921303085625,"Y": 33.72800947960886

},{

"X": -84.45678676276404,"Y": 33.73376559161287

},{

"X": -84.43921303085625,"Y": 33.73996448146335

},...

]}]}}]

},"user_fields": [ {

"name": "TravelBondaryCostUnits","value": "Kilometers"

}]}]}



http://myserver:8080/rest/GetTravelBoundary/results.xml?Data.TravelBoundaryCostUnits=Kilometers&Data.Latitude=33.751748&Data.Longitude=-84.364014&Data.TravelBoundaryCost=10


Some of the points have been removed from this example to shorten it.Note:

<ns3:xml.GetTravelBoundaryResponsexmlns:ns2="http://www.mapinfo.com/midev/service/geometries/v1"xmlns:ns3="http://www.pb.com/spectrum/services/GetTravelBoundary">

<ns3:output_port><ns3:IsoRouteResponse>

<ns3:IsoNodeResponse/><ns3:IsoPolygonResponse

xsi:type="ns2:MultiPolygon"srsName="epsg:4326"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<ns2:Polygon srsName="epsg:4326"><ns2:Exterior>

<ns2:LineString><ns2:Pos>



<ns2:X>-84.34868168466456</ns2:X><ns2:Y>33.68373169496257</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.36945064055561</ns2:X><ns2:Y>33.69293307108579</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.3694506405556</ns2:X><ns2:Y>33.69293307108579</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.3694506405556</ns2:X><ns2:Y>33.69303002973829</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.37104825254721</ns2:X><ns2:Y>33.69391558543121</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.37104825254721</ns2:X><ns2:Y>33.6936408692491</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.42163929894845</ns2:X><ns2:Y>33.716054477754355</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.4440058668311</ns2:X><ns2:Y>33.710741143596806</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.43921303085625</ns2:X><ns2:Y>33.72800947960886</ns2:Y>

</ns2:Pos><ns2:Pos>

<ns2:X>-84.45678676276404</ns2:X><ns2:Y>33.73376559161287</ns2:Y>

</ns2:Pos>...

</ns2:LineString></ns2:Exterior>

</ns2:Polygon></ns3:IsoPolygonResponse><ns3:user_fields/>

</ns3:IsoRouteResponse></ns3:output_port>

</ns3:xml.GetTravelBoundaryResponse>

Request

Parameters for Input DataGetTravelBoundary takes cost, cost unit, point latitude, and point longitude as input. The following tableprovides information on the format and layout of the input.

Table 17: GetTravelBoundary Input Data


Latitude of the point. Specify latitude in the formatchosen in the Option.CoordinateFormat parameter.

StringData.Latitude




Longitude of the point. Specify longitude in theformat chosen in the Option.CoordinateFormatparameter.

StringData.Longitude

(Optional) The cost distance or time, in the unitsspecified by either the

StringData.TravelBoundaryCost

Data.TravelBoundaryCostUnits parameter or theOption.DefaultTravelBoundaryCostUnits parameter.For example, if the unit specified is miles and youspecify 10 in this field, the cost would be 10 miles.

Use this field to override the default travel boundarycost on a record-by-record basis.

(Optional) The type of metric used to calculate thetravel boundary. One of the following:

StringData.TravelBoundaryCostUnits

• Feet• Hours• Kilometers• Meters• Miles• Minutes• Seconds• Yards

Use this field to override the default travel boundarycost units on a record-by-record basis.

Parameters for OptionsInput Options

Table 18: GetTravelBoundary Input Options


The name of the database that contains the data to use in the search process.Use the database name specified in the Enterprise Routing Module Routing

Option.DataSetResourceName

Database Resource tool. For more information, see the Spectrum™

Technology Platform Administration Guide.

The coordinate system of the input coordinates. The format must be theEuropean Petroleum Survey Group (EPSG) code, the SRID code, or the

Option.CoordinateSystem

MAPINFO code. Specify the coordinate reference system in the formatcodespace:code. For example, a geometry in Latitude/Longitude (WGS84) would be EPSG:4326. The default value is EPSG:4326, which is alsoknown as Latitude/Longitude (WGS 84). This is a worldwide system and isthe terrestrial reference frame associated with the NAVSTAR GlobalPositioning System (GPS) used extensively for navigation and surveying.This datum is earth-centered ("geocentric") and defined with satellite andterrestrial data.

The following table lists some of the more widely used EPSG codes:




EPSG CodeCoordinate System

4322Longitude/Latitude (WGS 72)

4326Longitude/Latitude (WGS 84)

4269Longitude/Latitude (NAD 83)

4277Longitude/Latitude (OSGB 36)

27700British National Grid

Specifies the format of latitude/longitude coordinates in the input.Option.CoordinateFormat

Use this option only if you specify a Latitude/Longitude coordinatesystem. If the coordinate system is not a Latitude/Longitudecoordinate system, set the coordinate format to Decimal.

Note:


(90.000000, 180.000000)Decimal

(90000000, 180000000). Default.DecimalAssumed

(90 00 00N, 180 00 00W)DegreesMinutesSeconds

(090000000N, 180000000W)PreZero

(090.000000N, 180.000000W)PreZeroDecimal

Number of cost units. The default is 10.Option.DefaultTravelBoundaryCost

Type of metric you want to use to calculate the travel boundary. One of thefollowing:

Option.DefaultTravelBoundaryCostUnits

• Feet• Hours• Kilometers• Meters• Miles• Minutes• Seconds• Yards

Output Options

Table 19: GetTravelBoundary Output Options


Specifies the type of result you want returned. One of the following:Option.ResultType

Returns the entire isoChrone.AccessibleNodes

Returns all of the points along the road networkthat can be reached for the isoChronecalculation.

Geometry




Returns the location specified by the enteredaddress.

StartNodes

Specifies what percentage of the original points should be returned orupon which the resulting polygon should be based.

Option.SimplificationFactor

Specifies the style of banding to be used in the result. Banding stylesare the types of multiple isoChrone or distance bands that can bedisplayed based on multiple costs.

Option.BandingStyle

Each boundary is determined by subtractingout the next smallest boundary.

Donut

Each boundary is determined independentof all others.

EncompassingEncompassing

Specifies whether you want to return holes, which are areas within thelarger boundary that cannot be reached within the desired time ordistance, based on the road network.

Option.ReturnHoles

Yes, return holes.Y

Do not return holes. Default.N

Specifies whether you want to return islands, which are small areasoutside the main boundary that can be reached within the desired timeor distance.

Option.ReturnIslands

Yes, return islands.Y

Do not return islands. Default.N

Travel Options

Travel options specify assumptions to make about travel speed off network roads and whether to useonly major roads when calculating the travel boundary. Most travel options have to do with ambientspeed.

Table 20: GetTravelBoundary Travel Options


Specifies the maximum distance to allow travel off the roadnetwork. Examples of off-network roads include driveways

Option.MaximumOffRoadDistance

and access roads. For example, if you specify a maximumoff road distance of 1 mile the travel boundary will extend nofurther than one mile from the network road. If you specify avalue of 0 the travel boundary will not extend beyond the roaditself. Use the ambient speed options to specify the speed oftravel along non-network roads.

The units of measure in which you want the data returned.One of the following:

Option.Units

• Kilometer (default)• Meter• Mile




Specifies whether to include all roads in the calculation or justmajor roads. If you choose to include only major roads,performance will improve but accuracy may decrease.

Option.MajorRoads

This map represents a travel boundary with travel allowed onall roads:

This map represents a travel boundary with travel restrictedto major roads only:


Include only major roads in the calculation. Default.Y

Include all roads in the calculation.N




Specifies the speed to travel when going off a network roadto find the travel boundary. Examples of off-network travelinclude driveways and access roads.

Option.DefaultAmbientSpeed

This option is available only when you specify a time valuein the Option.DefaultCostUnits parameter or theData.TravelBoundaryCostUnits parameter. The default is 15.Specify the speed units in the Option.AmbientSpeedUnitparameter.

To control how off-network travel is used in the travelboundary calculation, you need to specify the speed of traveloff the road network (the ambient speed). Ambient speed canaffect the size and shape of the travel boundary polygon. Ingeneral, the faster the ambient speed, the larger the polygon.For example, if you were at a point with 5 minutes left, and ifthe ambient speed were 15 miles per hour, boundary pointswould be put at a distance of 1.25 miles. If the ambient speedwere reduced to 10 miles per hour, boundary points wouldbe put at a distance of 0.83 miles. Note that you can limit thedistance allowed off a network road by using the theOption.MaximumOffRoadDistance parameter.

If you are calculating pedestrian travel boundarieswe recommend that you change the default ambientspeed to 3 MPH (5 KPH).

Note:

The unit of measure to use with the value specified in theOption.DefaultAmbientSpeed parameter.

Option.AmbientSpeedUnit

Kilometers per hour.KPH

MILES per hour. Default.MPH

Meters per second.MTPS

Specifies the ambient speed to use for off-network travelbased on the road type. If you do not specify an ambient

Option.AmbientSpeed.RoadType.<Type>

speed for a road type, the default ambient speed will be used,as specified in the Option.DefaultAmbientSpeed parameter.

The following map shows an example of a travel boundarywithout ambient speed overrides:




For comparison, this map shows the same travel boundarywith ambient speed overrides:

<Type> can be one of the following:

• AccessWay• Backroad• Connector• Ferry• Footpath• LimitedAccessDenseUrban• LimitedAccessRural• LimitedAccessSuburban




• LimitedAccessUrban• LocalRoadDenseUrban• LocalRoadRural• LocalRoadSuburban• LocalRoadUrban• MajorLocalRoadDenseUrban• MajorLocalRoadRural• MajorLocalRoadSuburban• MajorLocalRoadUrban• MajorRoadDenseUrban• MajorRoadRural• MajorRoadSuburban• MajorRoadUrban• MinorLocalRoadDenseUrban• MinorLocalRoadRural• MinorLocalRoadSuburban• MinorLocalRoadUrban• NormalRoadDenseUrban• NormalRoadRural• NormalRoadRural• NormalRoadUrban• PrimaryHighwayDenseUrban• PrimaryHighwayRural• PrimaryHighwaySuburban• PrimaryHighwayUrban• RampDenseUrban• RampLimitedAccess• RampMajorRoad• RampPrimaryHighway• RampRural• RampSecondaryHighway• RampUrban• RampSuburban• SecondaryHighwayDenseUrban• SecondaryHighwayRural• SecondaryHighwaySuburban• SecondaryHighwayUrban

ResponseGet Travel Boundary returns the following fields:

Table 21: GetTravelBoundary Outputs


Reports the success or failure of the match attempt.StringStatus




Successnull

FailureF

Reason for failure, if there is one. One of the following:StringStatus.Code

• InsufficientInputData (missing lat/lon)• MalformedInputData (wrong input format)• InputOutOfRange (input is out of range)• EngineError (engine-generated error)

Description of failure indicated in Status.Code.StringStatus.Description

GetTravelCostMatrixGetTravelCostMatrix calculates the travel time and distances between an array of start and end locations.You can use GetTravelCostMatrix to find the shortest or fastest paths between a number of start pointsand a number of end points, and determine the total time and distance of the individual routes (the routecosts). For example if you input four start points (S1 through S4) and four end points (E1 through E4),a total of 16 routes will be returned as illustrated in the following diagram:

Matrix routing is often used to determine service response time and coverages for specific services suchas a fire house or police station. You may require these calculations to ensure they can provide adequatecoverage for service level agreements such as having one or more people who can respond to an incidentwithin 20 minutes of first notification. The calculation can be used an analysis tool to determine the riskof an insured property or person based on the probability that ambulance, public safety, or fire personnelcan reach the property/person in a reasonable amount of time.

Get Travel Cost Matrix is only available as a SOAP web service. Get Travel Cost Matrix is notavailable through REST. It is also not available through the Java, C++, C, .NET, or COM APIs.

Note:

GetTravelCostMatrix is part of the Enterprise Routing Module.

GetTravelDirectionsGetTravelDirections returns routing information for a set of two distinct points or for multiple points. Ittakes a starting latitude and longitude point and an ending latitude and longitude point as input andreturns the route that is either fastest or shortest, depending on how you configure the stage.

Each country has its own database, named in this format: Enterprise Routing Module - <Country>. Eachdatabase also has its own country code. For example, the name of the Austrian database is "EnterpriseRouting Module - Austria," and the Austrian batch country code is "A1T." Each database requires aseparate license.

Get Travel Directions is only available as a SOAP web service. Get Travel Directions is notavailable through REST. It is also not available through the Java, C++, C, .NET, or COM APIs.

Note:

GetTravelDirections is part of the Enterprise Routing Module.



Enterprise Tax Module

AssignGeoTAXInfoAssignGeoTAXInfo identifies the tax districts that apply to a given address. Specifically, AssignGeoTAXInforeturns this information about an address:

• Latitude/longitude• FIPS state codes and county codes• County names• MCD/CCD codes and names• Place codes and names• Incorporated or unincorporated status codes• Cross-reference tax keys• Result indicators• Optionally, the relationship of an address to user-defined polygons

AssignGeoTAXInfo optionally includes enhanced tax jurisdiction information for an address, including:

• Insurance premium districts—Areas designated for the collection of taxes imposed on insurancepolicy premiums, based on the policy holder's address. Insurance premium districts are created bystate governments.

• Payroll tax districts—Areas designated for the collection of taxes imposed on employers to supportstate or local government facilities and services, based on the employee's and/or employer's address.Examples include taxes collected for districts to pay for schools, police, or other services. Payroll taxdistricts are created by state or local governments.

• Payroll system tax codes—Codes that represent specific jurisdictions that collect payroll tax. Usingpayroll system tax codes has advantages over using the payroll tax district information returned byAssign GeoTAX Info:

• AssignGeoTAXInfo uses an additional database to determine payroll tax codes, resulting in moreaccurate payroll tax determination.

• Many payroll systems use specific codes to determine withholding amounts. Since you can customizethe payroll tax codes returned by AssignGeoTAXInfo, you can set up a process whereAssignGeoTAXInfo returns the exact payroll tax codes required by your payroll system, instead ofreturning jurisdictional IDs that must then be translated into the codes used by your system.

• Property tax districts—Areas designated for the collection of taxes imposed on property owners tosupport local government facilities and services, based on the property's location. Examples includetaxes collected for districts to pay for schools, police, or other services. Property tax districts are createdby local governments.

• Special purpose tax districts—Areas designated for the collection of taxes imposed on residents tosupport specialized services for residents of the district, based on the resident's address. Examplesinclude services such as sewer service, transit service, or water resources. Special purpose tax districtsare created by legislative action, court action, or public referendums. This optional information requiresthe use of boundary files which require an additional license. Contact your Pitney Bowes Softwaresales representative for more information.

AssignGeoTAXInfo is part of the Enterprise Tax Module.

Resource URL

JSON endpoint:

http://server:port/rest/AssignGeoTaxInfo/results.json



XML endpoint:

http://server:port/rest/AssignGeoTaxInfo/results.xml



http://myserver:8080/rest/AssignGeoTAXInfo/results.json?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY&Data.PostalCode=12180


{"output_port": [{"Confidence": "100.0","ProcessedBy": "GTX","Census.MatchCode": "S","Census.MatchLevel": "Street","Census.BlockCode": "1","Census.Tract": "052301","County.Code": "083","County.Name": "Rensselaer","StateCode": "36","MCD.Code": "52100","MCD.Name": "North Greenbush","MSA.Code": "0160","MSA.Name": "Albany-Schenectady-Troy Ny","LatLong": "042.683028N073.702969W","LatLong.MatchCode": "R","LatLong.MatchLevel": "Rooftop","LatLong.StreetMatchCode": " ","LatLong.StreetMatchLevel": "","Latitude": "042.683028","Latitude.Directional": "N","Longitude": "073.702969","Longitude.Directional": "W","GeoTAXKey.MatchCode": " ","GeoTAXKey.MatchLevel": "NoMatch","GeoTAXKey": "","State.Abbreviation": "NY","Place.ClassCode": "","Place.Code": "00000","Place.IncorporatedFlag": "Unknown","Place.Name": "","Place.LastAnnexedDate": "","Place.LastUpdatedDate": "","Place.LastVerifiedDate": "","AuxiliaryData.AuxiliaryFile": "","AuxiliaryData.StateFile": "","AddressLine1": "1 Global View","City": "Troy","StateProvince": "NY","PostalCode": "12180","Place.PostalCodeConfidence": " ","County.PostalCodeConfidence": " ","GNISCode": "000000000","NumberUserBoundariesFound": "00","PTC.MatchCode": " ","NumberPTCsFound": "0","StateCounty": "","GTX.ErrorCode": "","GTX.ErrorDescription": "","GTX.WarnCode": "","GTX.WarnDescription": "","user_fields": []

}]}





http://myserver:8080/rest/AssignGeoTAXInfo/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY&Data.PostalCode=12180


<ns2:xml.AssignGeoTAXInfoResponsexmlns:ns2="http://www.pb.com/spectrum/services/AssignGeoTAXInfo">


<ns2:Confidence>100.0</ns2:Confidence><ns2:ProcessedBy>GTX</ns2:ProcessedBy><ns2:Census.MatchCode>S</ns2:Census.MatchCode><ns2:Census.MatchLevel>Street</ns2:Census.MatchLevel><ns2:Census.BlockCode>1</ns2:Census.BlockCode><ns2:Census.Tract>052301</ns2:Census.Tract><ns2:County.Code>083</ns2:County.Code><ns2:County.Name>Rensselaer</ns2:County.Name><ns2:StateCode>36</ns2:StateCode><ns2:MCD.Code>52100</ns2:MCD.Code><ns2:MCD.Name>North Greenbush</ns2:MCD.Name><ns2:MSA.Code>0160</ns2:MSA.Code><ns2:MSA.Name>Albany-Schenectady-Troy Ny</ns2:MSA.Name><ns2:LatLong>042.683028N073.702969W</ns2:LatLong><ns2:LatLong.MatchCode>R</ns2:LatLong.MatchCode><ns2:LatLong.MatchLevel>Rooftop</ns2:LatLong.MatchLevel><ns2:LatLong.StreetMatchCode/><ns2:LatLong.StreetMatchLevel/><ns2:Latitude>042.683028</ns2:Latitude><ns2:Latitude.Directional>N</ns2:Latitude.Directional><ns2:Longitude>073.702969</ns2:Longitude><ns2:Longitude.Directional>W</ns2:Longitude.Directional>


</ns2:xml.AssignGeoTAXInfoResponse>

Request

Parameters for Input DataThe following table provides information on the format of AssignGeoTAXInfo input.

Table 22: AssignGeoTAXInfo Input Data



Data.AddressLine1


Data.AddressLine2


Data.AddressLine2


Data.AddressLine4

Specifies the width of the polygon buffers to use for BoundaryFile processing. The buffer width is used to determine if a

String[10]

Data.BufferWidth




point is close to the edge of a polygon. The output fieldBufferRelation indicates whether or not the point is within thepolygon's buffer area. For more information, see Bufferingon page 232.

This field overrides the value specified in theOption.DefaultBufferWidth parameter. Specify the borderwidth in the units specified by the Option.DistanceUnitsparameter.

If you do not specify a buffer width in this input field, thedefault is used.

City nameString[50]

Data.City

The country where the address resides. The data you enterin this field has no impact on processing. It is simply passedthrough to output.

String[var]

Data.Country

AssignGeoTAXInfo only supports US addresses.Note:

Company or firm nameString[var]

Data.FirmName

Nine-digit ZIP CodeString [9]Data.PostalCode

The state where the address resides. The data you enter inthis field has no impact on processing. It is simply passedthrough to output.

String[50]

Data.StateProvince

Specifies the width of the polygon buffers to use forUser-Defined Boundary File processing. The buffer width is

Long[10]

Data.UseBufferWidth

used to determine if a point is close to the edge of a polygon.The output field BufferRelation indicates whether or not thepoint is within the polygon's buffer area. For more information,see Buffering on page 232.

This field overrides the value specified in theOption.DefaultBufferWidth parameter. Specify the borderwidth in the units specified by the Option.DistanceUnitsparameter.

If you do not specify a buffer width in this input field, thedefault is used.

Parameters for OptionsData

Data options control the data returned by AssignGeoTAXInfo. Table 23: AssignGeoTAXInfo DataOptions on page 64 lists the output data options.



Table 23: AssignGeoTAXInfo Data Options


The name of the database resource that contains the data to use in thesearch process. Use the database name specified in the Management

Option.Database.GTX

Console's Database Resources tool. For more information, see theSpectrum™ Technology Platform Administration Guide.

Specifies whether or not AssignGeoTAXInfo should attempt a match tothe street level data.

Option.UseStreetLevelMatching

Yes, use the street matcher (default).Y

No, do not use the street matcher.N

Specifies whether or not AssignGeoTAXInfo should attempt a match tothe GeoTAX Auxiliary file. The GeoTAX Auxiliary file contains newaddresses that have not yet been added to the Master File.

Option.UseGeoTaxAuxiliaryFile

Because matching to the GeoTAX Auxiliary file involves street-levelmatching, you must specify Option.UseStreetLevelMatching=Y in orderfor this option to work.

Yes, attempt to match to GeoTAX Auxiliary file (default).Y

No, do not use the GeoTAX Auxiliary file.N

Specifies whether or not AssignGeoTAXInfo should attempt a match toa User Auxiliary file. User Auxiliary files are user-defined files that the

Option.UseAuxiliaryFile

Enterprise Tax Module uses to override results from the master files instreet-level matching.

Because matching to the User Auxiliary file involves street-levelmatching, you must specify Option.UseStreetLevelMatching=Y in orderfor this option to work.

Yes, attempt to match to User Auxiliary file.Y

No, do not use the User Auxiliary file (default).N

Specifies whether or not AssignGeoTAXInfo should attempt a match tothe state-supplied file. Use this option in combination withFileSearchOrder to specify a state-supplied file to use.

Option.UseStateProvidedFile

State-supplied files are provided by individual state governments. Bymatching to the state-supplied files, you can remain compliant with taxjurisdiction assignment requirements mandated by new federal andstate laws, such as the Mobile Telecommunications Sourcing Act andthe Florida state Communications Services Tax Simplification Law.

There are two supported file formats: the Florida-native format and thenational TS-158 format (ANSI Transaction Set No. 158). The state ofFlorida provides address files in both the TS-158 and its own nativeformat. The state of Washington provides address data in the TS-158format.

Assign GeoTAX Info attempts to match to the state supplied file first. Ifa state match cannot be found, it attempts a match to the master files.

You must install the appropriate state-supplied file to use these options.For instructions, see the Spectrum™ Technology Platform InstallationGuide.





Yes, attempt to match to state-supplied file.Y

Do not use the state-supplied file (default).N

Specifies which state-supplied file to use. This option only takes effectif you specify Option.UseStateProvidedFile=Y. One of the following:

Option.FileSearchOrder

Use only the Florida-native formatted file.FLOnly

Use only the TS-158 formatted file.TSOnly

Specifies whether or not AssignGeoTAXInfo matches input addresseswith secondary information to records without secondary information.This option applies only to Florida-native files. One of the following:

Option.UseRelaxedSecondaryMatching

Yes, use relaxed matching.Y

No, do not use relaxed matching (default).N

Select one or more of the following to obtain the type of data you wantreturned. AssignGeoTAXInfo groups the output fields into record types.

Option.GeoTAXOutputRecordType

If you do not want all of the fields in a record type returned, do not selectthe check box, and list only those fields you want returned in ExtraOutput Fields.

• C—Census• L—Latitude/Longitude• T—Tax Jurisdiction• U—User-defined boundary file• W—Payroll System Tax Codes• X—Auxiliary File

You can also specify one, and only one, of the following:

Insurance Premium Tax District (IPD)I

Property Tax District (PTD)P

Payroll Tax District (PAY)R

Special Purpose Tax District (SPD)S

For a description of the fields in each output group, see Response onpage 68.

If you specify W, to obtain the best payroll system tax codematch possible.

Note:

If you integrate AssignGeoTAXInfo with third-party tax compliancesoftware from Vertex or ADP/Taxware, select which vendor you use.

Option.TaxKey

This controls the value returned in the GeoTAXKey output field. One ofthe following:

Return the Taxware jurisdiction code for the address.T

Return the Vertex jurisdiction code for the address. Select thisoption if you obtained a MatchMaster file from Vertex.

Y




Return the Vertex jurisdiction code for the address. Select thisoption if you obtained a Vertex file from Pitney BowesSoftware.

V

Do not return either the Taxware or Vertex jurisdiction codes(default).

N

Indicates the individual output fields you want returned. You can usethis field instead of the Output Record Type to limit the output to thosefields that are important to your current data needs.

Option.OutputFields

For a list of the fields included in each data type, see Response onpage 68.

Specifying Default State-Supplied File Options

If you use the Spectrum™ Technology Platform API, note that the value you specify in the ManagementConsole for the State supplied file field controls the default settings for three AssignGeoTAXInfo APIoptions: UseStateProvidedFile, UseRelaxedSecondary, and FileSearchOrder. The following table showhow each value in the State supplied file field affects these three options.

UseRelaxedSecondaryFileSearchOrderUseStateProvidedFile"State supplied file" value

NN/ANNone

NFSOnlyYFlorida-native

YFSOnlyYFlorida-native with relaxedsecondary matching

NTSOnlyYTS-158

Geocoding

Geocoding is the process of determining the latitude/longitude coordinates of a given address. Addresscoordinates are used as the basis for determining the tax jurisdictions for an address. Geocoding optionscontrol how AssignGeoTAXInfo determines address latitude and longitude.

Table 24: AssignGeoTAXInfo Geocoding Options


Indicates the offset distance in feet from the street center line.Option.LatLongOffset

The offset distance is used in street-level geocoding to prevent thegeocode from being in the middle of a street. It compensates for thefact that street-level geocoding returns a latitude and longitude point inthe center of the street where the address is located. Since the buildingrepresented by an address is not on the street itself, you do not wantthe geocode for an address to be a point on the street. Instead, youwant the geocode to represent the location of the building which sitsnext to the street. For example, an offset of 50 feet means that thegeocode will represent a point 50 feet back from the center of the street.The distance is calculated perpendicular to the portion of the streetsegment for the address. Offset is also used to prevent addresses across




the street from each other from being given the same point. The followingdiagram shows an offset point in relation to the original point.

No offset (default).0

Twenty feet offset from street center line20

Forty feet offset from street center line40

Sixty feet offset from street center line60

Specifies if AssignGeoTAXInfo should squeeze the street end pointswhen determining the geocode of an address in street-level matching.

Option.Squeeze

The squeeze value is 5% (2.5% from each endpoint). The followingdiagram compares the end points of a street segment to the squeezedend points of a street segment.

No, do not apply squeeze.N

Apply squeeze (default).Y

Indicates the desired format for returned latitude/longitude. Optionsinclude:

Option.LatLongFormat

Latitude/longitude in the following format:090000000N180000000W. (Default)

PreZero

Latitude/longitude in the following format:090.000000N180.000000W.

PreZeroDecimal

Latitude/longitude in the following format:90.000000-180.000000.

Decimal

Latitude/longitude in the following format:90000000-180000000.

DecimalAssumed

Latitude/longitude in the following format: 90 0000N180 00 00W.

DegMinSec

Specifies the units in which to measure distance. One of the following:Option.DistanceUnits




Distances are measured in miles.Miles

Distances are measured in kilometers.Km

Distances are measured in feet. (Default)Feet

Distances are measured in meters.Meters

Specifies the buffer width to use for tax district boundary files. The taxdistrict boundary files are the Special Purpose District (SPD) file, the

Option.DefaultBufferWidth

Insurance Premium District (IPD) file, the Payroll Tax District (PAY) fileand the Personal Property Tax District (PTD) file.

Specify the distance in the units of measurement specified in theDistanceUnits option.

The default buffer width that you specify here can be overridden on arecord-by-record basis using the BufferWidth input field.

For more information on buffers, see Buffering on page 232.

Specifies the buffer width to use for user-defined boundary files. Specifythe distance in the units of measurement specified in theDistanceUnits

Option.DefaultUserBufferWidth

option. For information on buffers, see Buffering on page 232. Thedefault buffer width that you specify here can be overridden on arecord-by-record basis using the BufferWidth input field.

To use buffers, the user-defined boundary file must supportbuffers.

Note:

Output Format

Output format options control how AssignGeoTAXInfo formats output data. The following table lists theoutput format options.

Table 25: AssignGeoTAXInfo Output Format Options


Specifies the casing of these output fields: County.Name, MSA.Name,MCD.Name, Place.Name, IPDn.DistrictName, PAYn.DistrictName,SPDn.DistrictName, and PTCn.PayrollDescription.

Option.OutputCasing


The output in mixed case (default). For example:Rensselaer.

M

The output in upper case. For example: RENSSELAER.U

Response

Auxiliary FileThe following table lists the output fields that contain auxiliary file data. To include auxiliary file data inthe output, set GeoTAXOutputRecordType = X. The following table lists the output fields that containtax jurisdiction data.



Table 26: Auxiliary File Output Fields

DescriptionResponse Element

Data retrieved as a result of an auxiliary match from the user-definedarea of the auxiliary file.

AuxiliaryData.AuxiliaryFile

Data retrieved as a result of a state match. Data content and formatvary depending on the state file used.

AuxiliaryData.StateFile

CensusThe census output fields contains census information from the U.S. Census, including Minor Civil Divisions(MCDs) and Census County Division (CCD) names and codes. MCDs are the primary political oradministrative divisions of a county, representing many kinds of legal entities with a variety of governmentaland administrative functions. CCDs are established in states where there are no legally establishedMCDs. The Census Bureau recognizes MCDs in 28 states and has established CCDs in 21 states. TheDistrict of Columbia has no primary divisions, and the city of Washington, DC is considered equivalentto an MCD for data presentation purposes.

Census data also contains the Federal Information Processing Standards (FIPS) codes for each stateand county. The FIPS State Code and the FIPS County Code are both used by the Census Bureau toidentify these geographic units.

The following table lists the output fields that contain census data. To include census data in the output,set GeoTAXOutputRecordType = C.

Table 27: Census Data Output Fields


Census Block Group code.Census.BlockCode

The level of match obtained against the databases.Census.MatchCode

This field is always included in the output regardless of whetheror not you choose to include census data in the output.

Note:

Auxiliary street matchA

State file address matchG

Street address matchS

GeoTAX Auxiliary file matchU

ZIP + 4 Code level match9

ZIP Code level match5

Unsuccessful matchnull

The level of match obtained against the databases.Census.MatchLevel


Note:

Auxiliary street matchAuxiliary

GeoTAX Auxiliary file matchAux2




Street address matchStreet

State file address matchGov

ZIP + 4 Code level matchZIP+4

ZIP Code level matchZIP

No matchnull

Six-digit tract number extracted from the Census.BlockCode.Census.Tract

Three-digit Federal Information Processing Standards (FIPS) countycode extracted from the Census.BlockCode.

County.Code


Note:

Name of the county.County.Name


Note:

Unique nine-digit Geographic Names Information System (GNIS) code.GNISCode


Note:

Minor Civil Division/Census County Division (MCD/CCD) Code.MCD.Code

Minor Civil Division/Census County Division (MCD/CCD) name.MCD.Name

Metropolitan Statistical area (MSA) code.MSA.Code

Metropolitan Statistical area (MSA) name.MSA.Name

Two-character state abbreviation.State.Abbreviation

This field is always included in the output regardless of whetheror not you choose to include census data in the output

Note:

Two-digit Federal Information Processing Standards (FIPS) state codeextracted from the Census.BlockCode.

StateCode


Note:

Input AddressAssignGeoTAXInfo always returns the input address as part of the output. The input address fields arereturned as input from the data. AssignGeoTAXInfo does not change these input values.

Table 28: Input Address Output Fields


Input address line 1.AddressLine1







Input address city.City

Input address country.Country

Input address firm name.FirmName

Input address postal codePostalCode

Input address state.StateProvince

Insurance Premium Tax DistrictThe following table lists the output fields that contain Insurance Premium Tax District (IPD) data. Formore information on insurance premium tax districts, see AssignGeoTAXInfo on page 60. To includecensus data in the output, set GeoTAXOutputRecordType = I.

AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.Note:

Table 29: Insurance Premium Tax District Output Fields


Indicates where in the district the address residesin relation to the edge of the district.

IPDn.BoundaryBuffer.BufferRelation


The address is inside the district at a distancefrom the edge that is greater than the

P

specified buffer width. Buffer width is specifiedeither by the option or by the input fieldBufferWidth.

The address is inside the district but is closeto the edge. This indicates that the address

I

is in the buffer area specified either by theoption or by the input field BufferWidth.

The address is outside the district but is closeto the edge. This indicates that the address

B

is in the buffer area specified either by theoption or by the input field BufferWidth.

For more information, see Buffering on page 232.

Indicates the distance from the address to theborder of the district. The distance is in the unitsspecified by the option .

IPDn.BoundaryBuffer.DistanceToBorder

IPD ID.IPDn.DistrictID

IPD name.IPDn.DistrictName




IPD district type.IPDn.DistrictType

IPD update date.IPDn.UpdateDate

IPD compiled date.IPDn.VersionDate

Tax code descriptions.IPDn.Notes

Field Length: 20

Possible Values: 01, 33, A, B

IPD change date.IPDn.ChangeDate

MMDDYY - Identifies when district becomes active- State supplied

IPDn.EffectiveDate

Field Length: 6

Possible Values: 010108

MMDDYY - Identifies when district becomesinactive - State supplied

IPDn.ExpirationDate

Field Length: 6

Possible Values: 063009

Format is dependent on associated flagIPDn.FireRate

Field Length: 20

Possible Values: .13, 15.00 or 3;7

P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.FireFlag

F - Flat Fee dollar amount

M - Multiple Percentages has a semi colon as adelimiter. 3;7 = "3% or 7%"

Format is dependent on associated flagIPDn.CasualtyRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.CasualtyFlag


M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"

Format is dependent on associated flagIPDn.VehicleRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.VehicleFlag



Format is dependent on associated flagIPDn.MarineRate




Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.MarineFlag



Format is dependent on associated flagIPDn.HealthRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.HealthFlag



Format is dependent on associated flagIPDn.LifeRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.LifeFlag

P - Percentage; .1 = 10%, .0575 = 5.75%


Format is dependent on associated flagIPDn.OtherRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.OtherFlag



Format is dependent on associated flagIPDn.MinimumRate

Field Length: 20


P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.MinimumFlag



Number of IPDs returned.NumberIPDsFound



Latitude/LongitudeThe following table lists the output fields that contain latitude and longitude data. Latitude/Longitude datacontains the coordinates for the address and additional information about how AssignGeoTAXInfodetermined the latitude and longitude. To include latitude/longitude data in the output, setGeoTAXOutputRecordType = L.

Table 30: Latitude/Longitude Output Fields


Seven-digit number in degrees and calculated to four decimal places(in the format you specified).

Latitude

Latitude directional.Latitude.Directional

NorthN

SouthS

Returned latitude/longitude, in the format you specified (up to 22alphanumeric characters).

LatLong

Level of match for the latitude/longitude.LatLong.MatchCode

ZIP + 2 centroid2

ZIP + 4 Code centroid4

ZIP Code centroid based on a ZIP + 4 code.5

Block group centroidB

Address-level based on street addressR

Census tract centroidT

Address-level match using the GeoTAX AuxiliaryDatabase

U

ZIP Code centroid based on a five-digit ZIP codeZ

No latitude/longitude determinednull

Level of match for the latitude/longitude.LatLong.MatchLevel

Block group centroidBlock

Exact address matchRooftop

Census tract centroidTract

ZIP Code centroidZIP

ZIP + 2 centroidZIP+2

ZIP + 4 centroidZIP+4

Address-level match using the GeoTAXAuxiliary Database

Auxiliary

Output street address return code.LatLong.StreetMatchCode

House number not found on streetH

Latitude/longitude not determined on auxiliary matchL




Street not found in ZIP CodeS

ZIP Code not found in street address databaseZ

Street-level matching option not selectedN

The street was successfully matchednull

Street level match used to determine the latitude/longitude.LatLong.StreetMatchLevel

Successful matchFullMatch

House number not found on streetHouseNotFound

Latitude/longitude not determined onauxiliary match

LatLongNotFound

Street not found in ZIP CodeStreetNotFound

ZIP Code not found in street addressdatabase

ZipNotFound

Street-level matching option not selectedNotUsed

Seven-digit number in degrees and calculated to four decimal places(in the format specified).

Longitude

Longitude directional.Longitude.Directional

EastE

WestW

Payroll System Tax CodeThe following table lists the output fields that contain Payroll System Tax Code (PTC) data. For moreinformation on payroll tax districts, see AssignGeoTAXInfo on page 60. To include this data in theoutput, set GeoTAXOutputRecordType = W.

AssignGeoTAXInfo returns up to six payroll tax codes per address.Note:

Table 31: Payroll System Tax Code Output Fields


Number of payroll system tax codes found for this address.NumberPTCsFound

Indicates the level of match obtained for the address. In order frommostspecific match to least, the possible match codes are:

PTC.MatchCode

The address was matched to a specific Payroll District ID.This is the most specific match.

P

The address was matched to a GNIS Code.G

The address was matched to a county's FIPS code.F

The address was matched to a state's FIPS code. This is theleast specific match.

S




A code that represents a taxing authority in a payroll application. Thisis a user-defined code. The specific codes are determined by the payrollapplication that utilizes the data returned by AssignGeoTAXInfo.

PTCn.PayrollCode

A description of the purpose of this payroll code.PTCn.PayrollDescription

A user-defined flag from the PTC database.PTCn.PayrollFlag

The state abbreviation and county name.StateCounty

Payroll Tax DistrictThe following table lists the output fields that contain Payroll Tax District (PAY) data. For more informationon payroll tax districts, see AssignGeoTAXInfo on page 60. To include this data in the output, setGeoTAXOutputRecordType = R.


Table 32: Payroll Tax District Output Fields


Number of PAYs returned.NumberPAYsFound

Indicates where in the district the address resides in relationto the edge of the district.

PAYn.BoundaryBuffer.BufferRelation


The address is inside the district at a distance from theedge that is greater than the specified buffer width.

P

Buffer width is specified either by the option or by theinput field BufferWidth.

The address is inside the district but is close to theedge. This indicates that the address is in the buffer

I

area specified either by the option or by the input fieldBufferWidth.

The address is outside the district but is close to theedge. This indicates that the address is in the buffer

B



Indicates the distance from the address to the border of thedistrict. The distance is in the units specified by the option.

PAYn.BoundaryBuffer.DistanceToBorder

PAY district ID.PAYn.DistrictID

PAY district name.PAYn.DistrictName

PAY district type.PAYn.DistrictType

PAY ID.PAYn.ID

PAY municipality emergency municipal services tax.PAYn.MunicipalEMSTax




The values for Pennsylvania are:

Levies the taxY

Does not levy the taxN

All other states are null.

PAY municipality income tax.PAYn.MunicipalIncomeTax


ResidentR

Non-residentN

BothB

NoneX


PAY school district emergency municipal services tax.PAYn.SchoolDistrictEMSTax

The Values for Pennsylvania are:

Levies the taxY

Does not levy the taxN


PAY school district income tax.PAYn.SchoolDistrictIncomeTax


ResidentR

Non-residentN

BothB

NX

The values for Ohio are:

ResidentR

NoneX


Property Tax DistrictThe following table lists the output fields that contain Property Tax District (PTD) data. For more informationon property tax districts, see AssignGeoTAXInfo on page 60. To include this data in the output, setGeoTAXOutputRecordType = P.




Table 33: Property Tax District Output Fields


Number of PTDs returned.NumberPTDsFound


PTDn.BoundaryBuffer.BufferRelation



P



I



B




PTDn.BoundaryBuffer.DistanceToBorder

PTD district ID.PTDn.DistrictID

PTD district name.PTDn.DistrictName

PTD district type. Only returned for Indiana.PTDn.DistrictType

Reporting districtR

Billing districtB

PTD jurisdiction ID.PTDn.JurisdictionID

PTD update date.PTDn.UpdateDate

Result IndicatorsThe following table lists the output fields that contain results data. Result indicators describe how wellAssignGeoTAXInfo matched the input address to a known address and assigned a location. These fieldsare always included in output from AssignGeoTAXInfo.

Table 34: Result Indicator Output Fields


Indicates the confidence in the output provided; from 0 to 100. Thehigher the score, the higher the confidence in the match. Calculated

Confidence

based on the match results for individual output fields, using the followingalgorithm:




Census.MatchCode + Latlong.StreetMatchCode + LatLong.MatchCode

The maximum confidence score is 100, so if this calculation results ina value greater than 100, the Confidence score is returned as 100.

AssignGeoTAXInfo uses the following values:

• Census.MatchCode

• A = 85• G = 85• S = 85• U = 85• 9 = 65• 5 = 45• null = 0

• LatLong.StreetMatchCode

• H = 5• S = 0• L = 0• Z = -10• null = 10

• LatLong.MatchCode

• 2 = 0• 4 = 5• 5 = -5• B = 2• R = 10• T = -2• U = 10• Z = -5• null = -10

This field contains a return code if the GeoTAX engine experiences anabnormal termination.

GTX.ErrorCode

This field contains the same set of codes returned by thestandalone GeoTAX software and is intended for users who

Note:

have migrated from GeoTAX to Spectrum™ TechnologyPlatform.

The first character indicates the file (or set of files affected).

Auxiliary fileA

Base fileB

Boundary fileD

User defined boundary fileF

Street fileG

Logical I/O program abendL




State supplied filesS

GeoTAX Auxiliary fileU

Street and state filesX

The second position is one of the following:

Both Florida and TS158 state files are problematicE

Expired databaseF

InformationalI

If the GeoTAX engine experiences an abnormal termination, this fieldcontains a text description of the reason. It is blank if GeoTAX terminatednormally. The maximum length is 80.

GTX.ErrorDescription

This field contains the same set of descriptions returned by thestandalone GeoTAX software and is intended for users who

Note:


SI-"TS158 FILES NOT FOUND"SI-"TS158 FILES VINTAGE OR INCOMPLETE DB ERROR"SI-"STATE FILES NOT FOUND"SE-"STATE AND TS158 FILES NOT FOUND"SE-"STATE NOT FOUND AND TS158 VINTAGE ERROR"SI-"STATE FILES VINTAGE OR INCOMPLETE DB ERROR"SE-"STATE VINTAGE ERROR AND TS158 NOT FOUND"SE-"STATE AND TS158 FILES VINTAGE OR INCOMPLETE DBERROR"GI-"STREET FILES NOT FOUND"XI-"STREET AND TS158 FILES NOT FOUND"XI-"STREET NOT FOUND AND TS158 FILES VINTAGE ERROR"XI-"STREET AND STATE FILES NOT FOUND"XE-"STREET STATE AND TS158 FILES NOT FOUND"XE-"STREET AND STATE NOT FOUND AND TS158 VINTAGEERROR"XI-"STREET NOT FOUND AND STATE VINTAGE ERROR"XE-"STREET AND TS158 NOT FOUND AND STATE VINTAGEERROR"XE-"STREET NOT FOUND AND STATE AND TS158 VINTAGEERROR"GI-"STREET FILES VINTAGE OR INCOMPLETE DB ERROR"XI-"STREET VINTAGE ERROR AND TS158 NOT FOUND"XI-"STREET AND TS158 FILES VINTAGE OR INCOMPLETE DBERROR"XI-"STREET VINTAGE ERROR AND STATE NOT FOUND"XE-"STREET VINTAGE ERROR AND STATE AND TS158 NOTFOUND"XE-"STREET AND TS158 VINTAGE ERROR AND STATE NOTFOUND"XI-"STREET AND STATE FILES VINTAGE OR INCOMPLETE DBERROR"XE-"STREET AND STATE VINTAGE ERROR AND TS158 NOTFOUND"




XE-"STREET STATE AND TS158 VINTAGE ERROR"LF-"INVALID FUNCTION PASSED TO GTDBLIO : "AI-"GENIO ERROR: FILE = G1GTAUX , FUNC = , ST = "UI-"GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST = "XF-"The (DB Vintage) database has expired!"XF-"The (SPD file Vintage) SPD File has expired!"DI- "UNABLE TO VALIDATE BOUNDARY LICENSE"DI- "UNABLE TO OPEN BOUNDARY FILE"DI- "BOUNDARY FILE NOT FOUND"FI- "UNABLE TO VALIDATE USER BOUNDARY LICENSE"FI- "UNABLE TO OPEN USER BND FILE"FI- "USER BND FILE NOT FOUND"

This field contains warning codes returned by the GeoTAX engine. It isblank if no warnings were issued. A value of WN indicates a databasewill expire next month.

GTX.WarnCode

This field contains the same set of codes returned by thestandalone GeoTAX software and is intended for users who

Note:


A text description of any warnings returned by the GeoTAX engine.GTX.WarnDescription

This field contains the same set of descriptions returned by thestandalone GeoTAX software and is intended for users who

Note:


Reports the success or failure of the match attempt.Status

Successnull

Failure. Some examples of failures are your license expiredor you did not select any output record types and fields forAssignGeoTAXInfo to return.

F

If AssignGeoTAXInfo could not process the address, this field will showthe reason. Currently there is one possible value for this field: InvalidAddress.

Status.Code

If AssignGeoTAXInfo could not process the address, this field will showa description of the failure. One of the following:

Status.Description

TS158 FILES NOT FOUNDTS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTATE FILES NOT FOUNDSTATE AND TS158 FILES NOT FOUNDSTATE NOT FOUND AND TS158 VINTAGE ERRORSTATE FILES VINTAGE OR INCOMPLETE DB ERRORSTATE VINTAGE ERROR AND TS158 NOT FOUNDSTATE AND TS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTREET FILES NOT FOUNDSTREET AND TS158 FILES NOT FOUNDSTREET NOT FOUND AND TS158 FILES VINTAGE ERRORSTREET AND STATE FILES NOT FOUNDSTREET STATE AND TS158 FILES NOT FOUND




STREET AND STATE NOT FOUND AND TS158 VINTAGE ERRORSTREET NOT FOUND AND STATE VINTAGE ERRORSTREET AND TS158 NOT FOUND AND STATE VINTAGE ERRORSTREET NOT FOUND AND STATE AND TS158 VINTAGE ERRORSTREET FILES VINTAGE OR INCOMPLETE DB ERRORSTREET VINTAGE ERROR AND TS158 NOT FOUNDSTREET AND TS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTREET VINTAGE ERROR AND STATE NOT FOUNDSTREET VINTAGE ERROR AND STATE AND TS158 NOT FOUNDSTREET AND TS158 VINTAGE ERROR AND STATE NOT FOUNDSTREET AND STATE FILES VINTAGE OR INCOMPLETE DB ERRORSTREET AND STATE VINTAGE ERROR AND TS158 NOT FOUNDSTREET STATE AND TS158 VINTAGE ERRORINVALID FUNCTION PASSED TO GTDBLIO :GENIO ERROR: FILE = G1GTAUX , FUNC = , ST =GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST =The (DB Vintage) database has expired!The (SPD file Vintage) SPD File has expired!UNABLE TO VALIDATE BOUNDARY LICENSEUNABLE TO OPEN BOUNDARY FILEBOUNDARY FILE NOT FOUNDUNABLE TO VALIDATE USER BOUNDARY LICENSEUNABLE TO OPEN USER BND FILEUSER BND FILE NOT FOUND

Special Purpose Tax DistrictThe following table lists the output fields that contain Special Purpose Tax District (SPD) data. For moreinformation on special purpose tax districts, see AssignGeoTAXInfo on page 60. To include this datain the output, set GeoTAXOutputRecordType = S.


Table 35: Special Purpose Tax District Output Fields


Number of SPDs returned.NumberSPDsFound


SPDn.BoundaryBuffer.BufferRelation



P



I






B




SPDn.BoundaryBuffer.DistanceToBorder

SPD compiled date.SPDn.CompiledDate

3-digit district type code.SPDn.DistrictCode

SPD name.SPDn.DistrictName

SPD district number.SPDn.DistrictNumber

SPD effective date.SPDn.EffectiveDate

SPD update date.SPDn.UpdateDate

SPD version date.SPDn.VersionDate

Tax JurisdictionTax jurisdiction data contains information about the "place" where the address resides. A "place" is ageographic area defined on the basis of population criteria that vary by state; or, an area recognized assignificant because it is located in an incorporated municipality. Places are used to determine taxjurisdiction.

The following table lists the output fields that contain tax jurisdiction data. To include tax jurisdiction datain the output, set GeoTAXOutputRecordType = T.

Table 36: Tax Jurisdiction Output Fields


Indicates if the ZIP Code resides in the county.County.PostalCodeConfidence This field is always included in the output regardless of whether

or not you choose to include tax jurisdiction data in the output.Note:

ZIP Code not wholly contained in the county.N

ZIP Code wholly contained in the county.Y

Unknown if ZIP Code is wholly contained in the county ora match was not made at the ZIP Code level.

null

Only available for 5-digit ZIP Code matches, not for streetaddress matches.

Note:

The value in this field varies depending on the option you specified inthe option:

GeoTAXKey




If you specified , GeoTAXKey contains the proprietary codes used inADP/Taxware tax compliance software. You can use this code in yourADP/Taxware application to find out the tax rate for the jurisdiction.

If you specified , GeoTAXKey contains the proprietary Vertex® jurisdictioncode (comprised of a two-digit Vertex® state code, three-digit FIPScounty code, and four-digit Vertex® city code). You can use this codein your Vertex® application to find out the tax rate for the jurisdiction.

Return code denoting the level of match obtained against the Vertex orTaxware cross reference files.

GeoTAXKey.MatchCode

Exact match using five fields: FIPS state code, FIPS countycode, FIPS place code, ZIP Code, and FIPS place name.

E

Partial match using four fields: FIPS state code, FIPS countycode, FIPS place code, and ZIP Code.

P

Alternate match using two fields: ZIP Code, FIPS place name.This return code is available only when using Vertex.

A

Record is default coded based on valid state code. This returncode is available only when using Vertex.

N

No matching record found.null

A description of the value returned in the GeoTAXKey.MatchCode field.GeoTAXKey.MatchLevel

Exact match. See description inGeoTAXKey.MatchCode.

Exact

Partial match. See description inGeoTAXKey.MatchCode.

Partial

Alternate match. See description inGeoTAXKey.MatchCode.

Alternate

Record is default coded. See description inGeoTAXKey.MatchCode.

DefaultCode

No matching record found.NoMatch

Place class code. Place class codes are used to determine the propertaxing jurisdictions

Place.ClassCode

This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.

Note:

An identifier for a specific place. A "place" is a geographic area definedon the basis of population criteria that vary by state. Or, an area

Place.Code

recognized as significant because it is located in an incorporatedmunicipality.


Note:

Indicates whether the address is located in an incorporated orunincorporated place. A "place" is a geographic area defined on the

Place.IncorporatedFlag

basis of population criteria that vary by state. Or, an area recognizedas significant because it is located in an incorporated municipality.





Note:

Incorporated place code.Inc

Unincorporated place code.Uninc

Incorporation status unknown.Unknown

Last annexed date, in the format MM/YYYY, representing the monthand year of the most recent boundary change or the most recentavailable boundary information.

Place.LastAnnexedDate


Note:

Last updated date, in the format MM/YYYY, reflecting the month andyear when TomTom updated the database to reflect attribute (namechange, FIPS change, etc.) or boundary edits to the Place.

Place.LastUpdatedDate


Note:

Last verified date, in the format MM/YYYY, representing the month andyear that TomTom verified municipality change information.

Place.LastVerifiedDate


Note:

The name of the "place" where the address is located. A "place" is ageographic area defined on the basis of population criteria that vary by

Place.Name

state. Or, an area recognized as significant because it is located in anincorporated municipality.


Note:

Indicates if the ZIP Code resides in the place.Place.PostalCodeConfidence


Note:

ZIP Code not wholly contained in the place.N

ZIP Code wholly contained in the place.Y

Unknown if the ZIP Code is wholly contained in the placeor a match was not made at the ZIP Code level.

null

Only available for five-digit ZIP Code matches, not for street addressmatches.

User-Defined Boundary FileThe following table lists the output fields that contain data returned from user-defined boundary files. Toinclude this data in the output, set GeoTAXOutputRecordType = U.

AssignGeoTAXInfo can return up to 10 user-defined areas for each input address.Note:



Table 37: Output Fields for User-Defined Boundary Files


Number of user-defined polygons returned.NumberUserBoundariesFound

A description of the polygon.UserBoundaryn.BoundaryDescription

The ID of the polygon as specified in the user-definedboundary file.

UserBoundaryn.BoundaryID

Indicates where in the polygon the address resides in relationto the edge of the area.

UserBoundaryn.BufferRelation


The address is inside the polygon at a distance fromthe edge that is greater than the specified buffer width.

P


The address is inside the polygon but is close to theedge. This indicates that the address is in the buffer

I


The address is outside the polygon but is close to theedge. This indicates that the address is in the buffer

B



Indicates the distance from the address to the border of thepolygon. The distance is in the units specified by the option.

UserBoundaryn.DistanceToBorder

A supplemental ID as specified in the user-defined boundaryfile.

UserBoundaryn.SupplementalBoundaryID

CalculateDistanceCalculateDistance takes two sets of latitude/longitude coordinates as input, calculates the distancebetween the coordinates, and returns the distance between the two points.

CalculateDistance is part of the Enterprise Tax Module.

Resource URL

JSON endpoint:

http://server:port/rest/CalculateDistance/results.json

XML endpoint:

http://server:port/rest/CalculateDistance/results.xml





http://myserver:8080/rest/CalculateDistance/results.json?Data.SecondLatitude=41.881833&Option.LatLongFormat=Decimal&Data.SecondLongitude=-87.785587&Data.FirstLatitude=41.857333&Data.FirstLongitude=-88.325183


{"output_port": [{"Distance": "27.799","user_fields": []

}]}



http://myserver:8080/rest/CalculateDistance/results.xml?Data.SecondLatitude=41.881833&Option.LatLongFormat=Decimal&Data.SecondLongitude=-87.785587&Data.FirstLatitude=41.857333&Data.FirstLongitude=-88.325183


<ns2:xml.CalculateDistanceResponsexmlns:ns2="http://www.pb.com/spectrum/services/CalculateDistance">


<ns2:Distance>27.799</ns2:Distance><ns2:user_fields/>


</ns2:xml.CalculateDistanceResponse>

Request

Parameters for Input DataCalculateDistance takes latitude and longitude information as input.

Table 38: CalculateDistance Input Data


Latitude of the first point for which you want distance returned.Data.FirstLatitude

First latitude directional.Data.FirstLatitude.Directional

NorthN

SouthS

Longitude of the first point for which you want distance returned.Data.FirstLongitude

First longitude directional.Data.FirstLongitude.Directional

EastE

WestW




Latitude of the second point for which you want distance returned.Data.SecondLatitude

Second latitude directional.Data.SecondLatitude.Directional

NorthN

SouthS

Longitude of the second point for which you want distance returned.Data.SecondLongitude

Second longitude directional.Data.SecondLongitude.Directional

EastE

WestW


Table 39: Output Data and Format Options


Indicates the format of the input latitude/longitude. The options are:Option.LatLongFormat

For example 90 00 00N180 00 00W.DegMinSec

(090000000N180000000W). Default.PreZero

(090.000000N180.000000W)PreZeroDecimal

(90.000000-180.000000)Decimal

(90000000-180000000)DecimalAssumed

Indicates the measurement units returned for distance calculation:Option.ReturnUnits

• Miles• Km• Feet• Meters

ResponseCalculateDistance always returns the Confidence field to indicate the confidence in the output provided.

If CalculateDistance fails to process the data, it returns the fields Status, Status.Code, andStatus.Descriptions. These fields provide information on why CalculateDistance failed to process thedata. Some examples of failures are your license expired or you did not select any output record typesand fields for CalculateDistance to return. The following table provides the record-level qualifiers anddata outputs for CalculateDistance.



Table 40: CalculateDistance Output Fields


Distance between the two input coordinates in the units of measurementthat you specified.

Distance

Reports the success or failure of the match attempt:Status

Successnull

FailureF

Reason for failure or error. If Status = F, Status.Code = Failure.Status.Code

Description of the problem. If Status = F, Status.Description = Unableto compute distance.

Status.Description

GeoConfidence Module

GeoConfidenceSurfaceGeoConfidenceSurface returns geoconfidence polygons (also called surfaces) based on the quality ofthe geocode information generated by the Enterprise Geocoding Module. With the geoconfidencepolygons generated, you can then overlap this polygon with other spatial data to determine a risk orprobability.

This service is used by the GeoConfidence Module's FloodZoneAnalysis dataflow template.

GeoConfidence uses services provided by the Enterprise Geocoding and Location Intelligencemodules.

Note:

Resource URL

JSON endpoint:

http://server:port/rest/GeoConfidenceSurface/results.json

XML endpoint:

http://server:port/rest/GeoConfidenceSurface/results.xml

RequestThe input fields for GeoConfidenceSurface are the output fields returned by the GeoConfidence outputcategory of the Enterprise Geocoding Module. These fields are described below.


The value returned in this field indicates whichgeoconfidence surface type has been returned.

GeoConfidenceCode

Possible values are:




A geocode point for the intersectionof two streets.

INTERSECTION

An array of street segment pointsrepresenting the street segmentwhere the address is located.

ADDRESS

If the geocoder was able to match theaddress using point data, the point

POINT

geometry where the address islocated.

A geocode point for the ZIP centroid.POSTAL1

An array of points for all streetsegments in the ZIP + 2 in which theaddress is located.

POSTAL2

An array of points for street segmentsin the ZIP + 4 in which the address islocated.

POSTAL3

An error has occurred.ERROR

An array of latitude/longitude values that represent thestreet segment points.

StreetSegmentPoints

This field contains values only if theGeoConfidenceCode field returns a value ofADDRESS, POSTAL2, or POSTAL3.

Note:

The latitude of the centroid of the geoconfidencepolygon.

GeoConfidenceCentroidLatitude

The longitude of the centroid of the geoconfidencepolygon.

GeoConfidenceCentroidLongitude

ResponseThe GeoConfidenceSurface output field contains the geoconfidence polygon.


A geoconfidence polygon that represents the returned geometry.Geometry

Global Sentry Module

GlobalSentryThe GlobalSentry service attempts to match transactions against government provided watch lists thatcontain data from various countries. The GlobalSentry service relies on the Universal Name, Data



Normalization, and Advanced Matching modules. The service provides pre-configured and optimizedrules for matching against the normalized and consolidated watch lists. These lists include the following:

• Denied Persons List (United States)• Unverified List (BIS Red Flag) (United States)• Consolidated Financial Sanction Targets (Individuals and Entities) (United Kingdom/European Union)• Consolidated lists of persons, groups, and entities subject to EU financial sanctions (European Union)• DFAT Consolidated List (Australia)• OSFI Consolidated List (Individuals and Entities) (Canada)• Specially Designated Nationals, Terrorists, Narcotic Traffickers and other Blocked Persons List (UnitedStates)

• Statutorily Debarred Parties List (United States)

Matches are performed against Sanctioned Countries, Name, Address, ID Number and other informationsuch as DOB to provide an "Overall Risk Level Score" that allows your organization to make the rightchoice before making a decision to block a particular transaction and avoid false positive results.

The following steps describe how Global Sentry processes data:

1. The service first scans all required data in the transaction to identify countries that have beensanctioned. If a sanction country match has been identified, the transaction bypasses all othermatching criteria and is assigned the highest possible risk score.

2. If a sanctioned country match has not been identified, the service then attempts to match thetransaction against the Global Sentry database using the Global Sentry Name Check, Global SentryAddress Check or Global Sentry ID Number Check subflows.

3. The Global Sentry Name Check attempts to match individuals, entities and vessels. If a name matchis identified a Name Score is returned from the service.

4. The Global Sentry Address Check attempts to match addresses within a country. If an Address matchis identified an Address Score is returned from the service.

5. The Global Sentry ID Number Check attempts to match identification numbers such as Passport,National ID, SSN, Fiscal Code, and so on. If an ID Number match is identified an ID Number Scoreis returned from the service.

6. If a transaction is not identified as a Name, Address or ID Number match, the transaction record iswritten to the output and given an overall risk level score of zero.

7. If a transaction has been identified as a Name, Address or Identification Number match, the serviceattempts to match those transactions against the Global Sentry database using the Global SentryOther Data Check subflow.

8. The Global Sentry Other Data Check attempts to match the Place of Birth, Date of Birth, Nationalityor Citizenship. If a match is identified a Place of Birth Score, Date of Birth Score, Nationality Scoreor Citizenship Score is returned by the service.

9. Global Sentry assigns an Overall Risk Level score to each transaction. The score is a value between0 and 16 and is returned in the OverallRiskLevel field. In calculating the risk level, Global Sentrytakes into account what data was provided in the input record and which inputs, if any, matchedentries in the Global Sentry database. Generally, a higher value indicates a higher risk associatedwith the transaction.

Resource URL

JSON endpoint:

http://server:port/rest/GlobalSentry/results.json

XML endpoint:

http://server:port/rest/GlobalSentry/results.xml



http://myserver:8080/rest/GlobalSentry/results.json?Data.FirstName=Miguel&Data.LastName=Batista




Empty response elements have been removed from this example. Only the first response recordshown.

Note:

{"Output": [{"OverallRiskLevel": "10","SanctionedCountryIdentified": "No","Status": "S","FirstName": "Miguel","LastName": "Batista","PlaceOfBirth": "San Sebastian (Guipuzcoa) Spain","EntryID": "315","InputFilteredFirstName": "Miguel","InputFilteredLastName": "Batista","InputFirstName": "Miguel","InputLastName": "Batista","ListType": "DFAT Consolidated List","MatchKey1": "MGL","MatchKey2": "BTST","NameMatchIdentified": "Yes","NameProvided": "Yes","AddressProvided": "No","IDNumberProvided": "No","AddressMatchIdentified": "No","IDNumberMatchIdentified": "No","CitizenshipScore": "0","CitizenshipMatchIdentified": "No","CitizenshipUID": "","DOBScore": "0","DOBMatchIdentified": "No","NationalityScore": "0","NationalityMatchIdentified": "No","PlaceOfBirthScore": "0","PlaceOfBirthMatchIdentified": "No","CitizenshipProvided": "No","DOBProvided": "No","NationalityProvided": "No","PlaceOfBirthProvided": "No","WatchListFirstName": "Miguel","WatchListLastName": "ALBISU IRIARTE","NameScore": "100","user_fields": []

}]}



http://myserver:8080/rest/GlobalSentry/results.xml?Data.FirstName=Miguel&Data.LastName=Batista


Empty response elements have been removed from this example. Only the first response recordshown.

Note:

<xml.GlobalSentryResponsexmlns="http://www.pb.com/spectrum/services/GlobalSentry">

<Output><Row>

<OverallRiskLevel>10</OverallRiskLevel><SanctionedCountryIdentified>No</SanctionedCountryIdentified><Status>S</Status><FirstName>Miguel</FirstName>



<LastName>Batista</LastName><PlaceOfBirth>San Sebastian (Guipuzcoa) Spain</PlaceOfBirth><EntryID>315</EntryID><InputFilteredFirstName>Miguel</InputFilteredFirstName><InputFilteredLastName>Batista</InputFilteredLastName><InputFirstName>Miguel</InputFirstName><InputLastName>Batista</InputLastName><ListType>DFAT Consolidated List</ListType><MatchKey1>MGL</MatchKey1><MatchKey2>BTST</MatchKey2><NameMatchIdentified>Yes</NameMatchIdentified><NameProvided>Yes</NameProvided><AddressProvided>No</AddressProvided><IDNumberProvided>No</IDNumberProvided><AddressMatchIdentified>No</AddressMatchIdentified><IDNumberMatchIdentified>No</IDNumberMatchIdentified><CitizenshipScore>0</CitizenshipScore><CitizenshipMatchIdentified>No</CitizenshipMatchIdentified><DOBScore>0</DOBScore><DOBMatchIdentified>No</DOBMatchIdentified><NationalityScore>0</NationalityScore><NationalityMatchIdentified>No</NationalityMatchIdentified><PlaceOfBirthScore>0</PlaceOfBirthScore><PlaceOfBirthMatchIdentified>No</PlaceOfBirthMatchIdentified><CitizenshipProvided>No</CitizenshipProvided><DOBProvided>No</DOBProvided><NationalityProvided>No</NationalityProvided><PlaceOfBirthProvided>No</PlaceOfBirthProvided><WatchListFirstName>Miguel</WatchListFirstName><WatchListLastName>ALBISU IRIARTE</WatchListLastName><NameScore>100</NameScore><user_fields/>

</Row></Output>

</xml.GlobalSentryResponse>

Request


Table 41: Global Sentry Input Fields


Full name.Data.Name

Required if FirstName and LastName is not used.

First name or all name elements other than last name.Data.FirstName

Required if Name is not used.

Last name only.Data.LastName

Required if Name is not used.

The first address line.Data.AddressLine1

Recommended if provided.

The second address line.Data.AddressLine2


The third address line.Data.AddressLine3





Full country name.Data.Country

Required if address lines are used.

Identification Number, such as SSN, Passport, Visa, and so on.Data.IDNumber


Any place of birth data.Data.PlaceOfBirth


Date Of Birth, in the format of Year, Month, Day.Data.DOB


Full country name.Data.Citizenship


Full country name.Data.Nationality


Response

Table 42: Global Sentry Service Output


Name

Input Name from the original data source.InputName

Input Name with titles, suffixes and special characters removed fromthe original data source.

InputFilteredName

Name returned from database.Name

Input First Name from the original data source.InputFirstName

Input First Name with titles, suffixes and special characters removedfrom the original data source.

InputFilteredFirstName

First Name returned from database.FirstName

Input Last Name from the original data source.InputLastName

Input Last Name with titles, suffixes and special characters removedfrom the original data source.

InputFilteredLastName

Last Name returned from database.LastName

Name match score. 0 - 100.NameScore

Identifies Name was a match. Yes or NoNameMatchIdentified

Identifies Name was provided in the input data . Yes or NoNameProvided




Address

Input Address line from the original data source.InputAddressLine1

Address line returned from database.AddressLine1





Address match score. 0 - 100.AddressScore

Identifies Address was a match. Yes or No.AddressMatchIdentified

Identifies Address was provided in the input data. Yes or No.AddressProvided

Input Country from the original data source.InputCountry

Country returned from database.Country

ID Number

Input ID Number from the original data source.InputIDNumber

ID Number returned from database.IDNumber

ID Number match score. 0-100.IDNumberScore

Identifies ID Number was a match. Yes or No.IDMatchNumberIdentified

Identifies ID Number was provided in the input data. Yes or No.IDNumberProvided

Place of Birth

Input Place of Birth from the original data source.InputPlaceOfBirth

Place of Birth returned from database.PlaceOfBirth

Place of Birth match score. 0-100.PlaceOfBirthScore

Identifies Place of Birth was a match. Yes or No.PlaceOfBirthMatchIdentified

Identifies Place of Birth was provided in the input data. Yes or No.PlaceOfBirthProvided

Date of Birth

Input Date of Birth from the original data source.InputDOB

Date of Birth returned from database.DOB

Date of Birth match score. 0-100.DOBScore

Identifies Date of Birth was a match. Yes or No.DOBMatchIdentified

Identifies Date of Birth was provided in the input data. Yes or No.DOBProvided

Citizenship

Input Citizenship from the original data source.InputCitizenship




Citizenship returned from database.Citizenship

Citizenship match score. 0 to 100.CitizenshipScore

Identifies Citizenship was a match. Yes or No.CitizenshipMatchIdentified

Identifies Citizenship was provided in the input data. Yes or No.CitizenshipProvided

Nationality

Input Nationality from the original data source.InputNationality

Nationality returned from database.Nationality

Nationality match score. 0-100.NationalityScore

Identifies Nationality was a match. Yes or No.NationalityMatchIdentified

Identifies Nationality was provided in the input data. Yes or No.NationalityProvided

Government List Information

Entry ID that identifies a name, entity, vessel, address, id number, placeof birth, date of birth, citizenship or nationality. This is provided by eachgovt. agency.

EntryID

Name of list provided by the government agencies. SDN, EU, Bank OfEngland, Financial Institutions of Canada.

ListType

Risk Analysis

Risk score per match. 0-16. For more information, see Understandingthe Risk Analysis Score on page 96.

OverAllRiskLevel

Sanction country was identified as a match. Yes or No.SanctionCountryIdentified

Understanding the Risk Analysis ScoreRisk analysis processing assigns a point value to each of these inputs depending on whether the inputwas provided and whether it matched a record in the Global Sentry database. The risk analysis scoreis the sum of these point values. Points are assigned as shown in the following table.

Table 43: Risk Analysis Scoring Method

Did Not MatchMatchedNo Data ProvidedInput

040Name

021Address

021ID

021Date of Birth

021Place of Birth

021Citizenship

021Nationality



Generally, each input that matches the database is assigned 2 points; Name is the exception. A namematch scores 4 points. Name score is weighted higher following guidance from sources including OFAC,who indicate that a name match is more significant than other types of matches.

If an input is provided and does not match an entry on the database, it is assigned 0 points and has noeffect on the overall risk level. This is consistent with guidance stating that a name match, coupled witha significant amount of additional data which does not match that entry in the database, should not beconsidered a "hit" against a particular list.

If an input is not provided, it is assigned a score of 1. This has the effect of identifying as higher riskthose transactions where one or more inputs match the database, but there are some inputs which arenot available for matching. For these types of transactions, the true risk level cannot be accuratelycalculated because of the missing data. Guidance from agencies such as OFAC suggests that in thesecases you should attempt to obtain as much of the missing data as possible in order to return a moreaccurate assessment of the risk involved in the transaction.

Although higher scores indicate a higher risk transactions, the risk level alone is not always sufficient todetermine the appropriate action. This is because different combinations of matched, not-matched, andnot-provided inputs can result in the same score. To provide additional information to determine whetheran interdiction is appropriate, the Global Sentry service also returns two indicators for each of the seveninputs that are used in matching. These indicate whether the input was provided and whether the inputmatched the database. This allows you to perform additional analysis on transactions that are in themiddle of the risk spectrum to understand whether it is appropriate to report the transaction to the watchlist authority, to flag the transaction as needing additional input data for an accurate risk assessment, toapprove the transaction, or to take some other action.

Customizing the Global Sentry ServiceGlobal Sentry deploys five dataflow templates that you can modify in Enterprise Designer. Each dataflowconsists of various components that were installed from the Spectrum™ Technology Platform, UniversalName, Data Normalization and Advanced Matching modules.

The names of the dataflows are:

• Global Sentry• Global Sentry Name Check• Global Sentry Address Check• Global Sentry ID Number Check• Global Sentry Other Data Check• Global Sentry Batch• Global Sentry Name Check Batch• Global Sentry Address Check Batch• Global Sentry ID Number Check Batch• Global Sentry Other Data Check Batch

Location Intelligence Module

Where to Find Documentation?The Location Intelligence Module provides spatial services that allows you to determine relationshipsbetween locations, areas, or points of interest and other business data, and visually show theserelationships on a map. These services include:

• Geometry• Feature• Mapping• MapTiling



• Named Resource• Web Feature Service• Web Map Service• Catalog Service for the Web

To learn about the Location Intelligence Module services, see the Spectrum Spatial Guide onsupport.pb.com.

Universal Addressing Module

AutoCompleteLoqateAutoCompleteLoqate offers real-time entry of address data for fast, accurate results. Users are returnedinstant results based on each character entered into the form, ensuring only accurate data is enteredinto the database.

Resource URL

JSON endpoint:

http://server:port/rest/AutoCompleteLoqate/results.json

XML endpoint:

http://server:port/rest/AutoCompleteLoqate/results.xml



http://myserver:8080/rest/AutoCompleteLoqate/results.json?Data.AddressLine1=1+Global


To make the example easier to read, empty response elements have been removed and onlythe first three address matches are shown.

Note:

{"output_port": [{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Vw","FirmName": "Map Info","City": "Troy","StateProvince": "NY","PostalCode": "12180-8399","Country": "United States","PostalCode.AddOn": "8399","user_fields": []

},{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Pl","City": "Glendale","StateProvince": "AZ","PostalCode": "85306-3216","Country": "United States","PostalCode.AddOn": "3216",



http://support.pb.com/ekip/index?page=product_content&cat=SC_SPECTRUM_TECHNOLOGY_PLATFORM

"user_fields": []},

{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Dr","City": "Olive Hill","StateProvince": "KY","PostalCode": "41164-6739","Country": "United States","PostalCode.AddOn": "6739","user_fields": []

}]}



http://myserver:8080/rest/AutoCompleteLoqate/results.xml?Data.AddressLine1=1+Global


To make the example easier to read, empty response elements have been removed and onlythe first three address matches are shown.

Note:

<ns2:xml.AutoCompleteLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/AutoCompleteLoqate">


<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Vw</ns2:AddressLine1><ns2:FirmName>Map Info</ns2:FirmName><ns2:City>Troy</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>12180-8399</ns2:PostalCode><ns2:PostalCode.AddOn>8399</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>


<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Pl</ns2:AddressLine1><ns2:City>Glendale</ns2:City><ns2:StateProvince>AZ</ns2:StateProvince><ns2:PostalCode>85306-3216</ns2:PostalCode><ns2:PostalCode.AddOn>3216</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>


<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Dr</ns2:AddressLine1><ns2:City>Olive Hill</ns2:City><ns2:StateProvince>KY</ns2:StateProvince><ns2:PostalCode>41164-6739</ns2:PostalCode><ns2:PostalCode.AddOn>6739</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>


</ns2:xml.AutoCompleteLoqateResponse>



Request

Parameters for Input DataThe following table lists the input for AutoCompleteLoqate.

Table 44: Input Format





The fourth address line.Data.AddressLine4

The city name.Data.City

The country code or name, in any of the following formats:Data.Country

• 2-digit ISO country code• 3-digit UPU Country code• English country name

For a list of ISO codes, see Country ISO Codes and Module Supporton page 234.

The company or firm name.Data.FirmName

The postal code for the address.Data.PostalCode

The state or province.Data.StateProvince


Table 45: AutoCompleteLoqate Options


Specifies the database to be used for address processing. Onlydatabases that have been defined in the Database Resources panelin the Management Console are available.

Option.Database.Loqate


The output in mixed case (default). For example:

123 Main StMytown FL 12345

M

The output in upper case. For example:

123 MAIN STMYTOWN FL 12345

U




Specifies the default country. You should specify the country wheremost of your addresses reside. For example, if most of the addresses

Option.HomeCountry

you process are in Canada, specify Canada. The valid country namesare:

Afghanistan, Albania, Algeria, American Somoa, Andorra, Angola,Anguilla, Antigua And Barbuda, Argentina, Armenia, Aruba, Australia,Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus,Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, Bosnia AndHerzegovina, Botswana, Brazil, British Virgin Islands, BruneiDarussalam, Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central African Republic, Chad,Chile, China, Colombia, Comoros Islands, Congo, Cook Islands, CostaRica, Cote D'Ivoire, Croatia, Cuba, Cyprus, Czech Republic, DemocraticRepublic Of Congo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea, Eritrea,Estonia, Ethiopia, Falkland Islands, Faroe Islands, Federated States OfMicronesia, Fiji, Finland, France, French Guiana, Gabon, Gambia,Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe,Guam, Guatemala, Guinea, Guinea Bissau, Guyana, Haiti, Holy See,Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan, Kenya,Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho,Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Macedonia,Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Marshall Islands,Martinique, Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru,Nepal, Netherlands Antilles, New Caledonia, New Zealand, Nicaragua,Niger, Nigeria, Niue, Norway, Oman, Pakistan, Palau, Panama, PapuaNew Guinea, Paraguay, Peru, Philippines, Pitcairn Islands, Poland,Portugal, Puerto Rico, Qatar, Republic Of Georgia, Republic Of Korea,Republic Of Singapore, Reunion, Romania, Russia, Rwanda, SaintHelena, Saint Kitts And Nevis, Saint Lucia, Saint Pierre And Miquelon,Saint Vincent And The Grenadines, Samoa, San Marino, Sao TomeAnd Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka,Sudan, Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti, Taiwan,Tajikistan, Tanzania, Thailand, The Netherlands, Togo, Tonga, TrinidadAnd Tobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan, TurksAnd Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna, Yemen,Yugoslavia, Zambia, Zimbabwe

Specifies the alphabet or script in which the output should be returned.This option is bi-directional and generally takes place from Native toLatin and Latin to Native.

Option.OutputScript

Do not perform transliteration and provide output inthe same script as the input (default).

Input

Output in the native script for the selected countrywherever possible.

Native

Use English values.Latn




The maximum number of addresses that AutoCompleteLoqate shouldreturn. The default is 10.


Specifies how you want Spectrum Technology Platform to respond whena data license error occurs.

Option.FailJobOnDataLicenseError

Fail the entire job if a data license error occurs.Fail the job

Fail the record(s) for which the data license erroroccurs and continue processing.

Fail the record

ResponseThe output from AutoCompleteLoqate is optional and corresponds directly to the fields you selected inthe Output Fields section of the AutoCompleteLoqate Options dialog box.

Table 46: AutoCompleteLoqate Output


The first address line.AddressLine1

The second address line.AddressLine2

The third address line.AddressLine3

The fourth address line.AddressLine4

The city name.City

The three-character ISO 3116-1 Alpha-3 code for the country. For a listof ISO codes, see Country ISO Codes and Module Support on page234.

Country

The firm name.FirmName

The ending house number for the range in which the candidate address'shouse number falls.

HouseNumber

The postal code.PostalCode

The last four digits of the ZIP + 4® Code.PostalCode.AddOn

Indicates which address coder processed the address.ProcessedBy

The Loqate coder processed the address.LOQATE

The state or province abbreviation.StateProvince


Successnull

FailureF

The reason for failure, if there is one.Status.Code

• DisabledCoder• RequestFailed




• NoLookupAddressFound

A description of the problem, if there is one.Status.Description

The input address matched only oneaddress in the database.

Did not returnmultiples

AutoCompleteLoqate returns data only ifmultiple possible matches were found.

AutoCompleteLoqate is not able to processthe partial address.

Not able to look up theaddress pattern

AutoCompleteLoqate Sample Web ApplicationYou can access a sample web application that demonstrates the Auto Complete Loqate functionality.When you enter a partial address, this application makes a call to the Auto Complete Loqate REST webservice, which returns a suggested address.

Prior to using this feature, you must add an Auto Complete Loqate database resource inManagement Console and save the database resource in the Auto Complete Loqate Service.

Note:

1. Be sure the Spectrum™ Technology Platform server is running.2. Open a web browser and go to: http://<servername>:<port>/autocomplete. For example,

if your server is named "myserver" and it uses the default HTTP port 8080, you would go to:http://myserver:8080/autocomplete.

This site is best viewed in Internet Explorer 8.0 or later, Chrome, or Mozilla Firefox.Note:

3. When the login screen appears, enter "guest" as the user name and leave the password field blank.4. Press OK.5. Select a country from the drop-down list.6. Begin typing your address in any of the fields provided.7. Select from the list of suggested addresses.8. To begin a new call, click Reset, which will clear the fields you used in your previous call.

GetCandidateAddressesGetCandidateAddresses returns a list of addresses that are consideredmatches for a given input address.GetCandidateAddresses returns candidate addresses only if the input addressmatchesmultiple addressesin the postal database. If the input address matches only one address in the postal database, then noaddress data is returned.

For addresses outside the U.S. and Canada, you may notice inconsistent results between the multiplematches returned by ValidateAddress and the results for that same address returned byGetCandidateAddresses. If you experience inconsistent results, it is likely because you set theperformance tuning setting in ValidateAddress to a value other than 100. To obtain consistent resultsbetween GetCandidateAddresses and ValidateAddress, set the performance tuning option to 100.

By default, GetCandidateAddresses does not match to individual house numbers. Rather, it useshouse number ranges for each street. After GetCandidateAddresses has determined the street

Note:

name, city name, state/province name, and postal code, it checks to make sure the input housenumber falls within one of the ranges of house numbers given for the matched street name. Thesame type of logic applies to unit numbers. If you want to determine that an individual housenumber is valid, you should use the ValidateAddress Delivery Point Validation (DPV) processingoption. DPV processing is only available for U.S. addresses.



The Canadian coder contains a reverse lookup routine that takes as input a specific postal code andreturns the street information stored in the database for that postal code. To use this function enternothing but a Canadian postal code in the PostalCode field. See the second example to view the returnfrom a sample postal code.

GetCandidateAddresses is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/GetCandidateAddresses/results.json

XML endpoint:

http://server:port/rest/GetCandidateAddresses/results.xml



http://myserver:8080/rest/GetCandidateAddresses/results.json?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY


{"output_port": [{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "60","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10002","Country": "USA","PostalCode.AddOn": "0001","user_fields": []

},{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "9","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10008","Country": "USA","PostalCode.AddOn": "0001","user_fields": []

},



{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "60","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10009","Country": "USA","PostalCode.AddOn": "0001","user_fields": []

}]}



http://myserver:8080/rest/GetCandidateAddresses/results.xml?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY


<ns2:xml.GetCandidateAddressesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCandidateAddresses">


<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:RecordType>PostOfficeBox</ns2:RecordType><ns2:MatchLevel>A</ns2:MatchLevel><ns2:AddressLine1>PO Box 1</ns2:AddressLine1><ns2:HouseNumberLow>1</ns2:HouseNumberLow><ns2:HouseNumberHigh>60</ns2:HouseNumberHigh><ns2:HouseNumberParity>B</ns2:HouseNumberParity><ns2:UnitNumberLow/><ns2:UnitNumberHigh/><ns2:UnitNumberParity></ns2:UnitNumberParity><ns2:FirmName/><ns2:City>New York</ns2:City><ns2:USUrbanName/><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>10002</ns2:PostalCode><ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country><ns2:user_fields/>


<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:RecordType>PostOfficeBox</ns2:RecordType><ns2:MatchLevel>A</ns2:MatchLevel><ns2:AddressLine1>PO Box 1</ns2:AddressLine1><ns2:HouseNumberLow>1</ns2:HouseNumberLow><ns2:HouseNumberHigh>9</ns2:HouseNumberHigh><ns2:HouseNumberParity>B</ns2:HouseNumberParity><ns2:UnitNumberLow/><ns2:UnitNumberHigh/><ns2:UnitNumberParity></ns2:UnitNumberParity><ns2:FirmName/><ns2:City>New York</ns2:City><ns2:USUrbanName/><ns2:StateProvince>NY</ns2:StateProvince>



<ns2:PostalCode>10008</ns2:PostalCode><ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country><ns2:user_fields/>


</ns2:xml.GetCandidateAddressesResponse>

Request

Parameters for Input DataThe following table lists the input for GetCandidateAddresses.






Does not apply to U.S. and Canadian addresses.


Does not apply to U.S. and Canadian addresses.

The fifth address line.Data.AddressLine5

Applies only to U.K. addresses. May contain street name, unit number,building number, and so on.



For U.S. addresses only, you may put the state in the City field insteadof the StateProvince field.

The postal code for the address. For U.S. addresses this is the ZIPCode™ in one of the following formats:

Data.PostalCode

9999999999-9999A9A9A9A9A 9A99999 999

For Canadian addresses you can complete just this field andhave candidate address data returned. For other countries,AddressLine1 and AddressLine2 must also be completed.

Note:


• 2-digit ISO country code• 3-digit UPU Country code• English country name• French country name




• German country name• Spanish country name



U.S. address urbanization name. Used primarily for Puerto Ricoaddresses.

Data.USUrbanName


Table 48: GetCandidateAddresses Options


Specifies whether or not to process U.S. addresses. If youenable U.S. address processing GetCandidateAddresses will

Option.PerformUSProcessing

attempt to retrieve candidate addresses for U.S. addresses.If you disable U.S. address processing, U.S. addresses willfail, meaning they are returned with an "F" in the Status outputfield. The output field Status.Code will say "DisabledCoder."If you are not licensed for U.S. address processing you mustdisable U.S. address processing in order for your jobs tocomplete successfully, regardless of whether or not theycontain U.S. addresses.

You must have a valid license for U.S. addressprocessing to successfully process U.S. addresses.

Note:

If you enable U.S. address processing but are notlicensed for this feature, or your license has expired,you will receive an error.

Yes, process U.S. addresses (default).Y

No, do not process U.S. addresses.N

Specifies the database to be used for U.S. addressprocessing. Only databases that have been defined in the

Option.Database.US

US Database Resources panel in theManagement Consoleare available.

Specifies whether or not to process Canadian addresses. Ifyou enable Canadian address processing

Option.PerformCanadianProcessing

GetCandidateAddresses will attempt to retrieve candidateaddresses for Canadian addresses. If you disable Canadianaddress processing, Canadian addresses will fail, meaningthey are returned with an "F" in the Status output field. Theoutput field Status.Code will say "DisabledCoder." If you arenot licensed for Canadian address processing you mustdisable Canadian address processing in order for your jobsto complete successfully, regardless of whether or not theycontain Canadian addresses.




You must have a valid license for Canadian addressprocessing to successfully process Canadian

Note:

addresses. If you enable Canadian addressprocessing but are not licensed for this feature, oryour license has expired, you will receive an error.

Yes, process Canadian addresses (default).Y

No, do not process Canadian addresses.N

Specifies the database to be used for Canadian addressprocessing. Only databases that have been defined in the

Option.Database.Canada

Canadian Database Resources panel in the ManagementConsole are available.

Specifies whether or not to process international addresses(addresses outside the U.S. and Canada). If you enable

Option.PerformInternationalProcessing

international address processing GetCandidateAddresseswill attempt to retrieve candidate addresses for internationaladdresses. If you disable international address processing,international addresses will fail, meaning they are returnedwith an "F" in the Status output field. The output fieldStatus.Code will say "DisabledCoder." If you are not licensedfor international address processing you must disableinternational address processing in order for your jobs tocomplete successfully, regardless of whether or not theycontain international addresses.

You must have a valid license for internationaladdress processing to successfully process

Note:

international addresses. If you enable internationaladdress processing but are not licensed for thisfeature, or your license has expired, you will receivean error.

Yes, process international addresses (default).Y

No, do not process international addresses.N

Specifies the database to be used for international addressprocessing. Only databases that have been defined in the

Option.Database.International

International Database Resources panel in theManagementConsole are available.


The output is in mixed case (default). For example:


M

The output is in upper case. For example:


U




The maximum number of candidate addresses thatGetCandidateAddresses should return. The default is 10. Themaximum is 10.


For U.S. addresses, specifies whether or not to return theUSPS®-approved abbreviation for the city, if there is one. The

Option.OutputShortCityName

USPS® provides abbreviations for city names that are 14characters long or longer. City abbreviations are 13 charactersor less and can be used when there is limited space on themailing label. If there is no short city name for the city, thenthe full city name is returned.

Yes, return the short city name.Y

No, do not return the short city name.N

(U.S. addresses only). Controls whetherGetCandidateAddresses should return a street match or a

Option.DualAddressLogic

PO Box/Rural Route/Highway Contract match when theaddress contains both street and PO Box/RuralRoute/Highway Contract information. For more information,see About Dual Address Logic on page 138.

(Default) USPS® CASS™ regulations determine theaddress returned based on the following order ofpriority:

N

1. PO Box2. Firm3. Highrise4. Street5. Rural Route6. General Delivery

Return a street match, regardless of the address line.S

Return a PO Box match, regardless of the addressline.

P

The strictness of the street name match (U.S. addressesonly).

Option.StreetMatchingStrictness

The input street name must match the databaseexactly.

E

The matching algorithm is "tight."T

The matching algorithm is "medium" (default).M

The matching algorithm is "loose".L

The strictness of the firm name match (U.S. addresses only).Option.FirmMatchingStrictness

The input firm name must match the databaseexactly.

E



The matching algorithm is "loose."L




The strictness of the directional match.Option.DirectionalMatchingStrictness

The input directional must match the databaseexactly.

E




Specifies whether or not to perform Enhanced Street Matching(ESM). ESM applies extra matching logic with additional data

Option.PerformESM

to any input address that is not matched through the regularaddress validation process. ESM applies to U.S. addressesonly.

Yes, perform ESM processing.Y

No, do not perform ESM processing (default).N

Specifies whether ValidateAddress will search address linesfor the city, state/province, and postal code.

Option.AddressLineSearchOnFail

This option enables ValidateAddress to search theAddressLine input fields for the city, state/province, postalcode, and country when the address cannot bematched usingthe values in the City, StateProvince, and PostalCode inputfields.

Consider enabling this option if your input addresses havethe city, state/province, and postal code information in theAddressLine fields.

Consider disabling this option if your input addresses use theCity, State/Province and PostalCode fields. If you enable thisoption and these fields are used, there is an increasedpossibility that ValidateAddress will fail to correct values inthese fields (for example a misspelled city name).

Yes, search the address line fields (default).Y

No, do not search the AddressLine fields.N

ResponseGetCandidateAddresses returns the following output.

Table 49: GetCandidateAddresses Output









For U.K. addresses only. If the address was validated, the fifth line ofthe validated and standardized address. If the address could not bevalidated, the fifth line of the input address without any changes.

AddressLine5

The city name.City


Country


The ending house number for the range in which the candidate address'shouse number falls.

HouseNumberHigh

The beginning house number for the range in which the candidateaddress's house number falls.

HouseNumberLow

Indicates the numbering scheme for the house numbers betweenHouseNumberLow and HouseNumberHigh, as follows:

HouseNumberParity

Only even valuesE

Only odd valuesO

BothB

For addresses outside the U.S. and Canada, identifies the match levelfor the candidate address. U.S. and Canadian addresses are always"A." One of the following:

MatchLevel

The candidate matches the input address at the street level.A

The candidate matches the input address at thestate/province level.

B

The postal code. In the U.S. this is the ZIP Code™.PostalCode

The last four digits of the ZIP + 4® Code. U.S. addresses only.PostalCode.AddOn

The type of address record, as defined by U.S. and Canadian postalauthorities (U.S. and Canadian addresses only):

RecordType

• FirmRecord• GeneralDelivery• HighRise• PostOfficeBox• RRHighwayContract• Normal

Code indicating the "default" match:RecordType.Default

The address matches a default record.Y

The address does not match a default record.null



Successnull




FailureF

The reason for failure, if there is one. There is only one possible value:Status.Code

• DisabledCoder• RequestFailed

A description of the problem, if there is one.Status.Description

The input address matched onlyone address in the database.

Did not return multiples

GetCandidateAddresses onlyreturns data if multiple possiblematches were found.

The input address matched morethan one address in the databasebut no addresses were returned.

Number of candidates is notgreater than 1

This value will appear ifStatus.Code=DisabledCoder.

PerformUSProcessing disabled


PerformCanadianProcessingdisabled


PerformInternationalProcessingdisabled

The ending unit number for the range in which the candidate address'sunit number falls.

UnitNumberHigh

The beginning unit number for the range in which the candidate address'sunit number falls.

UnitNumberLow

Indicates the numbering scheme for the unit numbers betweenUnitNumberLow and UnitNumberHigh, as follows:

UnitNumberParity

Only even valuesE

Only odd valuesO

BothB

The validated city urbanization name. Urbanization names are usedprimarily for Puerto Rico addresses.

USUrbanName

GetCandidateAddressesLoqateGetCandidateAddressesLoqate returns a list of addresses that are considered matches for a given inputaddress. GetCandidateAddressesLoqate returns candidate addresses only if the input address matchesmultiple addresses in the postal database. If the input address matches only one address in the postaldatabase, then no address data is returned. The Country input field is required; if this field is blank, nooutput will be returned.

By default, GetCandidateAddressesLoqate does not match to individual house numbers. Rather,it uses house number ranges for each street. After GetCandidateAddressesLoqate has determined

Note:

the street name, city name, state/province name, and postal code, it checks to make sure theinput house number falls within one of the ranges of house numbers given for the matched streetname. The same type of logic applies to unit numbers.



GetCandidateAddressesLoqate is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/GetCandidateAddressesLoqate/results.json

XML endpoint:

http://server:port/rest/GetCandidateAddressesLoqate/results.xml



http://myserver:8080/rest/GetCandidateAddressesLoqate/results.json?Data.AddressLine1=PO+Box+1&Data.City=New+York&Data.StateProvince=NY



Note:

{"output_port": [{"ProcessedBy": "LOQATE","AddressLine1": "PO Box 101","City": "New York Mls","StateProvince": "NY","PostalCode": "13417-0101","Country": "USA","PostalCode.AddOn": "0101","user_fields": []

},{"ProcessedBy": "LOQATE","AddressLine1": "PO Box 102","City": "New York Mls","StateProvince": "NY","PostalCode": "13417-0102","Country": "USA","PostalCode.AddOn": "0102","user_fields": []

}]}



http://myserver:8080/rest/GetCandidateAddressesLoqate/results.xml?Data.AddressLine1=PO+Box+1&Data.City=New+York&Data.StateProvince=NY



Note:

<ns2:xml.GetCandidateAddressesLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCandidateAddressesLoqate">




<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:AddressLine1>PO Box 101</ns2:AddressLine1><ns2:City>New York Mls</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>13417-0101</ns2:PostalCode><ns2:PostalCode.AddOn>0101</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country>


<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:AddressLine1>PO Box 102</ns2:AddressLine1><ns2:City>New York Mls</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>13417-0102</ns2:PostalCode><ns2:PostalCode.AddOn>0102</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country>


</ns2:xml.GetCandidateAddressesLoqateResponse>

Request

Parameters for Input DataThe following table lists the input for GetCandidateAddressesLoqate.











This field is required. If this field is blank, no output will bereturned.

Note:


The postal code for the address. For U.S. addresses this is the ZIPCode™ in one of the following formats:

Data.PostalCode


For U.S. addresses only, you may put the state in the City field insteadof the StateProvince field.




Table 51: GetCandidateAddressesLoqate Options


Specifies the database to be used for address processing. Onlydatabases that have been defined in the Management Console areavailable.



The output is in mixed case (default). For example:


M

The output is in upper case. For example:


U

Specifies the default country. You should specify the country wheremost of your addresses reside. For example, if most of the addresses

Option.HomeCountry

you process are in Canada, specify Canada.GetCandidateAddressLoqate uses the country you specify to attemptvalidation when it cannot determine the country from the StateProvince,PostalCode, and Country address fields. The valid country names are:

Afghanistan, Albania, Algeria, American Somoa, Andorra, Angola,Anguilla, Antigua And Barbuda, Argentina, Armenia, Aruba, Australia,Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus,Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, Bosnia AndHerzegovina, Botswana, Brazil, British Virgin Islands, BruneiDarussalam, Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central African Republic, Chad,Chile, China, Colombia, Comoros Islands, Congo, Cook Islands, CostaRica, Cote D'Ivoire, Croatia, Cuba, Cyprus, Czech Republic, DemocraticRepublic Of Congo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea, Eritrea,Estonia, Ethiopia, Falkland Islands, Faroe Islands, Federated States OfMicronesia, Fiji, Finland, France, French Guiana, Gabon, Gambia,Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe,Guam, Guatemala, Guinea, Guinea Bissau, Guyana, Haiti, Holy See,Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan, Kenya,Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho,Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Macedonia,Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Marshall Islands,Martinique, Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru,Nepal, Netherlands Antilles, New Caledonia, New Zealand, Nicaragua,Niger, Nigeria, Niue, Norway, Oman, Pakistan, Palau, Panama, PapuaNew Guinea, Paraguay, Peru, Philippines, Pitcairn Islands, Poland,Portugal, Puerto Rico, Qatar, Republic Of Georgia, Republic Of Korea,Republic Of Singapore, Reunion, Romania, Russia, Rwanda, SaintHelena, Saint Kitts And Nevis, Saint Lucia, Saint Pierre And Miquelon,




Saint Vincent And The Grenadines, Samoa, San Marino, Sao TomeAnd Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka,Sudan, Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti, Taiwan,Tajikistan, Tanzania, Thailand, The Netherlands, Togo, Tonga, TrinidadAnd Tobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan, TurksAnd Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna, Yemen,Yugoslavia, Zambia, Zimbabwe

The maximum number of candidate addresses thatGetCandidateAddressesLoqate should return. The default is 10. Themaximum is 99.


ResponseGetCandidateAddressesLoqate returns the following output.

Table 52: GetCandidateAddressesLoqate Output






The city name.City


Country


The postal code. In the U.S. this is the ZIP Code™.PostalCode

The last four digits of the ZIP + 4® Code. U.S. addresses only.PostalCode.AddOn





Successnull

FailureF

The reason for failure, if there is one. There is only one possible value:Status.Code

• RequestFailed




A description of the problem, if there is one. There is only one possiblevalue:

Status.Description

The input address matched only one address inthe database. GetCandidateAddressesLoqate

Did not returnmultiples

only returns data if multiple possible matches werefound.

GetCityStateProvinceGetCityStateProvince returns a city and state/province for a given input postal code.

GetCityStateProvince works with U.S. and Canadian addresses only.Note:

GetCityStateProvince is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/GetCityStateProvince/results.json

XML endpoint:

http://server:port/rest/GetCityStateProvince/results.xml



http://myserver:8080/rest/GetCityStateProvince/results.json?Data.PostalCode=12180


{"output_port": [{"ProcessedBy": "USA","PostalCode": "12180","City": "TROY","StateProvince": "NY","Country": "USA","City.Type": "P","user_fields": []

}]}



http://myserver:8080/rest/GetCityStateProvince/results.xml?Data.PostalCode=12180


<ns2:xml.GetCityStateProvinceResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCityStateProvince">

<ns2:output_port>



<ns2:Result><ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>12180</ns2:PostalCode><ns2:City>TROY</ns2:City><ns2:City.Type>P</ns2:City.Type><ns2:StateProvince>NY</ns2:StateProvince><ns2:Country>USA</ns2:Country><ns2:user_fields/>


</ns2:xml.GetCityStateProvinceResponse>

Request

Parameters for Input DataThe following table shows the input fields.

Table 53: GetCityStateProvince Input


A U.S. ZIP Code™ or Canadian postal code in one of the followingformats:

Data.PostalCode

99999

99999-9999

A9A9A9

A9A 9A9


Table 54: GetCityStateProvince Options

DescriptionParameter Name

Specifies whether or not to process U.S. addresses. If you enable U.S.address processing GetCityStateProvince will attempt to return the state


for U.S. addresses. If you disable U.S. address processing, U.S.addresses will fail, meaning they are returned with an "F" in the Statusoutput field. The output field Status.Code will say "DisabledCoder." Ifyou are not licensed for U.S. address processing you must disable U.S.address processing in order for your jobs to complete successfully,regardless of whether or not they contain U.S. addresses.

You must have a valid license for U.S. address processing tosuccessfully process U.S. addresses. If you enable U.S. address

Note:

processing but are not licensed for this feature, or your licensehas expired, you will receive an error.

Yes, process U.S. addresses (default).Y




DescriptionParameter Name

Specifies the database to be used for U.S. address processing. Onlydatabases that have been defined in the US Database Resourcespanel in the Management Console are available.

Option.Database.US

Specifies whether or not to process Canadian addresses. If you enableCanadian address processing GetCityStateProvince will attempt to


return the province for Canadian addresses. If you disable Canadianaddress processing, Canadian addresses will fail, meaning they arereturned with an "F" in the Status output field. The output fieldStatus.Code will say "DisabledCoder." If you are not licensed forCanadian address processing you must disable Canadian addressprocessing in order for your jobs to complete successfully, regardlessof whether or not they contain Canadian addresses.

You must have a valid license for Canadian address processingto successfully process Canadian addresses. If you enable

Note:

Canadian address processing but are not licensed for thisfeature, or your license has expired, you will receive an error.

Yes, process Canadian addresses (default).Y


Specifies the database to be used for Canadian address processing.Only databases that have been defined in the Canadian DatabaseResources panel in the Management Console are available.


Specifies whether or not to include non-mailing city names in the output.A non-mailing city name is an alternate name for the primary city name.For example, Hollywood is a non-mailing city name for Los Angeles.

Option.OutputVanityCity

Yes, include non-mailing city names.Y

No, do not include non-mailing city names (default).N

Specifies the maximum number of city-state/province pairs to return.The default value is 10.


ResponseGetCityStateProvince returns the matching city and state/province for the input postal code as well asa code to indicate the success or failure of the match attempt. If more than one city/state or city/provincematches the input postal code, multiple output records are returned.

Table 55: GetCityStateProvince Output


The matched city name.City

The USPS® standardized city name type (U.S. addresses only).City.Type

Vanity (non-mailing) city name.V

Primary. The city name is the primary mailing city name.P




Secondary. The city name is an alternate city name but isacceptable. A city can have multiple secondary city names.

S

The input postal code.PostalCode

Indicates which address coder processed the address. One of thefollowing:

ProcessedBy

The U.S. address coder processed the address.USA

The Canadian address coder processed the address.CAN



Successnull

FailureF

The reason for failure, if there is one. The only valid value is:Status.Code

• DisabledCoder• UnrecognizedPostalCode

The description of the failure. The valid values are:Status.Description

This value will appear ifStatus.Code=UnrecognizedPostalCode.

Postal code not found


PerformUSProcessingdisabled



GetCityStateProvinceLoqateGetCityStateProvinceLoqate returns a city and state/province for a given input postal code.

This stage is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/GetCityStateProvinceLoqate/results.json

XML endpoint:

http://server:port/rest/GetCityStateProvinceLoqate/results.xml



http://myserver:8080/rest/GetCityStateProvinceLoqate/results.json?Data.Country=USA&Data.PostalCode=60510




{"output_port": [{"ProcessedBy": "LOQATE","PostalCode": "60510","City": "Batavia","StateProvince": "IL","Country": "United States","Status": "","Status.Code": "","Status.Description": "","user_fields": []

}]}



http://myserver:8080/rest/GetCityStateProvinceLoqate/results.xml?Data.Country=USA&Data.PostalCode=60510


<ns2:xml.GetCityStateProvinceLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCityStateProvinceLoqate">


<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:PostalCode>60510</ns2:PostalCode><ns2:City>Batavia</ns2:City><ns2:StateProvince>IL</ns2:StateProvince><ns2:Country>United States</ns2:Country><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>


</ns2:xml.GetCityStateProvinceLoqateResponse>

Request

Parameters for Input DataThe following table shows the input fields.

Table 56: GetCityStateProvinceLoqate Input





The postal code for the address.Data.PostalCode



Options

Table 57: GetCityStateProvinceLoqate Options

Description / Valid Values

Specifies the database to be used for address processing. Onlydatabases that have been defined in the Database Resources panelin the Management Console are available.

The maximum number of addresses that GetCityStateProvinceLoqateshould return. The default is 10.

Specifies the alphabet or script in which the output should be returned.This option is bi-directional and generally takes place from Native toLatin and Latin to Native.

Do not perform transliteration and provide output in the same scriptas the input (default).

Output in the native script for the selected country wherever possible.

Use English values.

Specifies how you want Spectrum Technology Platform to respondwhen a data license error occurs.

Fail the entire job if a data license error occurs.Fail the job

Fail the record(s) for which the data licenseerror occurs and continue processing.

Fail the record

ResponseGetCityStateProvinceLoqate returns the matching city and state/province for the input postal code aswell as a code to indicate the success or failure of the match attempt. If more than one city/state orcity/province matches the input postal code, multiple output records are returned.

Table 58: GetCityStateProvinceLoqate Output


The matched city name.City

The country in the format determined by what you selected in:Country

• ISO Code• UPU Code• English

The input postal code.PostalCode








Successnull

FailureF

The reason for failure, if there is one. The only valid value is:Status.Code

• UnrecognizedPostalCode

The description of the failure. The only valid value is:Status.Description

This value will appear ifStatus.Code=UnrecognizedPostalCode.

Postal code not found

GetPostalCodesGetPostalCodes allows you to look up the postal codes for a particular city. The service takes a city,state, and country as input and returns the postal codes for that city. The input must be exactly correctin order to return postal codes.

GetPostalCodes only works with U.S. addresses.Note:

GetPostalCodes is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/GetPostalCodes/results.json

XML endpoint:

http://server:port/rest/GetPostalCodes/results.xml



http://myserver:8080/rest/GetPostalCodes/results.json?Data.City=Holland&Data.StateProvince=MI


{"output_port": [{"ProcessedBy": "USA","PostalCode": "49422","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []

},{"ProcessedBy": "USA","PostalCode": "49423","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []



},{"ProcessedBy": "USA","PostalCode": "49424","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []

}]}



http://myserver:8080/rest/GetPostalCodes/results.xml?Data.City=Holland&Data.StateProvince=MI


<ns2:xml.GetPostalCodesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetPostalCodes">


<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>49422</ns2:PostalCode><ns2:City.Type></ns2:City.Type><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>

</ns2:Result><ns2:Result>


</ns2:Result><ns2:Result>



</ns2:xml.GetPostalCodesResponse>

Request

Parameters for Input DataGetPostalCodes takes a city, state/province, and country as input.



Table 59: GetPostalCodes Input


The city whose postal codes you want to look up.Data.City

You may put the city and state in the City field. If you do this, you mustleave the StateProvince field blank.

The total length of the City and StateProvince fields cannot exceed 100characters.

The state or province of the city whose postal codes you want to lookup.

Data.StateProvince

You may also put the state in the City field instead of the StateProvincefield.

The total length of the City and StateProvince fields cannot exceed 100characters.

The country code or name of the city whose postal codes you want tolook up. The only valid value is US.

Data.Country


Table 60: GetPostalCodes Options


Specifies the database to be used for postal code look-ups. Onlydatabases that have been defined in the US Database Resources panelin the Management Console are available.

Option.Database.US

Specifies whether or not to include postal codes for the city's non-mailingcity names. A non-mailing city name is an alternate name for the primary

Option.IncludeVanityCity

city name. For example, Hollywood is a non-mailing city name for LosAngeles.

Yes, include postal codes for non-mailing city names.Y

No, do not include postal codes for non-mailing city names(default).

N

Specifies whether or not to return the city type in the output. If enabled,the city type is returned in the City.Type field.

Option.OutputCityType

Yes, include the city type in the output.Y

No, do not include the city type in the output (default).N

ResponseGetPostalCodes returns the postal codes for a specified city. Each postal code is returned in a separaterecord along with the data listed in the following table.



Table 61: GetPostalCodes Output


The USPS® city type (U.S. addresses only). The city type is determinedby looking at the ZIP Code and the city name. For example, the city

City.Type

Lanham MD has the postal codes 20703, 20706, and 20784. Lanhamis the primary city in 20703 and 20706 but is a vanity city in 20784.

This field column is only populated if . The possible values are:

Vanity (non-mailing) city name.V

Primary. The city name is the primary mailing city name.P

Secondary. The city name is an alternate city name but isacceptable. A city can have multiple secondary city names.

S

A postal code in the specified city.PostalCode

Because this service only works for U.S. addresses, ProcessedBy willalways contain one value: USA.

ProcessedBy


Successnull

FailureF

Reason for failure, if there is one. One of the following:Status.Code

• CountryNotSupported• UnableToLookup

Description of failure.Status.Description

• Input country is not supported• Input city was blank• Input city & state / province was blank, or no match found• City-state mismatch (different spelling found, or city-state was a vanityname and vanity matching was not allowed, or city-state did not matchZIP Code)

ValidateAddressValidateAddress standardizes and validates addresses using postal authority address data.ValidateAddress can correct information and format the address using the format preferred by theapplicable postal authority. It also adds missing postal information, such as postal codes, city names,state/province names, and more.

ValidateAddress also returns result indicators about validation attempts, such as whether or notValidateAddress validated the address, the level of confidence in the returned address, the reason forfailure if the address could not be validated, and more.

During address matching and standardization, ValidateAddress separates address lines into componentsand compares them to the contents of the Universal Addressing Module databases. If a match is found,the input address is standardized to the database information. If no database match is found,ValidateAddress optionally formats the input addresses. The formatting process attempts to structurethe address lines according to the conventions of the appropriate postal authority.

ValidateAddress is part of the Universal Addressing Module.



Resource URL

JSON endpoint:

http://server:port/rest/ValidateAddress/results.json

XML endpoint:

http://server:port/rest/ValidateAddress/results.xml



http://myserver:8080/rest/ValidateAddress/results.json?Data.AddressLine1=1825+Kramer+Ln&Data.PostalCode=78758


{"output_port": [{"Confidence": "100","RecordType": "Normal","CountryLevel": "A","ProcessedBy": "USA","MatchScore": "0","AddressLine1": "1825 Kramer Ln","City": "Austin","StateProvince": "TX","PostalCode": "78758-4260","Country": "United States Of America","PostalCode.Base": "78758","PostalCode.AddOn": "4260","user_fields": []

}]}



http://myserver:8080/rest/ValidateAddress/results.xml?Data.AddressLine1=1825+Kramer+Ln&Data.PostalCode=78758


<ns2:xml.ValidateAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddress">


<ns2:Confidence>93</ns2:Confidence><ns2:RecordType>Normal</ns2:RecordType><ns2:CountryLevel>A</ns2:CountryLevel><ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:MatchScore>0</ns2:MatchScore><ns2:AddressLine1>1825 Kramer Ln</ns2:AddressLine1><ns2:City>Austin</ns2:City><ns2:StateProvince>TX</ns2:StateProvince><ns2:PostalCode>78758-4260</ns2:PostalCode><ns2:PostalCode.Base>78758</ns2:PostalCode.Base><ns2:PostalCode.AddOn>4260</ns2:PostalCode.AddOn><ns2:Country>United States Of America</ns2:Country><ns2:user_fields/>


</ns2:xml.ValidateAddressResponse>



Request

Parameters for Input DataValidateAddress takes an address as input. All addresses use this format regardless of the address'scountry. SeeAddress Line Processing for U.S. Addresses on page 129 for important information abouthow address line data is processed for U.S. addresses.



The first address line.String[50]

Data.AddressLine1

The second address line.String[50]

Data.AddressLine2

The third address line.String[50]

Data.AddressLine3

Does not apply to Canadian addresses.

The fourth address line.String[50]

Data.AddressLine5

Does not apply to Canadian addresses.

The fifth address line.String[50]

Data.AddressLine5

Applies only to U.K. addresses. May contain street name, unitnumber, building number, and so on.


Data.City

For U.S. addresses only, you may put the city, state, and ZIPCode™ in the City field. If you do this, you must leave theStateProvince and PostalCode fields blank.

The state or province.String[50]

Data.StateProvince

For U.S. addresses only, you may put the state in the Cityfield instead of the StateProvince field.

The postal code for the address in one of the followingformats:

String[10]

Data.PostalCode

9999999999-9999A9A9A9A9A 9A99999 999

For U.S. addresses only, you may put the ZIP Code™ in theCity field.

For U.S. addresses only, if the city/state/ZIP Code™ is in thePostalCode field, ValidateAddress may parse the data andsuccessfully process the address. For best results, put thisdata in the appropriate fields (City, StateProvince, andPostalCode).

The country code or name, in any of the following formats:String[50]

Data.Country

• Two-character ISO 3116-1 Alpha-2 country code




• Three-character ISO 3116-1 Alpha-3 country code• English country name• French country name• German country name• Spanish country name

For a list of ISO codes, seeCountry ISO Codes and ModuleSupport on page 234.

The company or firm name.String[50]

Data.FirmName

The U.S. address urbanization name. This is used primarilyfor Puerto Rico addresses.

String[50]

Data.USUrbanName

If this mailpiece uses a generic barcode, specify yourUSPS®-assigned customer ID in this field. The

String [9]Data.CustomerID

ValidateAddress generic barcode is used for mailpieces thatuse the OneCode ACS® service.

For Canadian addresses only, indicates whether the addressis in English or French, if the optionOption.CanFrenchFormat=T is used.

StringData.CanLanguage

If this field is blank, the address is formatted in English. If thefield contains any non-blank value, the address is formattedin French. Note that addresses in Quebec are alwaysformatted in French regardless of the value in this field.

Address Line Processing for U.S. Addresses

The input fields AddressLine1 through AddressLine4 are handled differently for U.S. addresses dependingon whether the firm name extraction or urbanization code extraction options are enabled. If either ofthese options is enabled, ValidateAddress will look at the data in all four fields to validate the addressand extract the requested data (firm name and/or urbanization code). If neither of these options is enabled,ValidateAddress uses only the first two non-blank address line fields in its validation attempt. The datain the other address line fields is returned in the output field AdditionalInputData. For example,

AddressLine1: A1 Calle AAddressLine2:AddressLine3: URB AlamarAddressLine4: Pitney Bowes Software

In this address, if either firm name extraction or urbanization code extraction were enabled,ValidateAddress would examine all four address lines. If neither firm name extraction nor urbanizationcode extraction were enabled, ValidateAddress would examine AddressLine1 and AddressLine3 (thefirst two non-blank address lines) and attempt to validate the address using that data; the data inAddressLine4 would be returned in the output field AdditionalInputData.

Parameters for OptionsOutput Data Options

The following table lists the options that control the type of information returned by ValidateAddress.Some of these options can be overridden for Canadian addresses. For more information, see CanadianAddress Options on page 148.



Table 63: Output Data Options


Type of output record. For more than one, provide a list.Option.OutputRecordType

Returns 1 to 4 lines of address data plus city, state,postal code, firm name, and urbanization name

A

information. Each address line represents an actualline of the address as it would appear on an envelope.For more information, see Response on page 156. IfValidateAddress could validate the address, theaddress lines contain the standardized address.Whenaddresses are standardized, punctuation is removed,directionals are abbreviated, street suffixes areabbreviated, and address elements are corrected. IfValidateAddress could not validate the address, theaddress lines contain the address as it appeared inthe input ("pass through" data). Non-validatedaddresses are always included as pass through datain the address line fields even if you do not specifyOutputRecordType=A.

Parsed address elements. Each part of the address,such as house number, street name, street suffix,

E

directionals, and so on is returned in a separate field.For more information, seeParsed Address ElementsOutput on page 157. Note that if you specify "E" andspecify OutputFormattedOnFail=Y, the parsedaddress elements will contain the input address foraddresses that could not be validated.

Parsed input. This option returns the input address inparsed form regardless of whether or not

I

ValidateAddress is able to validate the address. Eachpart of the input address, such as house number,street name, street suffix, directionals, and so on isreturned in a separate field. Parsed input (value "I")differs from the combination ofOutputRecordType=Eand OutputFormattedOnFail=Y in that "I" returns allinput address in parsed form, not just input that couldnot be validated. For more information, see ParsedInput on page 159.

Postal data. Output addresses contain additional datafor each validated address. For more information, seePostal Data Output on page 160.

P

Do not return any address data or postal data.Blank

Specifies whether to include field-level result indicators.Field-level result indicators describe how ValidateAddress

Option.OutputFieldLevelReturnCodes

handled each address element. Field-level result indicatorsare returned in the qualifier "Result". For example, thefield-level result indicator for HouseNumber is contained inHouseNumber.Result. For a complete listing of resultindicator output fields, see Field-Level Result Indicators onpage 165.




No, do not output field-level return codes (default).N

Yes, output field-level return codes.Y

Specifies whether to return a formatted address when anaddress cannot be validated. The address is formatted using

Option.OutputFormattedOnFail

the preferred address format for the address's country. If thisoption is not selected, the output address fields are blankwhen ValidateAddress cannot validate the address.

This option applies only to U.S. and Canadianaddresses. Formatted data will not be returned forany other address.

Note:


Yes, format failed addresses.Y

Formatted addresses are returned using the format specifiedby the OutputRecordType option. Note that if you specifyOutputRecordType=E, the parsed address elements willcontain the parsed, validated address for addresses that couldbe validated. If the address could not be validated the parsedaddress elements will contain the input address in parsedform. If you always want the output to contain the inputaddress in parsed form, regardless of whether or notValidateAddress could validate the address, specifyOutputRecordType=I.

Formatted addresses are returned using the format specifiedby the Option.OutputRecordType option. Note that if youspecify Option.OutputRecordType=E, the parsed addresselements will contain the parsed, validated address foraddresses that could be validated. If the address could notbe validated the parsed address elements will contain theinput address in parsed form. If you always want the outputto contain the input address in parsed form, regardless ofwhether or not ValidateAddress could validate the address,specify Option.OutputRecordType=I.

Formatted addresses are returned using the format specifiedby the Include a standard address, Include address lineelements, and Include postal information check boxes.Note that if you select Include address line elements, theparsed address elements will contain the parsed, validatedaddress for addresses that could be validated. If the addresscould not be validated the parsed address elements willcontain the input address in parsed form. If you always wantthe output to contain the input address in parsed form,regardless of whether or not ValidateAddress could validatethe address, select Include standardized input addresselements.

If you specify Y, you must specify "A" and/or "E" forOutputRecordType.

If you specify Y, you must specify "A" and/or "E" forOption.OutputRecordType.




If you check this option, you must select Include a standardaddress and/or Include address line elements.

For U.S. addresses only, specifies whether or not to use astreet's alias in the output. A street alias is an alternate name

Option.OutputStreetNameAlias

for a street and typically applies only to a specific range ofaddresses on the street. If you do not allow street aliases inthe output then the street's "base" name will appear in theoutput regardless of whether or not there is an alias for thestreet. The base name is the name that applies to the entirestreet.

No, do not return street name aliases in the output.N

Yes, return street name aliases in the output if thereis an alias for the street (default).

Y

For U.S. addresses only, specifies how to handle street namealiases used in the input. A street alias is an alternate name

Option.OutputStreetNameAlias

for a street and typically applies only to a specific range ofaddresses on the street.

If you enable this option, street name aliases used in the inputwill appear in the output. If you do not enable this option,street name aliases in the input will be converted to the basestreet name in the output, with the following exceptions:

• If a preferred alias is used in input the preferred alias willalways be used in output.

• Changed aliases used in input are always converted to thebase street name in output.

This is one of three options that control how ValidateAddresshandles street name aliases. The other two areOption.OutputPreferredAlias andOption.OutputAbbreviatedAlias.

If Option.OutputAbbreviatedAlias is enabled, theabbreviated alias will always appear in the output

Note:

even if you have Option.OutputStreetNameAliasdisabled.

No, do not return street name aliases in the output.N

Yes, return street name aliases in the output if theinput street name is an alias (default).

Y

Specifies whether to return a formatted version of the addressas it would be printed on a physical mailpiece. Each line of

Option.OutputAddressBlocks

the address is returned in a separate address block field.There can be up to nine address block output fields:AddressBlock1 through AddressBlock9.

For example, this input address:

AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600City: Lanham




StateProvince: MDPostalCode: 20706

Results in this address block output:

AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882AddressBlock3: UNITED STATES OF AMERICA

ValidateAddress formats the address into address blocksusing postal authority standards. The country name is returnedusing the Universal Postal Union country name. Note that theoption Option.OutputCountryFormat does not affect thecountry name in the address block, it only affects the namereturned in the Country output field.

For addresses outside the U.S. and Canada, ifValidateAddress is unable to validate the address, no addressblocks are returned. For addresses in the U.S. and Canada,address blocks are returned even if validation fails.

No, do not return address blocks. Default.N

Yes, return address blocks.Y

Obtaining Congressional Districts

ValidateAddress can determine the U.S. congressional district for an address.

To obtain congressional districts, Option.OutputRecordType must contain P. For more informationon Option.OutputRecordType, see Output Data Options on page 129.

Table 64: Congressional District Output


Congressional district number. If the address is a non-state address (forexample Puerto Rico or Washington D.C.) this field is blank.

USCongressionalDistrict

Obtaining County Names

ValidateAddress can determine the county where a particular address is located and return the countyname.

County names are available for U.S. addresses only.Note:

To obtain county names, Option.OutputRecordType must contain P. For more information onOption.OutputRecordType, see Output Data Options on page 129.

Table 65: County Name Output


County nameUSCountyName

Obtaining FIPS County Numbers



Federal Information Processing Standards (FIPS) county numbers are numbers that identify each countyin a state. Note that these numbers are only unique at the state level, not the national level. For moreinformation, see http://www.census.gov.

FIPS county numbers are available for U.S. addresses only.Note:

To obtain FIPS county numbers, Option.OutputRecordType must contain P. For more informationon Option.OutputRecordType, see Output Data Options on page 129.

Table 66: FIPS County Number Output


FIPS (Federal Information Processing Standards) county numberUSFIPSCountyNumber

Obtaining Carrier Route Codes

Carrier route codes are unique identifiers assigned to each mail carrier who delivers mail, allowing uniqueidentification of each U.S. delivery route. ValidateAddress can return the code that represents anaddressee's carrier route.

Carrier route codes are available for U.S. addresses only.Note:

To obtain carrier route codes, Option.OutputRecordType must contain P. For more information onOption.OutputRecordType, see Output Data Options on page 129.

Table 67: Carrier Route Code Output


Carrier route codeUSCarrierRouteCode

Creating Delivery Point Barcodes

A Delivery Point Barcode (DPBC) is a POSTNET™ barcode representation of the address. It consists of62 bars with beginning and ending frame bars and five bars each for the ZIP + 4® Code, a value calculatedbased on the street address number, and a correction digit. The DPBC allows automated sortation ofletter mail to the carrier level in walk sequence. ValidateAddress generates the data you need to assemblea DPBC.

Delivery Point Barcodes are available for U.S. addresses only. For more information on DeliveryPoint Barcodes, see http://www.usps.com.

Note:

To generate the data needed to assemble a DPBC, Option.OutputRecordType must contain P. Formore information on Option.OutputRecordType, see Output Data Options on page 129.

Table 68: Delivery Point Barcode Output


The delivery point portion of the delivery point barcode.PostalBarCode

Check-digit portion of the 11-digit delivery point barcode.USBCCheckDigit

To assemble a DPBC you concatenate the values found in the ValidateAddress output as follows:

PostalCode.Base + PostalCode.Addon + PostalBarcode + USBCCheckDigit



http://www.census.gov

http://www.usps.com

For example, if you have the following:

• PostalCode.Base = 49423• PostalCode.Addon = 4506• PostalBarcode = 29• USBCCheckDigit = 2

The assembled barcode would be:

494234506292

Default Options

The following table lists the options that control the format and processing of addresses. These are called"default options" because by default the apply to all addresses. Some of these options can be overriddenfor Canadian addresses. For more information, see Canadian Address Options on page 148.

Table 69: Default Options





M



U

Specifies whether to use separators (spaces or hyphens) inZIP™ Codes or Canadian postal codes.


For example, a ZIP + 4® Code with the separator would be20706-1844 and without the separator it would be 207061844.A Canadian postal code with the separator would be P5E"1S7and without the separator it would be P5E1S7.

Yes, use separator (default).Y

No, do not use separator.N

Spaces are used in Canadian postal codes andhyphens in U.S. ZIP + 4® Codes.

Note:

Specifies whether or not to return multinational characters,including diacritical marks such as umlauts or accents. (Notsupported for U.S. addresses).

Option.OutputMultinationalCharacters

No, do not use multinational characters in the output(default). Only standard ASCII characters is returned.

N

Yes, use multinational characters in the output.Y

Indicates whether or not to return multiple address for thoseinput addresses that have more than one possible match.

Option.KeepMultimatch

Yes, return multiple matches (default).Y

No, do not return multiple matches.N




For more information, see Returning Multiple Matches onpage 139.

Specifies where to place secondary address information forU.S. addresses. Secondary address information refers to

Option.StandardAddressFormat

apartment numbers, suite numbers, and similar designators.For example, in this address the secondary addressinformation is "Apt 10E" and the primary address informationis "424 Washington Blvd".

Apt 10E424 Washington BlvdSpringfield MI 49423

Place both primary and secondary address informationin AddressLine1 (default).

C

Place the primary address information in AddressLine1and the secondary address information inAddressLine2.

S

Place both primary and secondary address informationin AddressLine1 and place dropped information from

D

dual addresses in AddressLine2. A dual address is anaddress that contains both street information and POBox/Rural Route/Highway Contract information. Formore information, see About Dual Address Logic onpage 138.

Specifies how to format city names that have short city nameor non-mailing city name alternatives. Applies to U.S. andCanadian addresses.

Option.OutputShortCityName

Returns the USPS®-approved abbreviation for the city,if there is one. The USPS® provides abbreviations for

Y

city names that are 14 characters long or longer. Cityabbreviations are 13 characters or less and can be usedwhen there is limited space on the mailing label. If thereis no short city name for the city, then the full city nameis returned.

Returns the long city name (default).N

Returns the abbreviated city name only if an abbreviatedcity name is used in the input address. If the input

S

address does not use a short city name, either the longor short city name could be returned, depending onUSPS® regulations for the particular city. Select thisoption if you are performing a CASS™ test.

Output the non-mailing city name (the vanity name) ifthe input city name is a non-mailing city name. For

V

example, "Hollywood" is a non-mailing city name for"Los Angeles". If you do not select this option and theinput city name is a non-mailing city name the longversion of the mailing city is returned.




Specifies the format to use for the country name returned inthe Country output field. For example, if you select English,


the country name "Deutschland" would be returned as"Germany".

Use English country names (default).E

Use Spanish country names.S

Use French country names.F

Use German country names.G

Use two-letter ISO abbreviation for the countriesinstead of country names.

I

Use Universal Postal Union abbreviation for thecountries instead of country names.

U

Specifies the default country. You should specify the countrywhere most of your addresses reside. For example, if most

Option.HomeCountry

of the addresses you process are in Canada, specify Canada.ValidateAddress uses the country you specify to attemptvalidation when it cannot determine the country from theStateProvince, PostalCode, and Country address fields. Thevalid country names are:

Afghanistan, Albania, Algeria, American Somoa, Andorra,Angola, Anguilla, Antigua And Barbuda, Argentina, Armenia,Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain,Bangladesh, Barbados, Belarus, Belgium, Belize, Benin,Bermuda, Bhutan, Bolivia, Bosnia And Herzegovina,Botswana, Brazil, British Virgin Islands, Brunei Darussalam,Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central AfricanRepublic, Chad, Chile, China, Colombia, Comoros Islands,Congo, Cook Islands, Costa Rica, Cote D'Ivoire, Croatia,Cuba, Cyprus, Czech Republic, Democratic Republic OfCongo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea,Eritrea, Estonia, Ethiopia, Falkland Islands, Faroe Islands,Federated States Of Micronesia, Fiji, Finland, France, FrenchGuiana, Gabon, Gambia, Germany, Ghana, Gibraltar, Greece,Greenland, Grenada, Guadeloupe, Guam, Guatemala,Guinea, Guinea Bissau, Guyana, Haiti, Holy See, Honduras,Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan,Kenya, Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia,Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania,Luxembourg, Macau, Macedonia, Madagascar, Malawi,Malaysia, Maldives, Mali, Malta, Marshall Islands, Martinique,Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar,Namibia, Nauru, Nepal, Netherlands Antilles, New Caledonia,New Zealand, Nicaragua, Niger, Nigeria, Niue, Norway, Oman,Pakistan, Palau, Panama, Papua New Guinea, Paraguay,Peru, Philippines, Pitcairn Islands, Poland, Portugal, PuertoRico, Qatar, Republic Of Georgia, Republic Of Korea,




Republic Of Singapore, Reunion, Romania, Russia, Rwanda,Saint Helena, Saint Kitts And Nevis, Saint Lucia, Saint PierreAnd Miquelon, Saint Vincent And The Grenadines, Samoa,San Marino, Sao Tome And Principe, Saudi Arabia, Senegal,Seychelles, Sierra Leone, Slovakia, Slovenia, SolomonIslands, Somalia, South Africa, Spain, Sri Lanka, Sudan,Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti,Taiwan, Tajikistan, Tanzania, Thailand, The Netherlands,Togo, Tonga, Trinidad And Tobago, Tristan Da Cunha,Tunisia, Turkey, Turkmenistan, Turks And Caicos Islands,Tuvalu, Uganda, Ukraine, United Arab Emirates, UnitedKingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna,Yemen, Yugoslavia, Zambia, Zimbabwe

Indicates how ValidateAddress should return a match ifmultiple non-blank address lines are present or multiple

Option.DualAddressLogic

address types are on the same address line (U.S. addressesonly).

(Default) USPS® CASS™ regulations determine theaddress returned based on the following order ofpriority:

N

1. PO Box2. Firm3. Highrise4. Street5. Rural Route6. General Delivery

Return a street match, regardless of the address line.S

Return a PO Box match, regardless of the addressline.

P

For more information, see About Dual Address Logic onpage 138.

About Dual Address Logic

For U.S. addresses only, the Option.DualAddressLogic option controls whether ValidateAddress shouldreturn a street match or a PO Box/Rural Route/Highway Contract match when the address contains bothstreet and PO Box/Rural Route/Highway Contract information in the same address line.

The Option.DualAddressLogic option has no effect if the street information is in a different addressline input field than the PO Box/Rural Route/Highway Contract information.

Note:

For example, given the following input address:

AddressLine1: 401 N Main St Apt 1 POB 1City: KempStateProvince: TXPostalCode: 75143

ValidateAddress would return one of the following:

• If Option.DualAddressLogic is set to either N or P, ValidateAddress returns the following:



AddressLine1: PO Box 1City: KempStateProvince: TXPostalCode: 75143-0001

• If Option.DualAddressLogic is set to S, ValidateAddress returns the following:

AddressLine1: 401 N Main St Apt 1City: KempStateProvince: TXPostalCode: 75143-4806

The address data that is not used to standardize the address can be returned in one of two places:

• AddressLine2—The address information not used to standardize the address is returned in theAddressLine2 field if you specify Option.StandardAddressFormat=D. For more information on thisoption, see Default Options on page 135. For example, if you choose to return a street match for dualaddresses,

AddressLine1: 401 N Main St Apt 1AddressLine2: PO Box 1City: KempStateProvince: TXPostalCode: 75143-0001

• AdditionalInputData—If you do not specify Option.StandardAddressFormat=D then the addressinformation not used to standardize the address is returned in the AdditionalInputData field. For moreinformation on this option, see Default Options on page 135. For example, if you choose to return astreet match for dual addresses,

AddressLine1: 401 N Main St Apt 1City: KempStateProvince: TXPostalCode: 75143-0001AdditionalInputData: PO Box 1

Address information that is dropped can be retrieved by setting the Option.StandardAddressFormatoption to D. For more information, see .

Returning Multiple Matches

If ValidateAddress finds multiple address in the postal database that are possible matches for the inputaddress, you can have ValidateAddress return the possible matches. For example, the following addressmatches multiple addresses in the U.S. postal database:

PO BOX 1New York, NY

Options

To return multiple matches, use the options described in the following table.

Table 70: Multiple Match Option


Indicates whether or not to return multiple address for those inputaddresses that have more than one possible match.







A number between 1 and 10 that indicates the maximum number ofaddresses to return.



The difference between Option.Keepmultimatch=N andOption.KeepMultimatch=Y/Option.MaximumResults=1 is that

Note:

a multiple match will return a failure ifOption.KeepMultimatch=N, whereas amultiple match will returnone record if Option.KeepMultimatch=Y andOption.MaximumResults=1.

To identify which output addresses are candidate addresses, you mustspecify a value of Y for Option.OutputFieldLevelReturnCodes. When


you do this, records that are candidate addresses will have one or more"M" values in the field-level result indicators.

Output

When you choose to return multiple matches, the addresses are returned in the address format youspecify. For information on specifying address format, seeOutput Data Options on page 129. To identifywhich records are the candidate addresses, look for multiple "M" values in the field-level result indicators.For more information, see Field-Level Result Indicators on page 165.

U.S. Address Options


Specifies whether to process U.S. addresses. If you enable U.S. addressprocessing ValidateAddress will attempt to validate U.S. addresses. If


you disable U.S. address processing, U.S. addresses will fail, meaningthey are returned with an "F" in the Status output field. The output fieldStatus.Code will say "DisabledCoder." If you are not licensed for U.S.address processing you must disable U.S. address processing in orderfor your jobs to complete successfully, regardless of whether or not theycontain U.S. addresses.

You must have a valid license for U.S. address processing tosuccessfully process U.S. addresses. If you enable U.S. address

Note:

processing but are not licensed for this feature, or your licensehas expired, you will receive an error.


Yes, process U.S. addresses. Default.Y

Specifies which database to use for validating U.S. addresses. Onlydatabases that have been defined in the US Database Resources panelin the Management Console are available.

Option.Database.US

Enhanced Line of Travel (eLOT) processing assigns a Line of Travelsequence code to your addresses. Note that ValidateAddress does not

Option.PerformLOT

sort into eLOT sequence but it provides data (the Line of Travelsequence code) that allows you to sort addresses into eLOT sequence.

To perform eLOT processing you must have the eLOT databaseinstalled.




No, do not perform Line of Travel Processing. Default.N

Yes, perform Line of Travel processing.Y

For a listing of the output fields returned by this option, see EnhancedLine of Travel Output on page 174.

Residential Delivery Indicator (RDI™) processing checks if an addressis a residential address (not a business address). To perform RDI™

processing, you must have the RDI™ database installed.

Option.PerformRDI

If you enable both DPV® and RDI™ processing, RDI™ information is onlyreturned if the address is a valid delivery point. If DPV® does not validatethe address no RDI™ data is returned.

No, do not perform Residential Delivery Indicator processing.Default.

N

Yes, perform Residential Delivery Indicator processing.Y

Enhanced Street Matching (ESM) applies additional matching logic tocorrect misspelled or complex street names and obtain a match. ESM

Option.PerformESM

enables ValidateAddress to validate more addresses but it reducesperformance. You cannot perform ESM when ASM is enabled.

No, do not perform enhanced street matching. Default.N

Yes, perform enhanced street matching.Y

All Street Matching (ASM) applies ESM processing as well as additionalmatching logic to correct errors in street names and obtain a match. It

Option.PerformASM

is effective at matching streets when the first letter of the street isincorrect. ASM provides the best address validation but reducesperformance.

No, do not perform all street matching.N

Yes, perform all street matching. Default.Y

Delivery Point Validation (DPV®) validates that a specific address exists,as opposed to validating that a specific address is within a range of valid

Option.PerformDPV

addresses. CMRA processing checks if an address is for a mailboxrented from a private company, referred to as a Commercial MailReceiving Agent (CMRA).

To perform DPV and CMRA processing, you must have the DPVdatabase installed. The DPV database contains both DPV and CMRAdata.

No, do not perform Delivery Point Validation or CMRAprocessing. Default.

N

Yes, performDelivery Point Validation and CMRA processing.Y

For a listing of the output fields returned by this option, see DPV andCMRA Output on page 175.

The USPS® Locatable Address Conversion System (LACS) allows youto correct addresses that have changed as a result of a rural route

Option.PerformLACSLink

address converting to street-style address, a PO Box renumbering, ora street-style address changing. When enabled, LACSLink processing




is attempted for addresses that could not be validated, or addresseswere validated and flagged for LACSLink conversion.

To perform LACSLink processing, you must have the LACSLink databaseinstalled.

No, do not attempt LACSLink conversion. Default.N

Yes, attempt LACSLink conversion.Y

For a listing of the output fields returned by this option, see LACSLinkOutput on page 174

The EarlyWarning System (EWS) uses the USPS® EWSFile to validateaddresses that are not in the ZIP + 4® database.

Option.PerformEWS

To perform EWS processing, youmust have the EWS database installed.

If an input address matches an address in the EWS file, ValidateAddresswill return the following record-level result indicators:

• Status="F"• Status.Code="EWSFailure"• Status.Description="Address found in EWS table"

No, do not perform EWS processing. Default.N

Yes, perform EWS processing.Y

Specifies whether to extract the firm name from AddressLine1 throughAddressLine4 and place it in the FirmName output field. This option

Option.ExtractFirm

works in cases where the input record's FirmName field is blank andthere is more than one address line.

Yes, extract the firm name.Y

No, do not extract the firm name. Default.N

To identify firm names in address lines, ValidateAddress scans theaddress lines for keywords and patterns that help it identify which fieldsare address lines and which are FirmName lines. Since this is donebased on patterns, ValidateAddress maymisidentify fields. The followingtips can help ensure optimal firm extraction:

• If possible, place the primary address elements in AddressLine1, thesecondary elements in AddressLine2, Urbanization in AddressLine3,and firm in AddressLine4. If the address has no urbanization code,then place the firm name in AddressLine3 and leave AddressLine4blank. For example,

AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes SoftwareAddressLine4: <blank>

• When you define just two address lines, AddressLine2 is assigned tothe secondary address most of the time. If you want to increase thechance that ValidateAddress will treat AddressLine2 as a firm name,put the firm name in AddressLine3 and leave AddressLine2 blank.




• Numerics in a firm name (such as the "1" in "1 Stop Software") willincrease the likelihood that ValidateAddress will treat the field as anaddress line.

Here are some examples of firm name extraction:

• In this example, AddressLine2 would get extracted into the FirmNameoutput field

FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600AddressLine2: International Goose Feathers inc.

• In this example, AddressLine3 would get extracted into the FirmNameoutput field.

FirmName: <blank>AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes Software

• In this example, AddressLine3 would be placed in theAdditionalInputData output field. The firm name would not be extractedbecause the FirmName input field is not blank.

FirmName: International Goose Feathers Inc.AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes Software

• In this example, no firm name would be extracted because there isonly one non-blank address line, which is always treated as theprimary address element.

FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600

• In this example, AddressLine2 would be treated as a secondaryaddress element because the numeral "1" causes ValidateAddressto treat that field as a secondary address element.

FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600AddressLine2: Pitney Bowes Software

Specifies whether to extract the urbanization name from AddressLine1through AddressLine4 and place it in the USUrbanName output field.

Option.ExtractUrb

This option works in cases where the input record's USUrbanName fieldis blank and there is more than one address line.

Yes, extract the urbanization name.Y

No, do not extract the urbanization name. Default.N

To identify urbanization names, ValidateAddress scans the addresslines for keywords and patterns that help it identify which fields areaddress lines and which are urbanization name lines. Since this is donebased on patterns, it is possible for ValidateAddress to incorrectly identifyfields. To help ensure optimal urbanization extraction, place the primary




address elements in AddressLine1, the secondary elements inAddressLine2, Urbanization in AddressLine3, and firm in AddressLine4,if possible. For example,


Specifies whether to perform SuiteLink™ processing.Option.PerformSuiteLink

SuiteLink corrects secondary address information for U.S. businessaddresses whose secondary address information could not be validated.If SuiteLink processing is enabled, the firm name is matched to a databaseof known firm names and their secondary address information.

For example,

Firm Name: Pitney Bowes SoftwareAddress Line 1: 4200 Parliament PlaceAddress Line 2: STE 1Postal Code: 20706

In this case, SuiteLink processing would change the suite number to thecorrect suite number:

Firm Name: Pitney Bowes SoftwareAddress Line 1: 4200 Parliament PlaceAddress Line 2: STE 600Postal Code: 20706-1844

SuiteLink attempts to correct firm names in addresses where:

• A firm name is present• A valid ZIP Code™, ZIP + 4® Code, and primary number could bedetermined

• A match has been made to a high-rise default record• The secondary address information could not be validated throughnormal processing

To perform SuiteLink™ processing, you must have the SuiteLink™

database installed.

This option takes one of the following values:

No, do not use SuiteLink™. Default.N

Yes, use SuiteLink™ processing.Y

For a listing of fields returned by this option, see SuiteLink Output onpage 176.

Specifies whether to use a street's preferred alias in the output.Option.OutputPreferredAlias

Street name aliases in the United States are alternative names givento sections of a street. There are four types of street name aliases:

• Preferred—A preferred alias is the street name preferred locally. Ittypically applies only to a specific range of addresses on the street.




• Abbreviated—An abbreviated alias is a variation of the street namethat can be used in cases where the length of AddressLine1 is longerthan 31 characters. For example, the street name 1234 BERKSHIREVALLEY RD APT 312A could be abbreviated to 1234 BERKSHIREVLLY RD APT 312A.

• Changed—There has been an official street name change and thealias reflects the new name. For example if SHINGLE BROOK RD ischanged to CANNING DR, then CANNING DR would be a changedalias type.

• Other—The street alias is made up of other names for the street orcommon abbreviations of the street.

The non-alias version of the street name is called the base street name.

If the preferred alias is used in the input then the preferred alias will bethe street name in the output regardless of whether you enable thisoption.

This is one of three options that control how ValidateAddress handlesstreet name aliases. The other two are Option.OutputStreetNameAliasand Option.OutputAbbreviatedAlias.

In most cases, if you select both Option.OutputPreferredAlias andOption.OutputAbbreviatedAlias, and ValidateAddress finds both apreferred and an abbreviated alias in the postal database, theabbreviated alias will be used in the output. The exception to this ruleis if the input street name is a preferred alias. In this case, the preferredalias will be used in the output.

Yes, perform preferred alias processing.Y

No, do not perform preferred alias processing. Default.N

If the input address contains a street name alias of type"changed" the output address will always contain the base streetname regardless of the options you specify.

Note:

Specifies whether to use a street's abbreviated alias in the output if theoutput address line is longer than 31 characters.

Option.OutputAbbreviatedAlias

This is one of three options that control how ValidateAddress handlesstreet name aliases. The other two are Option.OutputStreetNameAliasand Option.OutputPreferredAlias.

If a preferred alias is specified in the input, the output streetname will always be the preferred alias, even if you enableabbreviated street name alias processing.

Note:

Yes, perform abbreviated alias processing.Y

No, do not perform abbreviated alias processing. Default.N

If the input address contains a street name alias of type"changed" the output address will always contain the base streetname regardless of the options you specify.

Note:

Determines the "no stat" status of an address. An address is considered"no stat" if it exists but cannot receive mail, and therefore is not counted

Option.DPVDetermineNoStat

as a delivery statistic on a carrier's route (hence the term "no stat").




Examples include buildings under construction or those that the lettercarrier has identified as not likely to receive mail.

No, do not determine "no stat" status. Default.N

Yes, determine "no stat" status.Y

You must enable DPV processing to use this option.Note:

The result is returned in the DPVNoStat field. For more information seeLACSLink Output on page 174

Determines if the location has been unoccupied for at least 90 days.Option.DPVDetermineVacancy

No, do not determine vacancy. Default.N

Yes, determine vacancy.Y


The result is returned in the DPVVacant field. For more information seeLACSLink Output on page 174

Returns VeriMove detail data in output.Option.ReturnVerimove

No, do not return VeriMove detail data. Default.N

Yes, return VeriMove detail data.Y

Specifies the algorithm to use when determining if an input addressmatches an address in the postal database. One of the following:

Option.StreetMatchingStrictness

The input street name must match the database exactly.E





Option.FirmMatchingStrictness

The input firm name must match the database exactly.E





Option.DirectionalMatchingStrictness

The input directionals, such as the "N" in 123 N Main St.,must match the database exactly.

E


The matching algorithm is "medium". Default.M


Select thematch condition where a DPV result does NOT cause a recordto fail.

Option.DPVSuccessfulStatusCondition




Full matchF

Partial matchP

Always. Default.A


Treat Commercial Mail Receiving Agency (CMRA)matches as failures?Option.FailOnCMRAMatch

No, do not treat CMRA matches as failures. Default.N

Yes, treat CMRA matches as failures.Y


Specifies where ValidateAddress places Private Mailbox (PMB)information.

Option.StandardAddressPMBLine

Do not include the PMB information in Standard Addressoutput (default).

N

Place the PMB information in AddressLine1. If you specify 1,you must set Option.StandardAddressFormat to either C orD.

1

Place the PMB information in AddressLine2.2

CASS Certified Processing

CASS Certified™ processing also generates the USPS CASS Detailed Report, which contains some ofthe same information as the 3553 report but provides much greater detail about DPV, LACS, and SuiteLinkstatistics. The USPS CASS Detailed Report is not required for postal discounts and does not need tobe submitted with your mailing.

1. Validate Address must be in CASS Certified™ mode. If (Not CASS Certified) appears at the top ofthe window, click the Enable CASS button. The Enforce CASS rules check box will appear.

2. Click Configure CASS 3553. The CASS Report Fields dialog box appears.3. Type the List Processor company name, List Name or ID#, and the Number of Lists being

processed for this job.4. Type the Mailer Name, Address, and City, State, ZIP.5. Click OK.

The List information will appear in Section B and the Mailer information in Section D of the generatedUSPS® CASS Form 3553.



6. In Enterprise Designer, drag the CASS3553 report from the Reports pallet to the canvas.

7. Double-click the CASS3553 icon on the canvas.8. On the Stages tab, check the Validate Address checkbox. Note that if you have renamed the Validate

Address stage to something else, you should check the box with the name you have given the addressvalidation stage.

9. On the Parameters tab, select the format for the report. You can create the report in PDF, HTML,or plain text format.

10. Click OK.11. Repeat steps 6-10 for CASSDetail if you want to produce the CASS Detail Report.

Canadian Address Options


Specifies whether to process Canadian addresses.If you enable Canadian address processing


ValidateAddress will attempt to validate Canadianaddresses. If you disable Canadian addressprocessing, Canadian addresses will fail, meaningthey is returned with an "F" in the Status outputfield. The output field Status.Code will say"DisabledCoder." If you are not licensed forCanadian address processing you must disableCanadian address processing in order for your jobsto complete successfully, regardless of whether ornot they contain Canadian addresses.

You must have a valid license for Canadianaddress processing to successfully process

Note:

Canadian addresses. If you enableCanadian address processing but are notlicensed for this feature, or your license hasexpired, you will receive an error.





Yes, process Canadian addresses(default).

Y

Specifies which database you want to use forvalidating Canadian addresses. To specify a


database for Canadian address validation, selecta database in the Database drop-down list. Onlydatabases that have been defined in the CANDatabase Resources panel in the ManagementConsole are available.

Specifies how to determine the language (Englishor French) to use to format the address and

Option.CanFrenchFormat

directional. The following example shows anaddress formatted in English and French:

English: 123 Main St WFrench: 123 Rue Main O

The parameter controls the formatting of theaddress. It also affects the spelling of the directionalbut not spelling of the suffix.

Use the street suffix returned by the matchingprocess to determine the language. The street

C

suffix returned by thematching process, whichis used internally by ValidateAddress duringprocessing, may be different from that in theinput address. Ambiguous records areformatted like the input. Default. All addressesin Quebec are formatted using French.

Use the Canadian database to determine thelanguage. The Canadian database contains

S

data from the Canada Post Corporation(CPC). All addresses in Quebec are formattedusing French.

Use the CanLanguage input field to determinethe language. If there is a non-blank value in

T

this field the address are formatted usingFrench.

For English addresses, specifies the defaultapartment label to use in the output if there is no

Option.CanFrenchFormat

apartment label in the input address. This settingis ignored if you specifyOption.CanStandardAddressFormat=F.

Use "Apt" as the label. Default.Apt

Use "Apartment" as the label.Apartment

Use "Suite" as the label.Suite

Use "Unit" as the label.Unit




For French addresses, specifies the defaultapartment label to use in the output if there is no

Option.CanFrenchApartmentLabel

apartment label in the input address. This settingis ignored if you specifyOption.CanStandardAddressFormat=F.

Use "App" as the label. Default.App

Use "Appartement" as the label.Appartement

Use "Bureau" as the label.Bureau

Use "Suite" as the label.Suite

Use "Unite" as the label.Unite

In cases where the house number and postal codeare both valid but in conflict, you can force the

Option.CanPreferHouseNum

postal code to be corrected based on the housenumber by specifyingOption.CanPreferHouseNum=Y. If you do notselect this option the house number is changed tomatch the postal code.

Change the house number to match thepostal code. Default.

N

Change the postal code to match thehouse number.

Y

Specifies whether or not to return the city aliaswhen the alias is in the input address. This option

Option.CanOutputCityAlias

is disabled when you specifyOption.CanOutputCityFormat=D.

Output the city alias when the city alias isin the input. Default.

Y

Never output the city alias even if it is inthe input.

N

Specifies whether or not non-civic keywords areabbreviated in the output. For example, Post OfficeBox vs. PO Box.

Option.CanNonCivicFormat

Abbreviate non-civic keywords. Default.A

Do not abbreviate non-civic keywords. Thefull keyword is used.

F

Specifies whether or not to use SERP options.Option.EnableSERP

Enable SERP options.Y

Do not enable SERP options. Default.N

Specifies where to place secondary addressinformation in the output address. Secondary

Option.CanStandardAddressFormat

address information refers to apartment numbers,suite numbers, and similar designators.




Place apartment information in the locationspecified in the. Default.

D

Place apartment information at the at theend of the AddressLine1 field.

B

Place the apartment number only (no label)at the beginning of the AddressLine1 field.For example, 400-123 Rue Main

F

Place the apartment number and label atthe beginning of the AddressLine1 field. Forexample, Apt 400 123 Rue Main

E

Place apartment information on a separateline.

S

Place apartment information in the samelocation as the input address.

S

Specifies whether to use the long, medium, or shortversion of the city if the city has a long name. Forexample,

Option.CanOutputCityFormat

Long: BUFFALO HEAD PRAIRIEMedium: BUFFALO-HEAD-PRShort: BUFFALO-HD-PR

Use the default option specified by theOption.OutputShortCityName parameter.

D

Default. If you specifyOption.OutputShortCityName=V, the city isformatted as if you select for this option(see below) andY forCanOutputCityAlias.

Output short city name.S

Output the long city name.L

Output the medium city name.M

Use the same city format as used in theinput address. Output is L, M, or S.

I

Specifies where to place rural route deliveryinformation. An example of an address with ruralroute delivery information is:

Option.CanRuralRouteFormat

36 GRANT RD RR 3ANTIGONISH NS

In this address, "RR 3" is the rural route deliveryinformation.

Place rural route delivery information on thesame line as the address, after the addressinformation. Default. For example,

36 GRANT RD RR 3

A




Place rural route delivery information on aseparate address line. For example,

36 GRANT RDRR 3

S

Specifies where to place station information. Anexample of an address with station information is:

PO BOX 8625 STN AST. JOHN'S NL

Option.CanDeliveryOfficeFormat

Place station information in the samelocation as it is in the input address. Default.

I

Place station information on the same lineas the address, after the addressinformation. For example,

PO BOX 8625 STN A

A

Place station information on a separateaddress line. For example,

PO BOX 8625STN A

S

Specifies whether ValidateAddress should returna street match or a PO Box/non-civic match when

Option.CanDualAddressLogic

the address contains both civic and non-civicinformation. One of the following:

Use DualAddressLogic Global Option.Default.

D

Match to PO Box or other non-streetdata.

P

Match to street.S

For example, given the following input address:

AddressLine1: 36 GRANT RDAddressLine2: RR 4City: ANTIGONISHStateProvince: NS

ValidateAddress would return one of the following:

• If Option.CanDualAddressLogic is set to S,ValidateAddress returns the following:

AddressLine1: 36 GRANT RDAddressLine2: RR 3City: ANTIGONISHStateProvince: NSPostalCode: B2G 2L1

• If Option.CanDualAddressLogic is set to P,ValidateAddress returns the following:




AddressLine1: RR 4City: ANTIGONISHStateProvince: NSPostalCode: B2G 2L2

The address data that is not used to standardizethe address is returned in theAdditionalInputDatafield. For more information on this option, seeOutput Data Options on page 129.

SERP Processing

1. Validate Address must be in SERP Certified™ mode. If (Not SERP Certified) appears at the top ofthe window, click the Enable SERP settings button. The Configure SERP box will appear.

2. Click Configure SERP. The SERP Report Fields dialog box appears.3. Type your merchant CPC number.4. Type the mailer Name, Address, and City, State, ZIP.5. Click OK.6. In Enterprise Designer, drag the SERPReport from the Reports pallet to the canvas.

7. Double-click the SERPReport icon on the canvas.8. On the Stages tab, ensure that the Validate Address checkbox is checked. Note that if you have

renamed the Validate Address stage to something else, you should check the box with the nameyou have given the address validation stage.

9. On the Parameters tab, select the format for the report. You can create the report in PDF, HTML,or plain text format. PDF format is the default.

10. Click OK.

Obtaining SERP Return Codes

SERP return codes indicate the quality of the input address as determined by the Canada Post's SoftwareEvaluation and Recognition Program regulations.



To obtain SERP return codes, specify Option.OutputRecordType=P. For more information onOption.OutputRecordType, see Output Data Options on page 129.

SERP return codes are provided in the following output field.

Table 71: SERP Return Code Output


Validation/correction return code (Canadian addresses only):CanadianSERPCode

The input was valid. Canada Post defines a "valid" address as anaddress that meets all the following requirements:

V

There are exceptions. For further information, contactthe CPC.

Note:

• The address must contain all required components as found inCPC's Postal Code Data Files.

• The address must provide an exact match on all componentsfor only one address in CPC's Postal Code Data Files, allowingfor acceptable alternate words and names listed in the CPCPostal Code Data Files.

• Address components must be in a form that allows recognitionwithout ambiguity. Certain components may require "qualifiers"to identify them. For instance, a Route Service address requiresthe key words "Rural Route" or "RR" for differentiation from a"Suburban Service" or "SS" address with the same number.

The input was invalid. An "invalid" address is one that does notmeet CPC requirements for a valid address (see above). Examples

I

of this include address components that are missing, invalid, orinconsistent.

The input was correctable. A "correctable" address is one thatcan be corrected to match one, and only one, address.

C

The input was non-correctable. A "non-correctable" address isone that could be corrected a number of different ways such thatValidateAddress cannot identify a single correct version.

N

The input address was foreign (outside of Canada).F

International Address Options

Addresses outside of the U.S. and Canada are referred to as "international" addresses. The followingoptions control international address processing:


Specifies whether to process internationaladdresses (addresses outside the U.S. and

Option.PerformInternationalProcessing

Canada). If you enable international addressprocessing ValidateAddress will attempt to validateinternational addresses. If you disable internationaladdress processing, international addresses willfail, meaning they is returned with an "F" in theStatus output field. The output field Status.Codewill say "DisabledCoder." If you are not licensed




for international address processing you mustdisable international address processing in orderfor your jobs to complete successfully, regardlessof whether or not they contain internationaladdresses.

You must have a valid license forinternational address processing to

Note:

successfully process internationaladdresses. If you enable internationaladdress processing but are not licensedfor this feature, or your license has expired,you will receive an error.

No, do not process internationaladdresses.

N

Yes, process international addresses(default).

Y

Specifies which database you want to use forvalidating international addresses. To specify a

Option.Database.International

database for international address validation, selecta database in the Database drop-down list. Onlydatabases that have been defined in the INTLDatabase Resources panel in the ManagementConsole are available.

By default, ValidateAddress provides a balance ofgood address matching accuracy with good

Option.InternationalCityStreetSearching

performance. If you are willing to trade matchingaccuracy for faster performance, use theOption.InternationalCityStreetSearching parameterto increase processing speed. When you do this,some accuracy is lost. This option only controlsperformance for addresses outside the U.S. andCanada. This setting affects a small percentage ofrecords, mostly addresses in the U.K. There is noperformance control for U.S. and Canadian addressprocessing.

If you use GetCandidateAddresses, the candidateaddresses returned by GetCandidateAddressesmay differ from the multiple matches returned byValidateAddress if you set the performance tuningoption for international addresses to any value otherthan 100.

To control performance, specify a value from 0 to100. A setting of 100 maximizes accuracy while asetting of 0 maximizes speed. The default is 100.

This option enables ValidateAddress to search theAddressLine input fields for the city, state/province,

Option.AddressLineSearchOnFail

postal code, and country when the address cannotbe matched using the values in the City,StateProvince, and PostalCode input fields.




Consider enabling this option if your inputaddresses have the city, state/province, and postalcode information in the AddressLine fields.

Consider disabling this option if your inputaddresses use the City, State/Province andPostalCode fields. If you enable this option andthese fields are used, there is an increasedpossibility that ValidateAddress will fail to correctvalues in these fields (for example a misspelledcity name).

No, do not search the AddressLine fields.N

Yes, search the address line fields.Default.

Y

ResponseThe output from ValidateAddress contains different information depending on the output categories youselect.

Standard Address OutputStandard address output consists of four lines of the address which correspond to how the addresswould appear on an actual address label. City, state/province, postal code, and other data is also includedin standard address output. ValidateAddress returns standard address output for validated addressesif you set Option.OutputRecordType=A. Standard address fields are always returned for addresses thatcould not be validated. For non-validated addresses, the standard address output fields contain theaddress as it appeared in the input ("pass through" data). If you want ValidateAddress to standardizeaddress according to postal authority standards when validation fails, specifyOption.OutputFormattedOnFail=Y in your request.

Table 72: Standard Address Output


Input data not used by ValidateAddress. For more information, seeAbout AdditionalInputData on page 178.

AdditionalInputData

If the address was validated, the first line of the validated andstandardized address. If the address could not be validated, the firstline of the input address without any changes.

AddressLine1

If the address was validated, the second line of the validated andstandardized address. If the address could not be validated, the secondline of the input address without any changes.

AddressLine2

If the address was validated, the third line of the validated andstandardized address. If the address could not be validated, the thirdline of the input address without any changes.

AddressLine3

If the address was validated, the fourth line of the validated andstandardized address. If the address could not be validated, the fourthline of the input address without any changes.

AddressLine4




For U.K. addresses only. If the address was validated, the fifth line ofthe validated and standardized address. If the address could not bevalidated, the fifth line of the input address without any changes.

AddressLine5

The validated city name.City


• ISO Code• UPU Code• English• French• German• Spanish

For U.K. addresses only, a subdivision of a firm. For example,Engineering Department.

DepartmentName

The validated firm or company name.FirmName

The validated ZIP Code™ or postal code.PostalCode

The 4-digit add-on part of the ZIP Code™. For example, in the ZIP Code™

60655-1844, 1844 is the 4-digit add-on. (U.S. addresses only.)PostalCode.AddOn

The 5-digit ZIP Code™; for example 20706 (U.S. addresses only).PostalCode.Base

The validated state or province abbreviation.StateProvince

The validated urbanization name. (U.S. addresses only.)USUrbanName

Parsed Address Elements OutputOutput addresses are formatted in the parsed address format if you set Option.OutputRecordType=E.If you want ValidateAddress to return formatted data in the Parsed Address format when validation fails(that is, a normalized address), specify Option.OutputFormattedOnFail=Y.

If you want ValidateAddress to always return parsed input data regardless of whether or notvalidation is successful, specify Option.OutputRecordType=I. For more information, see ParsedInput on page 159.

Note:

Table 73: Parsed Address Output


Input data not used by ValidateAddress. For moreinformation, see About AdditionalInputData onpage 178.

AdditionalInputData

Apartment designator (such as STE or APT), forexample: 123 E Main St APT 3

ApartmentLabel

Secondary apartment designator, for example: 123E Main St APT 3, 4th Floor

ApartmentLabel2




In this release, this field will always beblank.

Note:

Apartment number. For example: 123 E Main StAPT 3

ApartmentNumber

Secondary apartment number. For example: 123E Main St APT 3, 4th Floor

ApartmentNumber2


Note:

Delivery installation name (Canadian addressesonly)

CanadianDeliveryInstallationAreaName

Delivery installation qualifier (Canadian addressesonly)

CanadianDeliveryInstallationQualifierName

Delivery installation type (Canadian addresses only)CanadianDeliveryInstallationType

Validated city nameCity

Country. Format is determined by what youselected in :

Country

• ISO Code• UPU Code• English• French• German• Spanish

For U.K. addresses only, a subdivision of a firm.For example, Engineering Department.

DepartmentName

The validated firm or company nameFirmName

House number, for example: 123 E Main St Apt 3HouseNumber

Leading directional, for example: 123 E Main StApt 3

LeadingDirectional

Post office box number. If the address is a ruralroute address, the rural route box number willappear here.

POBox

Validated postal code. For U.S. addresses, this isthe ZIP Code.

PostalCode

Private mailbox indicator.PrivateMailbox

The type of private mailbox. Possible valuesinclude:

PrivateMailbox.Type

• Standard• Non-Standard




This replaces PrivateMailboxType (noperiod in field name). Please modify yourAPI calls accordingly.

Note:

Rural Route/Highway Contract indicatorRRHC

Validated state or province nameStateProvince

Street name, for example: 123 E Main St Apt 3StreetName

Street suffix, for example: 123 E Main St Apt 3StreetSuffix

Trailing directional, for example: 123 PennsylvaniaAve NW

TrailingDirectional

USPS® urbanization name. Puerto Rican addressesonly.

USUrbanName

Parsed InputThe output can include the input address in parsed form. This type of output is referred to as "parsedinput." Parsed input fields contain the address data that was used as input regardless of whether or notValidateAddress validated the address. Parsed input is different from the "parsed address elements"output in that parsed address elements contain the validated address if the address could be validated,and, optionally, the input address if the address could not be validated. Parsed input always containsthe input address regardless of whether or not ValidateAddress validated the address.

To include parsed input fields in the output, set Option.OutputRecordType=I.

Table 74: Parsed Input



ApartmentLabel.Input

Apartment number, for example: 123 E Main StAPT 3

ApartmentNumber.Input

Delivery installation name (Canadian addressesonly)

CanadianDeliveryInstallationAreaName.Input

Delivery installation qualifier (Canadian addressesonly)

CanadianDeliveryInstallationQualifierName.Input

Delivery installation type (Canadian addresses only)CanadianDeliveryInstallationType.Input

Validated city nameCity.Input

Country. Format is determined by what youselected in:

Country.Input

• ISO Code• UPU Code• English• French




• German• Spanish

The validated firm or company nameFirmName.Input

House number, for example: 123 E Main St Apt 3HouseNumber.Input


LeadingDirectional.Input


POBox.Input


PostalCode.Input

Private mailbox indicatorPrivateMailbox.Input

The type of private mailbox. Possible valuesinclude:

PrivateMailbox.Type.Input

• Standard• Non-Standard

Rural Route/Highway Contract indicatorRRHC.Input

Validated state or province nameStateProvince.Input

Street name, for example: 123 E Main St Apt 3StreetName.Input

Street suffix, for example: 123 E Main St Apt 3StreetSuffix.Input


TrailingDirectional.Input

USPS® urbanization nameUSUrbanName.Input

Postal Data OutputIf Option.OutputRecordType contains P then the following fields are returned in the output.

Table 75: Postal Data Output


Validation/correction return code (Canadian addresses only). For moreinformation, see Obtaining SERP Return Codes on page 153.

CanadianSERPCode

For addresses in France only, a numeric code that represents the street.For information about Hexavia codes, see www.laposte.fr.

IntHexaviaCode

For addresses in France only, a numeric code that represents the city.For a listing of INSEE codes, see www.insee.fr.

IntINSEECode



http://www.laposte.fr/

http://www.insee.fr


The two-digit delivery point portion of the delivery point barcode (U.S.addresses only) For more information, see Creating Delivery PointBarcodes on page 134.

PostalBarCode

Indicates whether or not alternate address matching logic was used, andif so which logic was used (U.S. addresses only). One of the following:

USAltAddr

No alternate address scheme used.null

Delivery point alternate logic was used.D

Enhanced highrise alternate match logic was used.E

Small town default logic was used.S

Unique ZIP Code logic was used.U

Check-digit portion of the 11-digit delivery point barcode (U.S. addressesonly). For more information, see Creating Delivery Point Barcodes onpage 134.

USBCCheckDigit

Carrier route code (U.S. addresses only). For more information, seeObtaining Carrier Route Codes on page 134.

USCarrierRouteCode

Congressional district (U.S. addresses only). For more information, seeObtaining Congressional Districts on page 133.

USCongressionalDistrict

County name (U.S. addresses only). For more information, seeObtainingCounty Names on page 133.

USCountyName

The finance number in which the address resides (U.S. addresses only).The finance number is a number assigned by the USPS to an area that

USFinanceNumber

covers multiple ZIP Codes. ValidateAddress will successfully validatean address only if its finance number matches the finance number of thecandidate address in the U.S. Database.

FIPS (Federal Information Processing Standards) county number (U.S.addresses only). For more information, see Obtaining FIPS CountyNumbers on page 133.

USFIPSCountyNumber

Indicates whether or not the address is a candidate for LACSLink

conversion (U.S. addresses only). One of the following:USLACS

Yes, the address is a candidate for LACSLink processing. If LACSLink

is enabled, ValidateAddress will attempt to convert the addressY

using the LACSLink database. If the conversion attempt issuccessful, the output address is the new address obtained fromthe LACSLink database. If the attempt is not successful, the addresswill not be converted.

No, the address is not a candidate for LACSLink processing.LACSLink processing may still be attempted if LACSLink processing

N

is requested, the LACSLink database is installed, and one of thefollowing is true:

• The address matches to a Rural Route address and theRecordType.Default field returns a Y.

• The input address could not be matched to any address in theU.S. Postal Database (Failures due to multiple matches are notLACSLink candidates.)




A six-character alphanumeric value that groups together ZIP Codes thatshare the same primary city. For example, addresses with the followingtwo last lines would have the same last line number:

USLastLineNumber

Chantilly VA 20151 Chantilly VA 20152

Result IndicatorsResult indicators provide information about the kinds of processing performed on an address. There aretwo types of result indicators:

• Record-Level Result Indicators on page 162• Field-Level Result Indicators on page 165

Record-Level Result Indicators

Record-level result indicators provide data about the results of ValidateAddress processing for eachrecord, such as the success or failure of the match attempt, which coder processed the address, andother details. The following table lists the record-level result indicators returned by ValidateAddress.

Table 76: Record Level Indicators


The type of address data being returned:AddressFormat

French format (for example: 123 Rue Main)F

English format (for example: 123 Main St)E


Confidence

100 indicates a very high level of confidence that the matchresults are correct. For multiple matches, the confidence levelis 0. For details about how this number is calculated, seeIntroduction to the Validate Address ConfidenceAlgorithm on page 252.

If no match was found, which address component could notbe validated:

CouldNotValidate

• ApartmentNumber• HouseNumber• StreetName• PostalCode• City• Directional• StreetSuffix• Firm• POBoxNumber• RuralRoute

More than one component may be returned, in acomma-separated list.

Note:




The category of address matching available. This is always"A" for U.S. and Canadian addresses. One of the following:

CountryLevel

The address is in a country for which there is highlydetailed postal data available. Addresses in this match

A

level can have the following address elements validatedand corrected, and added if missing from the input:

• Postal code• City name• State/county name• Street address elements• Country name.

The address is in a country for which there is a mediumlevel of postal data available. Addresses in this match

B

level can have the following address elements validatedand corrected, and added if missing from the input:

• Postal code• City name• State/county name• Country name

The address is in a country for which the postal data isleast detailed. Addresses in this match level can havethe following actions performed on them:

C

• Validate and correct country name (cannot supplymissing country name)

• Validate the format of the postal code (cannot supplymissing postal code or validate the code)

MatchScore provides an indication of the degree to which theoutput address is correct. It is significantly different from

MatchScore

Confidence in that Confidence is indicates how much theinput address changed to obtain a match, whereas themeaning of Match Score varies between U.S. and non-U.S.addresses.

For U.S. addresses, MatchScore is a one-digit score on ascale of 0 to 9 that reflects the closeness of the street-namematch (after transformations by ValidateAddress, if any). Zeroindicates an exact match and 9 indicates the least likelymatch. If no match was found, this field is blank.

For non-U.S. and non-Canadian addresses, MatchScore isa five-digit score, with a maximum value of 00999. Highernumbers indicates a closer match.

This field does not apply to Canadian addresses.

Note that you cannot equate match scores from U.S.addresses with those of non-U.S. addresses. For example,a match score of 4 for a U.S address does not indicate thesame level of match as a 00004 for a non-U.S. address.




The Validate Address and AdvancedMatchingModulecomponents both use the MatchScore field. The

Note:

MatchScore field value in the output of a dataflow isdetermined by the last stage to modify the valuebefore it is sent to an output stage. If you have adataflow that contains Validate Address and AdvancedMatching Module components and you want to seethe MatchScore field output for each stage, use aTransformer stage to copy the MatchScore value toanother field. For example, Validate Address producesan output field called MatchScore and then aTransformer stage copies the MatchScore field fromValidate Address to a field called AddressMatchScore.When the matcher stage runs it populates theMatchScore field with the value from thematcher andpasses through the AddressMatchScore value fromValidate Address.

If multiple matches were found, indicates the number ofrecords that are possible matches.

MultimatchCount

Indicates which address component had multiple matches, ifmultiple matches were found:

MultipleMatches

• Firm• LeadingDirectional• PostalCode• StreetName• StreetSuffix• TrailingDirectional• Urbanization


Note:

Which address coder processed the address:ProcessedBy

U.S. address coderUSA

Canadian address coderCAN

International address coderINT

Type of address record, as defined by U.S. and Canadianpostal authorities (supported for U.S. and Canadian addressesonly):

RecordType

• FirmRecord• GeneralDelivery• HighRise• PostOfficeBox• RRHighwayContract• Normal

Code indicating the "default" match:RecordType.Default




The address matches a default record.Y

The address does not match a default record.null

Reports the success or failure of the match attempt. Formultiple matches, this field is "F" for all the possible matches.

Status

Successnull

FailureF

Reason for failure, if there is one. For multiple matches, allpossible matches is "MultipleMatchesFound."

Status.Code

• DisabledCoder• InsufficientInputData• MultipleMatchesFound• UnableToValidate

Description of the problem, if there is one.Status.Description

This value will appear ifStatus.Code=MultipleMatchesFound.

Possible Multiple AddressesFound

This value will appear ifStatus.Code=UnableToValidate.

Address Not Found


PerformUSProcessing disabled




PerformInternationalProcessingdisabled

Field-Level Result Indicators

Field-level result indicators describe how ValidateAddress handled each address element. Field-levelresult indicators are returned in the qualifier "Result". For example, the field-level result indicator forHouseNumber is contained in HouseNumber.Result.

To enable field-level result indicators, . For more information on this option, see Output Data Optionson page 129.

The following table lists the field-level result indicators. If a particular field does not apply to an address,the result indicator may be blank.

Table 77: Field-Level Result Indicators


These result codes apply to international addresses only.AddressRecord.Result

Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field.

M




Standardized. This option includes any standardabbreviations.

S

Unmatched.U

Validated. The data was confirmed correct and remainedunchanged from input.

V

ApartmentLabel.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A

Corrected. U.S. and Canadian addresses only.C

Dropped. The field provided on input was removed. U.S. andCanadian addresses only. For more information, see AboutAdditionalInputData on page 178.

D

Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.

F

Pass-through. The data was not used in the validation process,but it was preserved in the output. U.S. and Canadianaddresses only.

P

The apartment label is required but is missing from the inputaddress. U.S. addresses only.

R

Standardized. This option includes any standard abbreviations.S

Unmatched. Does not apply to Canadian addresses.U


V

ApartmentNumber.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A

Corrected. Canadian addresses only.C

Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.

D


F

Pass-through. The data was not used in the validation process,but it was preserved in the output. U.S. addresses that are an

P

EWS match will have a value of P. U.S. and Canadianaddresses only.

The apartment number is required but is missing from the inputaddress. U.S. addresses only.

R

Standardized. This option includes any standard abbreviations.Does not apply to U.S. addresses.

S

Unmatched.U


V




City.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A


Hyphens missing or punctuation errors. Canadian addressesonly.

F

Multiple. The input address matched multiple records in thepostal database, and each matching record has a different

M

value in this field. Does not apply to U.S. or Canadianaddresses.

Pass-through. The data was not used in the validation process,but it was preserved in the output.

P

The city is required but is missing from the input address. U.S.addresses only.

R


S



V

These result codes do not apply to U.S. or Canadian addresses.Country.Result


M


S

Unmatched.U


V

FirmName.Result Corrected. U.S. addresses only.C

Pass-through. The data was not used in the validationprocess, but it was preserved in the output. U.S. and Canadianaddresses only.

P

Unmatched. U.S. and Canadian addresses only.U

Validated. The data was confirmed correct and remainedunchanged from input. U.S. addresses only.

V

HouseNumber.Result Appended. The field was added to a blank input field.Canadian addresses only.

A



D





F

Out of range. Does not apply to U.S. or Canadian addresses.O

Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.

P

The house number is required but is missing from the inputaddress. Canadian addresses only.

R

Standardized. This option includes any standard abbreviations.Does not apply to U.S. or Canadian addresses.

S

Unmatched.U


V

LeadingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A

Corrected. Non-blank input was corrected to a non-blank value.U.S. addresses only.

C


D


F

Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field. U.S. addresses only.

M


P


Unmatched.U

Validated. The data was confirmed correct and remainedunchanged from input. Does not apply to Canadian addresses.

V

POBox.Result Appended. The field was added to a blank input field. Canadianaddresses only.

A



D


F




Multiple matches. The input address matched multiple recordsin the postal database, and each matching record has adifferent value in this field. U.S. addresses only.

M


P

The P.O. Box number is required but is missing from the inputaddress. U.S. addresses only.

R


Unmatched.U


V

PostalCode.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



F

Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field. Does not apply to Canadian addresses.

M

Pass-through. The data was not used in the validation process,but it was preserved in the output. Does not apply to U.S.addresses.

P

The postal code is required but is missing from the inputaddress. U.S. addresses only.

R


S

Unmatched. For example, if the street name does not matchthe postal code, both StreetName.Result andPostalCode.Result will contain U.

U


V

These result codes apply to international addresses only.PostalCodeCity.Result


M

Pass-through. The data was not used in the validationprocess, but it was preserved in the output.

P


S

Unmatched.U


V




These result codes apply to U.S. addresses only.PostalCode.Source

The ZIP Code™ in the input was verified by usingUSPS® Finance Number groupings.

FinanceNumber

The ZIP Code™ in the input address was correctedbecause the USPS® redrew ZIP Code™ boundariesand the address is now in a different ZIP Code™.

ZIPMOVE

PostalCode.Type The ZIP Code™ contains only PO Box addresses. U.S.addresses only.

P

The ZIP Code™ is a unique ZIP Code™ assigned to aspecific company or location. U.S. addresses only.

U

The ZIP Code™ is for military addresses. U.S. addressesonly.

M

The ZIP Code™ is a standard ZIP Code™.null

RRHC.Result Corrected. Canadian addresses only.C


D

Multiple matches. The input address matched multiple recordsin the postal database, and each matching record has adifferent value in this field. U.S. addresses only.

M


P

The rural route/highway contract is required but is missing fromthe input address. U.S. addresses only.

R

Standardized. This option includes any standard abbreviations.U.S. and Canadian addresses only.

S


Validated. The data was confirmed correct and remainedunchanged from input. U.S. and Canadian addresses only.

V

These result codes apply to U.S. addresses only.RRHC.Type

The address is a Highway Contract address.HC

The address is a Rural Route address.RR

StateProvince.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A

Corrected. U.S. addresses only.C


M



P




The state is required but is missing from the input address.U.S. addresses only.

R


S



V

These result codes apply to international addresses only.Street.Result


M


P

Street corrected. House number is out of range. Applies toUK and Japanese records only.

R


S

Unmatched.U


V

Indicates the result of abbreviated alias processing. One of the following:StreetName.AbbreviatedAlias.Result

No abbreviated alias processing attempted.null

The StreetName field contains the base street name.B

The standardized address length is less than 31 charactersso the StreetName field contains the base name.

L

No abbreviated alias found.N

An abbreviated alias was found for input address. TheStreetName field contains the abbreviated alias.

Y

This result code applies to U.S. addresses only.StreetName.Alias.Type

In previous releases this field was named StreetName.AliasTypewith no "." between "Alias" and "Type." This old name is

Note:

obsolete. Please update your processes to use the new nameStreetName.Alias.Type.

The alias is an abbreviation of the street name. Forexample, HARTS-NM RD is an abbreviated alias forHARTSVILLE NEW MARLBORO RD.

Abbreviated

There has been an official street name change and thealias reflects the new name. For example if SHINGLE

Changed

BROOKRD is changed to CANNINGDR, then CANNINGDR would be a changed alias type.

The street alias is made up of other names for the streetor common abbreviations of the street.

Other




The street alias is the locally preferred alias. For example,a street is named "South Shore Dr." because it runs along

Preferred

the southern shore of a lake, not because it is south ofa municipal demarcation line. So, "South" is not apredirectional in this case and should not be shorted to"S". So, "South Shore Dr." would be the preferred alias.

Indicates the result of preferred alias processing. One of the following:StreetName.PreferredAlias.Result

No preferred alias processing attempted.null

Preferred alias processing was not attempted because theinput addressmatched to an alias. Preferred alias processingis only attempted for base addresses.

A

No preferred alias found.N

A preferred alias was found for the input address. TheStreetName field contains the preferred alias.

Y

StreetName.Result Appended. The field was added to a blank input field. Canadianaddresses only.

A



D


F


M


P


S

Unmatched.U


V

StreetSuffix.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



D


F





M


P


Unmatched. Does not apply to U.S. addresses.U


V

TrailingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



D


F


M


P




V

These result codes apply to U.S. addresses only.USUrbanName.Result

Appended. The field was added to a blank input field.A

Corrected.C


M

Unmatched.U


V

Output from OptionsValidateAddress returns additional data depending on the options you select. For information on theoutput generated by each option, see the options listed in the following sections:



Enhanced Line of Travel Output

Enhanced Line of Travel processing produces the following output.


Line of Travel sequence code and an indicator denoting USPS® LOTsequence. This field is in the format nnnnY where:

USLOTCode

The four-digit LOT code.nnnn

One of the following:Y

• A—Ascending LOT sequence• D—Descending LOT sequence

A hexadecimal value that allows you to sort your file in ascending orderonly. The hexadecimal values range from 0 to FF ascending, then FFthrough 0 descending.

USLOTHex

A two-byte value used for final sortation in place of the DPC add-on. Itconsists of an uppercase letter followed by a digit 0 through 9. Values

USLOTSequence

range from A0 (99 descending) through J9 (00 descending), and K0 (00ascending) through T9 (99 ascending).

LACSLink Output


Indicates whether or not the address is a candidate for LACSLink

conversion (U.S. addresses only). One of the following:USLACS

Yes, the address is a candidate for LACSLink processing. IfLACSLink is enabled, ValidateAddress will attempt to convert the

Y

address using the LACSLink database. If the conversion attemptis successful, the output address is the new address obtainedfrom the LACSLink database. If the attempt is not successful, theaddress will not be converted.

No, the address is not a candidate for LACSLink processing.LACSLink processing may still be attempted if LACSLink processing

N

is requested, the LACSLink database is installed, and one of thefollowing is true:

• The address matches to a Rural Route address and theRecordType.Default field returns a Y.

• The input address could not be matched to any address in theU.S. Postal Database (Failures due to multiple matches are notLACSLink candidates.)

Indicates the success or failure of LACSLink processing. (U.S. addressesonly.)

USLACS.ReturnCode

LACSLink processing successful. Record matched throughLACSLink processing.

A

LACSLink processing failed. No matching record found duringLACSLink processing.

00




LACSLink processing matched the input address to an olderhighrise default address. The address has been converted.

09

Rather than provide an imprecise address, LACSLink

processing does not provide a new address.

LACSLink processing failed. Match found during LACSLink

processing but conversion did not occur due to other USPS®

regulations.

14

LACSLink processing successful. Record matched throughLACSLink processing. Unit number dropped on input.

92

LACSLink did not process the record, or LACSLink processingwas not attempted.

null

RDI Output


Return values indicating address type.RDI

The address is a business address.B

The address is a residential address.R

The address is both a residential and a business address.M

Not checked because the address did not code at a ZIP+ 4® level, or RDI™ was not performed.

null

DPV and CMRA Output


Indicates the results of Delivery Point Validation (DPV) processing.DPV

DPV confirmed.Y

Address is not deliverable.N

The primary number was validated but the secondarynumber could not be confirmed.

S

The primary number was validated but the secondarynumber was missing from input.

D

The address matches multiple valid delivery points.M

The address could not be confirmed because the addressdid not code at the ZIP + 4® level.

U

The address caused a false-positive violation.V

Indicates if the address is a Commercial Mail Receiving Agency (CMRA)CMRA

Yes, the address is a CMRA.Y

No, the address is not a CMRA.N




Unconfirmed.U

DPV footnote codes.DPVFootnote

Input address matched to the ZIP + 4® file.AA

Input address not matched to the ZIP + 4® file.A1

Input address matched to DPV (all components).BB

Input address primary number matched to DPV butsecondary number not match (present but not valid).

CC

Input address primary number matched to DPV but highrise address missing secondary number.

N1

Input address primary number missing.M1

Input address primary number invalid.M3

Input address missing PO, RR or HC Box number.P1

Input address matched to CMRA.RR

Input address matched to CMRA but secondary numbernot present.

R1

Indicates whether the building is vacant (unoccupied for 90 days). Oneof the following:

DPVVacant

Yes, the building is vacant.Y

No, the building is not vacant.N

The option was not turned on.null

Indicates whether the building is a "no stat" building and therefore unableto receive mail. One of the following:

DPVNoStat

Yes, the building is a "no stat" building, which means thebuilding is not receiving mail.

Y

No, the building is not a "no stat" building, which meansthe building does receive mail.

N

The option was not turned on.null

SuiteLink Output


Indicates whether or not ValidateAddress corrected the secondaryaddress information (U.S. addresses only). One of the following:

SuiteLinkReturnCode

ValidateAddress corrected the secondary addressinformation.

A

ValidateAddress did not correct the secondary addressinformation.

00

SuiteLink was not performed.null




SuiteLink processing encountered an error. For example,an error would occur if the SuiteLink database is expired.

XX

Provides additional information on the SuiteLink match attempt. (U.S.addresses only)

SuiteLinkMatchCode

ValidateAddress corrected the secondary address information.A

ValidateAddress did not correct the secondary addressinformation. No additional detail about the match attempt isavailable.

B

The words in the FirmName field are all "noise" words. Noisewords are defined by the USPS® and are ignored when

C

attempting to mach the firm name. Examples of noise wordsare "company" and "corporation". ValidateAddress is not ableto correct secondary address information for firm names thatconsist entirely of noise words. For example "Company andCorporation" is all noise words.

The address is not a high-rise default address. SuiteLink

matching is only done for high-rise default addresses. AD

high-rise default is a default to use when the address does notcontain valid secondary information (the apartment number orapartment type is missing).

SuiteLink processing failed because the SuiteLink database isexpired.

E

SuiteLink was not performed or there was an error.null

Indicates how well ValidateAddress matched the firm name to the firmnames in the SuiteLink database.

SuiteLinkFidelity

The firm name matches the SuiteLink database exactly.1

Good match. All words in the firm name except one matchedthe firm name in the SuiteLink database.

2

Poor match. More than one word in the firm name did notmatch the firm name in the SuiteLink database.

3

SuiteLink could not match the firm name, or was notperformed, or there was an error.

null

VeriMove Output


Indicates whether or not ValidateAddress should return a 250-byte fieldcontaining input data to pass to VeriMove Express. This field contains

VeriMoveDataBlock

the Detail Results Indicator data required by VeriMove. For moreinformation about the contents of this field, see the VeriMove User’sGuide. One of the following:

Yes, return the field VeriMoveDataBlock..Y

No, do not return the field VeriMoveDataBlock.N



About AdditionalInputDataValidateAddress ignores some input data during the address standardization process. This extraneousdata (sometimes referred to as "dropped data") is returned in the AdditionalInputData. Some examplesof dropped data include:

• Delivery instructions (for example, "Leave at back door")• Phone numbers (for example, "555-135-8792")• Attention lines (for example, "Attn: John Smith")

Data such as this is generally not embedded in an address. If it is embedded, ValidateAddress canusually identify this extraneous data and return it in the AdditionalInputData.

ValidateAddress does not return dropped data from split indicia addresses. A split indicia addressis one where a primary address is split betweenmultiple address lines. For example, if the primary

Note:

address is "1 Green River Valley Rd" then the following would be a split indicia version of thisaddress: 1 Green River Valley Rd 01230

If there is more than one piece of dropped data in an address, each piece of data is separated by asemicolon and a space ("; ") for U.S. addresses and a space for addresses outside the U.S. The orderof dropped data in AdditionalInputData is:

1. Care of, mail stop (U.S. addresses only)2. Other extraneous data found on address lines3. Entire unused data lines

For example, if this is the input address:

123 Main St C/O John SmithApt 5 Drop at back [email protected]

Then AdditionalInputData would contain:

C/O John Smith; Apt 5 Drop At Back Dock; 555-123-4567; [email protected]; 555-123-4567

ValidateAddress can handle the following types of extraneous data:

• Care Of Data on page 178• Extraneous Data on Its Own Address Line on page 178• Extraneous Data Within an Address Line on page 179• Dual Addresses on page 180

Care Of Data

For U.S. addresses only, "care of" data is returned in AdditionalInputData. The following addressescontain examples of "care of" data:

123 Main St C/O John SmithApt 505674

123 Main StApt 5 ATTN John Smith05674

123 Main St Apt 5MailStop 205674

Extraneous Data on Its Own Address Line

ValidateAddress returns extraneous data on its own address line for U.S. and Canadian addresses.



For U.S. addresses, ValidateAddress uses the first two non-blank address lines to perform addressstandardization, unless either the firm name extraction or urbanization code extraction options are enabled(see Address Line Processing for U.S. Addresses on page 129 for more information). Data on otheraddress lines is returned in AdditionalInputData. In the following address, "John Smith" would be returnedin AdditionalInputData because it is in the third non-blank address line and ValidateAddress only usesthe first two non-blank address lines for U.S. addresses.

123 Main StApt 5John Smith05674

If one of either of the first two non-blank address lines contains extraneous data, that data is returnedin AdditionalInputData. For example, in the following addresses "John Smith" would be returned inAdditionalAddressData.

123 Main StJohn Smith05674

John Smith123 Main St05674

In the following address both "John Smith" and "Apt 5" would both be returned in AdditionalInputData."John Smith" would be returned because it is extraneous data in one of the first two address lines and"Apt 5" would be returned because U.S. address data must be in the first two non-blank address lines.

John Smith123 Main StApt 505674

Extraneous Data Within an Address Line

Extraneous data that is within an address line is returned in AdditionalInputData. For example, in thefollowing addresses "John Smith" would be returned in AdditionalInputData.

123 Main St John Smith05674

123 Main St Apt 5 John Smith05674

123 Main St John SmithApt 505674

123 Main StApt 5 John Smith05674

For U.S. addresses, only extraneous data at the end of the address line is returned in AdditionalInputData.Extraneous data that is not at the end of an address line is not returned for U.S. addresses. For example,in the following addresses "John Smith" is not returned.

John Smith 123 Main St05674

123 Main John Smith St05674



The AdditionalInputData will sometimes contain the original street name or suffix if the street name waschanged to obtain a match and the street name or suffix was at the end of a line. For example thisaddress:

Pitney Bowes Software4200 ParlamentLanham MD

ValidateAddress would correct the spelling of the street name and add the suffix, returning "4200Parliament Pl" as the corrected street address and "Parlament" in AdditionalInputData.

Dual Addresses

A dual address is an address that contains both street and PO Box/Rural Route/Highway Contractinformation. Depending on the processing options you select, the portion of the dual address that is notused for address standardization may be returned in AdditionalInputData. For more information, seeAbout Dual Address Logic on page 138.

ValidateAddressGlobalValidateAddressGlobal provides enhanced address standardization and validation for addresses outsidethe U.S. and Canada. ValidateAddressGlobal can also validate addresses in the U.S. and Canada butits strength is validation of addresses in other countries. If you process a significant number of addressesoutside the U.S. and Canada, you should consider using ValidateAddressGlobal.

ValidateAddressGlobal is part of the Universal Addressing Module.

ValidateAddressGlobal performs several steps to achieve a quality address, including transliteration,parsing, validation, and formatting.

Character Set Mapping and Transliteration

ValidateAddressGlobal handles international strings and their complexities. It uses fully Unicode enabledstring processing which enables the transliteration of non-roman characters into the Latin character setand mapping between different character sets.

Character set mapping and transliteration features include:

• Support for over 30 different character sets including UTF-8, ISO 8859-1, GBK, BIG5, JIS, EBCDIC• Proper "elimination" of diacritics according to language rules• Transliteration for various alphabets into Latin Script• Greek (BGN/PCGN 1962, ISO 843 - 1997)• Cyrillic (BGN/PCGN 1947, ISO 9 - 1995)• Hebrew• Japanese Katakana, Hiragana and Kanji• Chinese Pinyin (Mandarin, Cantonese)• Korean Hangul

Address Parsing, Formatting, and Standardization

Restructuring incorrectly fielded address data is a complex and difficult task especially when done forinternational addresses. People introduce many ambiguities as they enter address data into computersystems. Among the problems are misplaced elements (such as company or personal names in streetaddress fields) or varying abbreviations that are not only language, but also country specific.ValidateAddressGlobal identifies address elements in address lines and assigns them to the properfields. This is an important precursor to the actual validation. Without restructuring, "no match" situationsmight result.



Properly identified address elements are also important when addresses have to be truncated or shortenedto fit specific field length requirements. With the proper information in the right fields, specific truncationrules can be applied.

• Parses and analyzes address lines and identifies individual address elements• Processes over 30 different character sets• Formats addresses according to the postal rules of the country of destination• Standardizes address elements (such as changing AVENUE to AVE)

Global Address Validation

Address validation is the correction process where properly parsed address data is compared againstreference databases supplied by postal organizations or other data providers. ValidateAddressGlobalvalidates individual address elements to check for correctness using sophisticated fuzzy matchingtechnology and produces standardized and formatted output based on postal standards and userpreferences. FastCompletion validation type can be used in quick address entry applications. It allowsinput of truncated data in several address fields and generates suggestions based on this input.

In some cases, it is not possible to fully validate an address. Here ValidateAddressGlobal has a uniquedeliverability assessment feature that classifies addresses according to their probable deliverability.

Resource URL

JSON endpoint:

http://server:port/rest/ValidateAddressGlobal/results.json

XML endpoint:

http://server:port/rest/ValidateAddressGlobal/results.xml



http://myserver:8080/rest/ValidateAddressGlobal/results.json?City.StateProvince=NY&Data.AddressLine1=1+Global+View&Data.City=Troy&Data.Country=USA


{"output": [{"Country.Input": "USA","AddressLine1.Input": "1 Global View","City.Input": "Troy","Country": "UNITED STATES","AddressLine1": "1 GLOBAL VW","HouseNumber": "1","StreetName": "GLOBAL","StreetSuffix": "VW","City": "TROY","PostalCode": "12180-8371","PostalCode.Base": "12180","PostalCode.AddOn": "8371","StateProvince": "NEW YORK","County": "RENSSELAER","LastLine": "TROY NY 12180-8371","AddressBlock1": "1 GLOBAL VW","AddressBlock2": "TROY NY 12180-8371","ProcessStatus": "C4","ProcessStatus.Description": "Corrected - all elements have been

checked","ModeUsed": "BATCH","CountOverflow": "NO",



"MailabilityScore": "5","Confidence": "82.09","ElementResultStatus": "88F088E0F000000000E0","ElementInputStatus": "00600050600000000060","ElementRelevance": "11101010100000000010","AddressType": "S","AMAS.Status": "EAM0","user_fields": []

}]}



http://myserver:8080/rest/ValidateAddressGlobal/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.Country=USA&Data.StateProvince=NY


<ns2:xml.ValidateAddressGlobalResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddressGlobal">

<ns2:output><ns2:Address>

<ns2:Country>UNITED STATES</ns2:Country><ns2:AddressLine1>1 GLOBAL VW</ns2:AddressLine1><ns2:HouseNumber>1</ns2:HouseNumber><ns2:StreetName>GLOBAL</ns2:StreetName><ns2:StreetSuffix>VW</ns2:StreetSuffix><ns2:City>TROY</ns2:City><ns2:PostalCode>12180-8371</ns2:PostalCode><ns2:PostalCode.Base>12180</ns2:PostalCode.Base><ns2:PostalCode.AddOn>8371</ns2:PostalCode.AddOn><ns2:StateProvince>NY</ns2:StateProvince><ns2:County>RENSSELAER</ns2:County><ns2:LastLine>TROY NY 12180-8371</ns2:LastLine><ns2:AddressBlock1>1 GLOBAL VW</ns2:AddressBlock1><ns2:AddressBlock2>TROY NY 12180-8371</ns2:AddressBlock2><ns2:ProcessStatus>C4</ns2:ProcessStatus><ns2:ProcessStatus.Description>

Corrected - all elements have been checked</ns2:ProcessStatus.Description><ns2:ModeUsed>BATCH</ns2:ModeUsed><ns2:CountOverflow>NO</ns2:CountOverflow><ns2:MailabilityScore>5</ns2:MailabilityScore><ns2:Confidence>85.09</ns2:Confidence><ns2:ElementResultStatus>

88F0F8E0F000000000E0</ns2:ElementResultStatus><ns2:ElementInputStatus>

00606050600000000060</ns2:ElementInputStatus><ns2:ElementRelevance>

11101010100000000010</ns2:ElementRelevance><ns2:AddressType>S</ns2:AddressType><ns2:AMAS.Status>EAM0</ns2:AMAS.Status><ns2:user_fields/>

</ns2:Address></ns2:output>

</ns2:xml.ValidateAddressGlobalResponse>



Request

Parameters for Input DataValidateAddressGlobal takes a standard address as input. All addresses use this format no matter whatcountry the address is from.

Table 78: ValidateAddressGlobal Input


These fields contain address line data. AddressLine1 containsthe first address line, AddressLine2 contains the second

String[79]

Data.AddressLine1 throughData.AddressLine6

address line, and so forth. Note that the city, state/province,and postal code information should be placed in theirrespective fields, not address line fields. For example:

AddressLine1: 17413 Blodgett RoadAddressLine2: PO Box 123City: Mount VernonStateProvice: WAPostalCode: 97273Country: USA

If the input address is not already parsed into the appropriateaddress line and City, StateProvice, and PostalCode fields,use the UnformattedLine fields instead of the address linefields.

City nameString[79]

Data.City


Data.StateProvince

The postal code for the address. In the U.S. this is the ZIPCode®.

String[79]:

9999999999-9999

Data.PostalCode

A9A9A9A9A 9A99999999

The name of the addressee. For example, "Mr. Jones".String[79]

Data.Contact

The country name. If no value is specified in the or option,you must specify a country.

String[79]

Data.Country


Data.FirmName

StreetString[79]

Data.Street

NumberBuilding[79]

Data.Number




BuildingString[79]

Data.Building

SubBuildingString[79]

Data.SubBuilding

DeliveryServiceString[79]

Data.DeliveryService

Use these fields if the input address is completely unparsedand you want ValidateAddressGlobal to attempt to parse theaddress into the appropriate fields. For example:

String[79]

Data.UnformattedLine1throughData.UnformattedLine10

UnformattedLine1: 17413 Blodgett RoadUnformattedLine2: PO Box 123UnformattedLine3: Mount Vernon WA 97273UnformattedLine4: USA

This address would be parsed into these output fields:

AddressLine1: 17413 Blodgett RoadAddressLine2: PO Box 123City: Mount VernonStateProvice: WAPostalCode: 97273Country: USA

If you specify input in the unformatted line fields youmust specify the entire address using only

Note:

unformatted line fields. Do not use other fields suchas City or StateProvince in combination withunformatted line fields.

Parameters for OptionsInput Options

Table 79: ValidateAddressGlobal Input Options

Description/Valid ValuesParameter

Specifies the database resource containing the postal data to use for addressvalidation. Only databases that have been defined in the Global Database

Option.Database.AddressGlobal

Resources panel in the Management Console are available. For moreinformation, see the Spectrum™ Technology Platform Administration Guide.

Specifies a default country to use when the input record does not containexplicit country information. Specify the country using the ISO3 country code.

Option.Input.DefaultCountryISO3

If you do not specify a default country each input record must have the countryspecified in the Country input field. For a list of ISO codes see Country ISOCodes and Module Support on page 234.

Causes address records to be always treated as originating from the countryspecified here, overriding the country in the address record and the default

Option.Input.ForceCountryISO3

country. Specify the country using the ISO3 country code. For a list of ISOcodes, see Country ISO Codes and Module Support on page 234.



Description/Valid ValuesParameter

Enables you to use non-standard formatting for multi-line addresses in inputfiles. Acceptable values for this field include the following:

Option.Input.FormatDelimiter

• CRLF (default)• LF• CR• SEMICOLON ( 2101 MASSACHUSETTS AVE NW ; WASHINGTON DC20008)

• COMMA (2101 MASSACHUSETTS AVE NW , WASHINGTON DC 20008)

• TAB (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008 )• PIPE (2101 MASSACHUSETTS AVE NW | WASHINGTON DC 20008 )• SPACE (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008)

The same value must be selected for both the input option and outputoption.

Note:

Output Options

Table 80: ValidateAddressGlobal Output Options


This option specifies the maximum number of candidate addresses toreturn. The default is 1. The maximum is 20. If you are using

Option.Result.MaximumResults

FastCompletion mode, you may want to enter a number greater than 1to ensure you are provided with multiple options for completing a field.

Specifies whether to include the input data in the output. If enabled, theoutput will contain fields that end with .Input containing the corresponding

Option.Result.IncludeInputs

input field. For example, the output field AddressLine1.Input wouldcontain the data specified in the input field AddressLine1.

Include the input data in the output.TRUE

Do not include the input data in the output(default).

FALSE

Specifies the format for the StateProvince field. One of the following.Option.Result.StateProvinceType

Return the abbreviation for the state orprovince. For example, North Carolina wouldbe returned as "NC".

ABBREVIATION

Return either the abbreviation or the fullname depending on the format used by thecountry's postal authority. (Default)

COUNTRY_STANDARD

Return the full name of the state or province,not the abbreviation. For example "NorthCarolina".

EXTENDED

Specifies the language or code to use for the country name returned byValidateAddressGlobal.

Option.Result.CountryType




The two-character ISO code for thecountry

ISO2

The three-character ISO code forthe country

ISO3

The ISO country numberISO_NUMBER

ChineseNAME_CN

DanishNAME_DA

GermanNAME_DE

English (default)NAME_EN

SpanishNAME_ES

FinnishNAME_FI

FrenchNAME_FR

GreekNAME_GR

HungarianNAME_HU

ItalianNAME_IT

JapaneseNAME_JP

KoreanNAME_KR

DutchNAME_NL

PolishNAME_PL

PortugueseNAME_PT

RussianNAME_RU

SanskritNAME_SA

SwedishNAME_SE

Specifies the alphabet in which the output should be returned. Thealphabet in which the data is returned differs from country to country.

Option.Result.PreferredScript

For most countries the output will be Latin I regardless of the selectedpreferred language.

ASCII characters with expansion of specialcharacters (e.g. Ã– = OE)

ASCII_Extended

ASCII charactersASCII_Simplified

(default) Latin I or ASCII characters (as perreference database standard)

Database

Latin I charactersLatin

Latin I characters (alternative transliteration)Latin_Alt

Latin I or ASCII characters (local postaladministration alternative)

Postal_Admin_Alt

Latin I or ASCII characters (as preferred bylocal postal administration)

Postal_Admin_Pref




For countries that use an alphabet other than Latin I, the returnedalphabet differs from country to country. For more information, seeAlphabets for Non-Latin 1 Countries on page 187.

Specifies the language in which the output should be returned. Thealphabet in which the data is returned differs from country to country,

Option.Result.PreferredLanguage

but for most countries the output will be Latin, regardless of the selectedpreferred language.

Language derived from reference data for eachaddress. Default.

DATABASE

English locality and state/province names output,if available.

ENGLISH

Specifies the casing of the output.Option.Result.Casing

Output will be based on the reference databasestandard.

NATIVE

Output will be in upper case for all countries.UPPER

Output will be in lower case for all countries.LOWER

Casing determined by country-specific rules.MIXED

For parse mode, returns the data the way it wasentered. For validation mode, uses the casing found

NOCHANGE

in the reference data and according to postal rules.Values that could not be checked against thereference data will retain their input casing.

Enables you to use non-standard formatting for multi-line addresses inthe output. Acceptable values for this field include the following:

Option.Result.FormatDelimiter

• CRLF (default)• LF• CR• SEMICOLON ( 2101 MASSACHUSETTS AVE NW ; WASHINGTONDC 20008)

• COMMA (2101 MASSACHUSETTS AVE NW , WASHINGTON DC20008 )

• TAB (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008)

• PIPE (2101MASSACHUSETTSAVENW |WASHINGTONDC 20008)

• SPACE (2101 MASSACHUSETTS AVE NW WASHINGTON DC20008)

The same value must be selected for both the input option andoutput option.

Note:

Alphabets for Non-Latin 1 Countries

For countries that use an alphabet other than Latin I, the returned alphabet differs from country to country.The following table shows how the output is returned for specific countries. All countries that are notlisted use the value specified in the field option.



LatinDatabaseCountry

CYRILLIC_ISO+ LATIN

CYRILLIC_ISO+LATIN_SIMPLE

CYRILLIC_BGNCYRILLIC_ISOCyrillicCyrillicCyrillicRUS

JAPANESE+ LATIN

JAPANESE+LATIN_SIMPLE

JAPANESEJAPANESEKanaKanjiKanjiJPN

CHINESE_MANDARIN+ LATIN

CHINESE_MANDARIN+LATIN_SIMPLE

CHINESE_CANTONESE

CHINESE_MANDARIN

HanziHanziHanziCHN

CHINESE_CANTONESE+ LATIN

CHINESE_CANTONESE+LATIN_SIMPLE

CHINESE_MANDARIN

CHINESE_CANTONESE

HanziHanziHanziHKG

CHINESE_CANTONESE+ LATIN

CHINESE_CANTONESE+LATIN_SIMPLE

CHINESE_MANDARIN

CHINESE_CANTONESE

HanziHanziHanziTWN

GREEK_ISO+ LATIN

GREEK_ISO+LATIN_SIMPLE

GREEK_BGNGREEK_ISOGreekGreekGreekGRC

KOREAN +LATIN

KOREAN +LATIN_SIMPLE

KOREANKOREANHanjaHangulLatinKOR

HEBREW +LATIN

HEBREW +LATIN_SIMPLE

HEBREWHEBREWHebrewHebrewLatinISR

LATINLATIN_SIMPLELatin-3Latin-3Latin-3Latin-3Latin-3ROM

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2POL

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2CZE

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2CRI

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2HUN

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2MDA

LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2SVK

LATINLATIN_SIMPLELatin-7Latin-7Latin-7Latin-7Latin-7LAT

Process Options

Table 81: ValidateAddressGlobal Process Options


Use this option to set the appropriate balance between processing speedand quality. One of the following:

Option.Process.OptimizationLevel

The parser will honor input assignment strictly, with theexception of separation of House Number from Streetinformation.

NARROW




The parser will separate address element more actively asfollows:

STANDARD

• Province will be separated from Locality information• PostalCode will be separated from Locality information• House Number will be separated from Street information• SubBuilding will be separated from Street information• DeliveryService will be separated from Street information• SubBuilding will be separated from Building information• Locality will be separated from PostalCode information

Parser separation will happen similarly to Standard, butadditionally up to 10 parsing candidates will be passed to

WIDE

validation for processing. Validation will widen its search treeand take additional reference data entries into account formatching.

Please note that adjusting the optimization level might have no effect forcountries that lack the postal reference data information required for the kindof separation described above.

Increasing separation granularity from Narrow to Standard consumes someprocessing power, but themajor impact on processing speed is from validationprocessing a larger search tree, thus increasing the number of data accessesand comparisons for the optimization level Wide, in an attempt to make themost out of the input data given.

Specifies the type of processing to perform on the addresses. One of thefollowing:

Option.Process.Mode

Use this mode in batch processing environments whenno human input or selection is possible. It is optimized

BATCH

for speed and will terminate its attempts to correct anaddress when ambiguous data is encountered thatcannot be corrected automatically. The Batchprocessing mode will fall back to Parse mode whenthe database is missing for a specific country.

Use this mode in batch processing environments forAustralian mail. Validate Address Global is certified

CERTIFIED

by Australia Post's AddressMatching Approval System(AMAS). It will standardize and validate your mailagainst the Postal Address File, providing postaldiscounts and allowing for the least amount ofundeliverable pieces.

Use this mode if you want to use FastCompletionmode to enter truncated data in address fields and

FASTCOMPLETION

have Validate Address Global generate suggestions.For example, if you work in a call center orpoint-of-sale environment, you can enter just part ofan address element and the FastCompletion featurewill provide valid options for the complete element.

Use this mode when working in interactiveenvironments to generate suggestions when an

INTERACTIVE

address input is ambiguous. This validation type is




especially useful in data entry environments whencapturing data from customers or prospects. It requiresthe input of an almost-complete address and willattempt to validate or correct the data provided. Ifambiguities are detected, this validation type willgenerate up to 20 suggestions that can be used forpick lists. The Interactive processing mode will fallback to Parse mode when the respective database ismissing for a specific country.

Use this mode for separating address input into tokensfor subsequent processing in other systems, bypassing

PARSE

validation. For example, you could use this mode whenaddress data of already high quality simply needs tobe tokenized quickly for export to an external systemor for use by a downstream stage.

Specifies how closely an address must match the reference data in order forthe address to be validated. One of the following:

Option.Process.MatchingScope

These settings may not have an effect for countries lacking thenecessary level of detail in the postal reference data.

Note:

All address elements must match.ALL

Validate Global Address must achieve a matchon StateProvince, PostalCode,

DELIVERYPOINT_LEVEL

City/Locality/Suburb, street, house number, andsub building.

Validate Global Address must achieve a matchon StateProvince, PostalCode,City/Locality/Suburb, and street.

STREET_LEVEL

Validate Global Address must achieve a matchon StateProvince, PostalCode, andCity/Locality/Suburb.

LOCALITY_LEVEL

Response

Address Data

Table 82: Parsed Address Elements


The AddressBlock output fields contain a formatted version of thestandardized or normalized address as it would be printed on a physical

AddressBlock1-9

mailpiece. Validate Address Global formats the address into addressblocks using postal authority standards. Each line of the address isreturned in a separate address block field. There can be up to nineaddress block output fields: AddressBlock1 through AddressBlock9. Forexample, this input address:




AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600City: LanhamStateProvince: MDPostalCode: 20706


AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882

If the address was validated, the address line fields contain the validatedand standardized address lines. If the address could not be validated,

AddressLine1-6

the address line fields contain the input address without any changes.Note that the last line of the address is contained in the LastLine field.For example:

AddressLine1: 4200 PARLIAMENT PL STE 600LastLine: LANHAM MD 20706-1882

An area smaller than a state/province but larger than a city.AdministrativeDistrict

The flat or unit type (such as STE or APT), for example: 123 E Main StApt 3

ApartmentLabel

The flat or unit number, for example: 123 E Main St Apt 3ApartmentNumber

An estate or block name.BlockName

The name of a building, for example Sears Tower.BuildingName

The name of the town or city. For example, Vancouver, BC.City

Additional information about the city.City.AddInfo

A code used by the postal authority to speed up delivery in certaincountries for large localities, for example Prague or Dublin.

City.SortingCode

The name of the addressee. For example, Mr. Jones.Contact

The country in the language or code specified in the option.Country

Dependent state or province information that further subdivides a stateor province. An example would be a U.S. county.

County

The name of a company.FirmName

Information that further subdivides a building, e.g. the suite or apartmentnumber. For example: 123 E Main St Apt 3, 4th Floor

Floor

The house number 1, for example: 298A-1B New South Head RdHouseNumber

Complete last address line (city, state/province, and postal code).LastLine

Street directional that precedes the street name. For example, the N in138 N Main Street.

LeadingDirectional

Dependent place name that further subdivides a Locality. Examples arecolonias in Mexico, Urbanisaciones in Spain.

Locality

Post Box descriptor (POBox, Postfach, Case Postale etc.) and number.POBox

The postcode for the address. The format of the postcode varies bycountry.

PostalCode




The second part of a postcode. For example, for Canadian addressesthis will be the LDU. For U.S. addresses this is the ZIP + 4 add on. Thisfield is not used by most countries.

PostalCode.AddOn

The base portion of the postcode.PostalCode.Base

A room number in a building.Room

The name of a secondary street or rural route.SecondaryStreet

The name of the state or province.StateProvince

The name of street where property is located, for example: 123 E MainSt Apt 3

StreetName

The street suffix, for example: 123 E Main St Apt 3StreetSuffix

A portion of a building, such as a suite. For example, Suite 102.SubBuilding

Dependent place name that further subdivides a Locality. An examplewould be Mahalle in Turkey.

Suburb

The name of a territory. Territories are larger than a state/province.Territory

The trailing directional, for example: 123 Pennsylvania Ave NWTrailingDirectional

Original Input DataThis option outputs the original input data in <FieldName>.Input fields.

Table 83: Original Input Data



AddressLine1.Input


AddressLine2.Input


AddressLine3.Input


AddressLine4.Input


AddressLine5.Input


AddressLine6.Input

City nameString[79]

City.Input

State or provinceString[79]

StateProvince.Input




The postal code for the address. In the U.S. this is the ZIPCode. One of these formats:

String[79]:

PostalCode.Input

9999999999-9999A9A9A9A9A 9A99999 999

The name of the addressee. For example, "Mr. Jones".String[79]

Contact.Input

Specify the country using the format you chose for inputcountry format (English name, ISO code, or UPU code). For

String[79]

Country.Input

a list of valid values, see Country ISO Codes and ModuleSupport on page 234.


FirmName.Input

StreetString[79]

Street.Input

NumberBuilding[79]

Number.Input

BuildingString[79]

Building.Input

SubBuildingString[79]

SubBuilding.Input

DeliveryServiceString[79]

DeliveryService.Input

Result CodesThese output fields contain information about the result of the validation processing.

Table 84: Result Codes

Result CodeResponse Element

For United States and Canada addresses only, the AddressType fieldindicates the type of address. One of the following:

AddressType

The address was validated/corrected to the firm name.F

The address was validated/corrected to the building name.B

The address is a general delivery address.G

The address was validated/corrected to the high-rise default.H

The address is a large volume receiver.L

The address is a military address.M




The address was validated/corrected to PO box.P

The address was validated/corrected to a rural route.R

The address was validated/corrected to a street address.S

The address could not be validated/corrected so the type isunknown.

U

The level of confidence assigned to the address being returned. Range isfrom zero (0) to 100; zero indicates failure, 100 indicates a very high level ofconfidence that the match results are correct.

Confidence

Indicates whether the number of candidate addresses exceeds the numberreturned. One of the following:

CountOverflow

Yes, there are additional candidate addresses. To obtain theadditional candidates, increase the value.

Yes

No, there are no additional candidates.No

ElementInputStatus provides per element information on the matching ofinput elements to reference data. The values in this field vary depending on

ElementInputStatus

whether you are using batch mode or parse mode. For information about thevalue in this field, see Interpreting ElementInputStatus,ElementResultStatus, and ElementRelevance on page 196.

Indicates which address elements are actually relevant from the local postalauthority's point of view. For information about the value in this field, see

ElementRelevance

Interpreting ElementInputStatus, ElementResultStatus, andElementRelevance on page 196.

ElementResultStatus categorizes the result in more detail than theProcessStatus field by indicating if and how the output fields have been

ElementResultStatus

changed from the input fields. For information about the value in this field,see Interpreting ElementInputStatus, ElementResultStatus, andElementRelevance on page 196.

An estimate of how likely it is that mail sent to the address would be successfuldelivered. One of the following:

MailabilityScore

Completely confident of deliverability5

Almost certainly deliverable4

Should be deliverable3

Fair chance2

Risky1

No chance0

Indicates the processing mode used. The processing mode is specified inthe option. For a description of the modes, see Process Options on page188.

ModeUsed

If the address was matched to multiple candidate addresses in the referencedata, this field contains the number of candidate matches found.

MultimatchCount

Provides a general description of the output quality. For a more detaileddescription of the output quality, see the ElementResultStatus field.

ProcessStatus





Verified. The input data is correct. All elements were checkedand input matched perfectly.

V4

Verified. The input data is correct on input but some or allelements were standardized or the input contains outdatednames or exonyms.

V3

Verified. The input data is correct but some elements could notbe verified because of incomplete reference data.

V2

Verified. The input data is correct but the user standardizationhas deteriorated deliverability (wrong element user

V1

standardization - for example, postcode length chosen is tooshort). Not set by validation.

Corrected. All elements have been checked.C4

Corrected, but some elements could not be checked.C3

Corrected, but delivery status unclear (lack of reference data).C2

Corrected, but delivery status unclear because userstandardization was wrong. Not set by validation.

C1

Data could not be corrected completely, but is very likely to bedeliverable. Single match (e.g. HNO is wrong but only 1 HNOis found in reference data).

I4

Data could not be corrected completely, but is very likely to bedeliverable. Multiple matches (e.g. HNO is wrong but more than1 HNO is found in reference data).

I3

Data could not be corrected, but there is a slim chance that theaddress is deliverable.

I2

Data could not be corrected and is unlikely to be delivered.I1

Country recognized from the Force country SettingRA

Country recognized from DefaultCountryISO3 SettingR9

Country recognized from name without errorsR8

Country recognized from name with errorsR7

Country recognized from territoryR6

Country recognized from provinceR5

Country recognized from major townR4

Country recognized from formatR3

Country recognized from scriptR2

Country not recognized - multiple matchesR1

Country not recognizedR0

Parsed perfectlyS4

Parsed with multiple resultsS3

Parsed with errors. Elements change position.S2

Parse Error. Input Format Mismatch.S1




Validation Error: No validation performed because country wasnot recognized.

N1

Validation Error: No validation performed because requiredreference database is not available.

N2

Validation Error: No validation performed because country couldnot be unlocked.

N3

Validation Error: No validation performed because referencedatabase is corrupt or in wrong format.

N4

Validation Error: No validation performed because referencedatabase is too old.

N5

Validation Error: No validation performed because input datawas insufficient.

N6

FastCompletion Status: Suggestions are available - completeaddress.

Q3

FastCompletion Status: Suggested address is complete butcombined with elements from the input (added or deleted).

Q2

FastCompletion Status: Suggested address is not complete(enter more information).

Q1

FastCompletion Status: Insufficient information provided togenerate suggestions.

Q0

Reports the success or failure of the processing attempt.Status

Successnull

FailureF

The reason for the failure, if there was one.Status.Code

A description of the reason for the failure, if there was one.Status.Description

Interpreting ElementInputStatus, ElementResultStatus, and ElementRelevance

The ElementInputStatus, ElementResultStatus, and ElementRelevance output fields contain a series ofdigits that describe the outcome of the validation operation in detail. ElementInputStatus contains someinformation for parsing operations.

This is what an ElementInputStatus value looks like:

44606040600000000060

This is what an ElementResultStatus value looks like:

88F0F870F00000000040

This is what an ElementRelevance value looks like:

11101010100000000000

To understand the values in these fields you need to know which element each position represents, andthe meaning of the values in each position. For example, the first digit indicates the result from thePostalCode.Base output field. The position meanings are listed below.

• Position 1—PostalCode.Base• Position 2—PostalCode.AddOn



• Position 3—City• Position 4—Locality and Suburb• Position 5—StateProvice• Position 6—County• Position 7—StreetName• Position 8—SecondaryStreet• Position 9—HouseNumber• Position 10—Number level 1• Position 11—POBox• Position 12—Delivery service level 1• Position 13—Building level 0• Position 14—BuildingName• Position 15—Sub building level 0• Position 16—Floor and Room• Position 17—FirmName• Position 18—Organization level 1• Position 19—Country• Position 20—Territory

For ElementInputStatus, the possible values for validation are:

• 0—Empty• 1—Not found• 2—Not checked (no reference data)• 3—Wrong - Set by validation only: The reference database suggests that either Number orDeliveryService is out of valid number range. Input is copied, not corrected for batchmode, for interactivemode and FastCompletion suggestions are provided.

• 4—Matched with errors in this element• 5—Matched with changes (inserts and deletes) For example:

• Parsing: Splitting of house number for "MainSt 1"• Validation: Replacing input that is an exonym or dropping superfluous fielded input that is invalidaccording to the country reference database

• 6—Matched without errors

For ElementInputStatus, the possible values for parsing are:

• 0—Empty• 1—Element had to be relocated• 2—Matched but needed to be normalized• 3—Matched

For ElementRelevance, the possible values for parsing are:

• 0—Empty• 1—Element had to be relocated• 2—Matched but needed to be normalized• 3—Matched

For ElementResultStatus, the possible values are (for all address elements apart from country):

• 0—Empty• 1—Not validated and not changed. Original is copied.• 2—Not validated but standardized.• 3—Validated but not changed due to invalid input, database suggests that number is out of validranges. Input is copied, not corrected - this status value is only set in batch mode.



• 4—Validated but not changed due to lack of reference data.• 5—Validated but not changed due to multiple matches. Only set in batch mode, otherwise multiplesuggestions that replace the input are marked as corrected (status value 7).

• 6—Validated and changed by eliminating the input value• 7—Validated and changed due to correction based on reference data• 8—Validated and changed by adding value based on reference data• 9—Validated, not changed, but delivery status not clear (e.g. DPV value wrong; given number rangesthat only partially match reference data).

• C—Validated, verified but changed due to outdated name• D—Validated, verified but changed from exonym to official name• E—Validated, verified but changed due to standardization based on casing or language. Validationonly sets this status if input fully matches a language alternative.

• F—Validated, verified and not changed due to perfect match

For Country (position 19 & 20), the following values are possible:

• 0—Empty• 1—Country not recognized• 4—Country recognized from DefaultCountryISO3 setting• 5—Country not recognized - multiple matches• 6—Country recognized from script• 7—Country recognized from format• 8—Country recognized from major town• 9—Country recognized from province• C—Country recognized from territory• D—Country recognized from name with errors• E—Country recognized from name without errors• F—Country recognized from ForceCountryISO3 setting

ValidateAddressLoqateValidateAddressLoqate standardizes and validates addresses using postal authority address data.ValidateAddress Loqate can correct information and format the address using the format preferred bythe applicable postal authority. It also adds missing postal information, such as postal codes, city names,state/province names, and so on.

ValidateAddressLoqate also returns result indicators about validation attempts, such as whether or notValidateAddressLoqate validated the address, the level of confidence in the returned address, the reasonfor failure if the address could not be validated, and more.

During address matching and standardization, ValidateAddressLoqate separates address lines intocomponents and compares them to the contents of the Universal Addressing Module databases. If amatch is found, the input address is standardized to the database information. If no database match isfound, ValidateAddressLoqate optionally formats the input addresses. The formatting process attemptsto structure the address lines according to the conventions of the appropriate postal authority.

ValidateAddressLoqate is part of the Universal Addressing Module.

Resource URL

JSON endpoint:

http://server:port/rest/ValidateAddressLoqate/results.json

XML endpoint:

http://server:port/rest/ValidateAddressLoqate/results.xml





http://myserver:8080/rest/ValidateAddressLoqate/results.json?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY


{"output_port": [{"Confidence": "95","CouldNotValidate": "","ProcessedBy": "LOQATE","MatchScore": "100.0","AddressLine1": "1 Global Vw","AddressLine2": "","City": "Troy","StateProvince": "NY","PostalCode": "12180-8371","Country": "United States","FirmName": "","PostalCode.Base": "12180","PostalCode.AddOn": "8371","user_fields": []

}]}



http://myserver:8080/rest/ValidateAddressLoqate/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY


<ns2:xml.ValidateAddressLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddressLoqate">


<ns2:Confidence>95</ns2:Confidence><ns2:CouldNotValidate/><ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:MatchScore>100.0</ns2:MatchScore><ns2:AddressLine1>1 Global Vw</ns2:AddressLine1><ns2:AddressLine2/><ns2:City>Troy</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>12180-8371</ns2:PostalCode><ns2:PostalCode.Base>12180</ns2:PostalCode.Base><ns2:PostalCode.AddOn>8371</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:FirmName/><ns2:user_fields/>


</ns2:xml.ValidateAddressLoqateResponse>

Request

Parameters for Input DataValidateAddressLoqate takes an address as input. All addresses use this format regardless of theaddress's country. See Address Line Processing for U.S. Addresses on page 200 for importantinformation about how address line data is processed for U.S. addresses.





The first address line.StringData.AddressLine1

The second address line.StringData.AddressLine2

The third address line.StringData.AddressLine3

The fourth address line.StringData.AddressLine4

The city name.StringData.City

The country code or name, in any of the following formats:StringData.Country

• Two-character ISO 3116-1 Alpha-2 country code• Three-character ISO 3116-1 Alpha-3 country code• English country name

For a list of ISO codes, seeCountry ISO Codes and ModuleSupport on page 234.

The company or firm name.StringData.FirmName

The postal code for the address in one of the followingformats:

StringData.PostalCode

9999999999-9999A9A9A9A9A 9A99999 999

The state or province.StringData.StateProvince

Address Line Processing for U.S. Addresses

The input fields AddressLine1 through AddressLine4 are handled differently for U.S. addresses dependingon whether the firm name extraction or urbanization code extraction options are enabled. If either ofthese options is enabled, ValidateAddressLoqate will look at the data in all four fields to validate theaddress and extract the requested data (firm name and/or urbanization code). If neither of these optionsis enabled, ValidateAddressLoqate uses only the first two non-blank address line fields in its validationattempt. The data in the other address line fields is returned in the output field AdditionalInputData. Forexample,


In this address, if either firm name extraction or urbanization code extraction were enabled,ValidateAddressLoqate would examine all four address lines. If neither firm name extraction norurbanization code extraction were enabled, ValidateAddressLoqate would examine AddressLine1 andAddressLine3 (the first two non-blank address lines) and attempt to validate the address using that data;the data in AddressLine4 would be returned in the output field AdditionalInputData.

OptionsThe following table lists the options that control the type of information returned by ValidateAddressLoqate.



Table 86: Output Data Options


Specifies which database you want to use for validatinginternational addresses. To specify a database for


international address validation, select a database in theDatabase drop-down list.

Specifies whether to include field-level result indicators.Field-level result indicators describe how


ValidateAddressLoqate handled each address element.Field-level result indicators are returned in the qualifier"Result". For example, the field-level result indicator forHouseNumber is contained in HouseNumber.Result. For acomplete listing of result indicator output fields, see ResultIndicators on page 209.

No, do not output field-level return codes (default).N

Yes, output field-level return codes.Y

Specifies whether to return a formatted address when anaddress cannot be validated. The address is formatted using

Option.OutputFormattedOnFail

the preferred address format for the address's country. If thisoption is not selected, the output address fields are blankwhen ValidateAddressLoqate cannot validate the address.

This option applies only to U.S. and Canadianaddresses. Formatted data will not be returned forany other address.

Note:


Yes, format failed addresses.Y

Formatted addresses are returned using the format specifiedby theInclude a standard address, Include address lineelements, and Include postal information check boxes.Note that if you select Include address line elements, theparsed address elements will contain the parsed, validatedaddress for addresses that could be validated. If the addresscould not be validated the parsed address elements willcontain the input address in parsed form. If you always wantthe output to contain the input address in parsed form,regardless of whether or not ValidateAddressLoqate couldvalidate the address, select Include standardized inputaddress elements.

If you check this option, you must select Include a standardaddress and/or Include address line elements.

Formatted addresses are returned using the format specifiedby the OutputRecordType option. Note that if you specifyOutputRecordType=E, the parsed address elements willcontain the parsed, validated address for addresses thatcould be validated. If the address could not be validated theparsed address elements will contain the input address inparsed form. If you always want the output to contain theinput address in parsed form, regardless of whether or not




ValidateAddressLoqate could validate the address, specifyOutputRecordType=I.

If you specify Y, you must specify "A" and/or "E" forOutputRecordType.

Formatted addresses are returned using the format specifiedby the Option.OutputRecordType option. Note that if youspecify Option.OutputRecordType=E, the parsed addresselements will contain the parsed, validated address foraddresses that could be validated. If the address could notbe validated the parsed address elements will contain theinput address in parsed form. If you always want the outputto contain the input address in parsed form, regardless ofwhether or not ValidateAddressLoqate could validate theaddress, specify Option.OutputRecordType=I.

If you specify Y, you must specify "A" and/or "E" forOption.OutputRecordType.

Specifies whether to return a formatted version of the addressas it would be printed on a physical mailpiece. Each line of

Option.OutputAddressBlocks

the address is returned in a separate address block field.There can be up to nine address block output fields:AddressBlock1 through AddressBlock9.

For example, this input address:



AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882AddressBlock3: UNITED STATES OF AMERICA

ValidateAddressLoqate formats the address into addressblocks using postal authority standards. The country nameis returned using the Universal Postal Union country name.Note that the option does not affect the country name in theaddress block, it only affects the name returned in theCountry output field.

For addresses outside the U.S. and Canada, ifValidateAddressLoqate is unable to validate the address, noaddress blocks are returned. For addresses in the U.S. andCanada, address blocks are returned even if validation fails.


No, do not return address blocks. Default.N

Yes, return address blocks.Y







M



U

Specifies the default country. You should specify the countrywhere most of your addresses reside. For example, if most

Option.HomeCountry

of the addresses you process are in Canada, specify Canada.ValidateAddressLoqate uses the country you specify toattempt validation when it cannot determine the country fromthe StateProvince, PostalCode, and Country address fields.The valid country names are:

Afghanistan, Albania, Algeria, American Somoa, Andorra,Angola, Anguilla, Antigua And Barbuda, Argentina, Armenia,Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain,Bangladesh, Barbados, Belarus, Belgium, Belize, Benin,Bermuda, Bhutan, Bolivia, Bosnia And Herzegovina,Botswana, Brazil, British Virgin Islands, Brunei Darussalam,Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central AfricanRepublic, Chad, Chile, China, Colombia, Comoros Islands,Congo, Cook Islands, Costa Rica, Cote D'Ivoire, Croatia,Cuba, Cyprus, Czech Republic, Democratic Republic OfCongo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea,Eritrea, Estonia, Ethiopia, Falkland Islands, Faroe Islands,Federated States Of Micronesia, Fiji, Finland, France, FrenchGuiana, Gabon, Gambia, Germany, Ghana, Gibraltar, Greece,Greenland, Grenada, Guadeloupe, Guam, Guatemala,Guinea, Guinea Bissau, Guyana, Haiti, Holy See, Honduras,Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan,Kenya, Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia,Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania,Luxembourg, Macau, Macedonia, Madagascar, Malawi,Malaysia, Maldives, Mali, Malta, Marshall Islands, Martinique,Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar,Namibia, Nauru, Nepal, Netherlands Antilles, NewCaledonia,New Zealand, Nicaragua, Niger, Nigeria, Niue, Norway,Oman, Pakistan, Palau, Panama, Papua New Guinea,Paraguay, Peru, Philippines, Pitcairn Islands, Poland,Portugal, Puerto Rico, Qatar, Republic Of Georgia, RepublicOf Korea, Republic Of Singapore, Reunion, Romania, Russia,Rwanda, Saint Helena, Saint Kitts And Nevis, Saint Lucia,Saint Pierre And Miquelon, Saint Vincent And TheGrenadines, Samoa, San Marino, Sao Tome And Principe,Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri




Lanka, Sudan, Surivalue, Swaziland, Sweden, Switzerland,Syria, Tahiti, Taiwan, Tajikistan, Tanzania, Thailand, TheNetherlands, Togo, Tonga, Trinidad And Tobago, Tristan DaCunha, Tunisia, Turkey, Turkmenistan, Turks And CaicosIslands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan,Vanuatu, Venezuela, Vietnam, Virgin Islands (US), WallisAnd Futuna, Yemen, Yugoslavia, Zambia, Zimbabwe

Specifies the format to use for the country name returned inthe Country output field. For example, if you select English,


the country name "Deutschland" would be returned as"Germany".

Use English country names (default).E

Use two-letter ISO abbreviation for the countriesinstead of country names.

I

Use Universal Postal Union abbreviation for thecountries instead of country names.

U

Specifies the alphabet or script in which the output shouldbe returned. This option is bi-directional and generally takesplace from Native to Latin and Latin to Native.

Option.OutputScript

Do not perform transliteration and provideoutput in the same script as the input(default).

Input

Output in the native script for the selectedcountry wherever possible.

Native

Use English values.Latn

Indicates whether or not to return multiple address for thoseinput addresses that have more than one possible match.




For more information, see Returning Multiple Matches onpage 204.

Returning Multiple Matches

If ValidateAddressLoqate finds multiple address in the postal database that are possible matches forthe input address, you can have ValidateAddressLoqate return the possible matches. For example, thefollowing address matches multiple addresses in the U.S. postal database:

PO BOX 1 New York, NY

Options

To return multiple matches, use the options described in the following table.



Table 87: Multiple Match Option

Description/Valid Values

Indicates whether or not to return multiple address for those inputaddresses that have more than one possible match.

number between 1 and 10 that indicates the maximum number ofaddresses to return. The default value is 1.

The difference between and is that a multiple match will returna failure if, whereas a multiple match will return one record if.

Note:

To identify which output addresses are candidate addresses, you must.When you do this, records that are candidate addresses will have oneor more "M" values in the field-level result indicators.

Output

When you choose to return multiple matches, the addresses are returned in the address format youspecify. For information on specifying address format, seeOptions on page 200. To identify which recordsare the candidate addresses, look for multiple "M" values in the field-level result indicators. For moreinformationResult Indicators on page 209, see .

ResponseThe output from ValidateAddressLoqate contains various information depending on the output categoriesyou select.

Standard Address OutputStandard address output consists of four lines of the address which correspond to how the addresswould appear on an actual address label. City, state/province, postal code, and other data is also includedin standard address output. ValidateAddressLoqate returns standard address output for validatedaddresses if you. Standard address fields are always returned for addresses that could not be validatedregardless of whether or not you. For non-validated addresses, the standard address output fields containthe address as it appeared in the input ("pass through" data). If you want ValidateAddressLoqate tostandardize address according to postal authority standards when validation fails,.



Input data that could not be matched to a particular address component.For more information, see About Additional Input Data.

AdditionalInputData

If the address was validated, the first line of the validated andstandardized address. If the address could not be validated, the first

AddressLine1-4

line of the input address without any changes. There can be up to fouraddress block output fields: AddressLine1 through AddressLine4.

The validated city name.City


• ISO Code• UPU Code




• English

The validated firm or company name.FirmName

The validated ZIP Code™ or postal code.PostalCode

The 4-digit add-on part of the ZIP Code™. For example, in the ZIP Code™

60655-1844, 1844 is the 4-digit add-on.PostalCode.AddOn

The 5-digit ZIP Code™; for example 20706.PostalCode.Base

The validated state or province abbreviation.StateProvince

Parsed Address Elements OutputOutput addresses are formatted in the parsed address format if you. If you want ValidateAddressLoqateto return formatted data in the Parsed Address format when validation fails (that is, a normalized address),.

If you want ValidateAddressLoqate to always return parsed input data regardless of whether ornot validation is successful,. For more information, see Parsed Input on page 207.

Note:

Table 89: Parsed Address Output


The AddressBlock output fields contain a formattedversion of the standardized or normalized address

AddressBlock1-9

as it would be printed on a physical mailpiece.Validate Address Global formats the address intoaddress blocks using postal authority standards.Each line of the address is returned in a separateaddress block field. There can be up to nineaddress block output fields: AddressBlock1 throughAddressBlock9. For example, this input address:



AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882


ApartmentLabel

Apartment number. For example: 123 E Main StAPT 3

ApartmentNumber

Secondary apartment number. For example: 123E Main St APT 3, 4th Floor

ApartmentNumber2





Note:

Validated city nameCity

Country. Format is determined by what youselected in :

Country


The validated firm or company nameFirmName

House number, for example: 123 E Main St Apt 3HouseNumber


LeadingDirectional


POBox


PostalCode

Validated state or province nameStateProvince

Street name, for example: 123 E Main St Apt 3StreetName

Street suffix, for example: 123 E Main St Apt 3StreetSuffix


TrailingDirectional

Parsed InputThe output can include the input address in parsed form. This type of output is referred to as "parsedinput." Parsed input fields contain the address data that was used as input regardless of whether or notValidateAddress validated the address. Parsed input is different from the "parsed address elements"output in that parsed address elements contain the validated address if the address could be validated,and, optionally, the input address if the address could not be validated. Parsed input always containsthe input address regardless of whether or not ValidateAddress validated the address.

To include parsed input fields in the output,.

Table 90: Parsed Input



ApartmentLabel.Input

Apartment number, for example: 123 E Main StAPT 3

ApartmentNumber.Input

Validated city nameCity.Input




Country. Format is determined by what youselected in:

Country.Input


The validated firm or company nameFirmName.Input

House number, for example: 123 E Main St Apt 3HouseNumber.Input


LeadingDirectional.Input


POBox.Input


PostalCode.Input

Validated state or province nameStateProvince.Input

Street name, for example: 123 E Main St Apt 3StreetName.Input

Street suffix, for example: 123 E Main St Apt 3StreetSuffix.Input


TrailingDirectional.Input

Geocode OutputValidateAddressLoqate returns the latitude/longitude, geocoding match code, dependent and doubledependent localities, dependent thoroughfare, subadministrative and superadministrative areas, andthe search distance as output. Match codes describe how well the geocoder matched the input addressto a known address; they also describe the overall status of a match attempt. Search distance codesrepresent how close the geocode is to the actual physical location of an address. he output returned isin the DataTable class. For information on the DataTable class, see the "API Fundamentals" section .



This two-byte code reflects the status and level of geocode matchingfor an address.

Geocode.MatchCode

The first byte represents the geocoding status and is one of the following:

Multiple candidate geocodes were found to match the inputaddress, and an average of these was returned

A

A geocode was able to be interpolated from the inputaddresses location in a range

I

A single geocode was found matching the input addressP

A geocode was not able to be generated for the input addressU




The second byte represents the level of geocoding matching and is oneof the following:

Delivery point (post box or subbuilding)5

Premise or building4

Thoroughfare3

Locality2

Administrative area1

None0

Eight-digit number in degrees and calculated to five decimal places (inthe format specified).

Latitude

Eight-digit number in degrees and calculated to five decimal places (inthe format specified).

Longitude

The radius of accuracy in meters, providing an indication of the probablemaximum distance between the given geocode and the actual physical

SearchDistance

location. This field is derived from and dependent upon the accuracyand coverage of the underlying reference data.

Result IndicatorsResult indicators provide information about the kinds of processing performed on an address. There aretwo types of result indicators:

• Record-Level Result Indicators• Field-Level Result Indicators

Record-Level Result Indicators

Record-level result indicators provide data about the results of ValidateAddressLoqate processing foreach record, such as the success or failure of the match attempt, which coder processed the address,and other details. The following table lists the record-level result indicators returned byValidateAddressLoqate.

Table 92: Record Level Indicators


The level of confidence assigned to the address being returned. Rangeis from zero (0) to 100; zero indicates failure, 100 indicates a very high

Confidence

level of confidence that the match results are correct. For multiplematches, the confidence level is 0. For details about how this numberis calculated, see Introduction to the Validate Address ConfidenceAlgorithm on page 252.

If no match was found, which address component could not be validated:CouldNotValidate

• ApartmentNumber• HouseNumber• StreetName




• PostalCode• City• Directional• StreetSuffix• Firm• POBoxNumber


Note:

MatchScore provides an indication of the similarity between the inputdata and the closest reference data match. It is significantly different

MatchScore

from Confidence in that Confidence indicates how much the inputaddress changed to obtain a match, whereas the meaning of MatchScore varies between U.S. and non-U.S. addresses.

The int getFieldMatchscore (unit record, const char*) field is a decimalvalue between 0 and 100 that reflects the similarity between the identifiedinput data and the closest reference data match. A result of 100 indicatesthat no changes other than alias, casing, or diacritic changes have beenmade to the input data. A result of 0 indicates that there is no similaritybetween the input data and closest reference data match.

The Validate Address Loqate and Advanced Matching Modulecomponents both use the MatchScore field. The MatchScore

Note:

field value in the output of a dataflow is determined by the laststage to modify the value before it is sent to an output stage. Ifyou have a dataflow that contains Validate Address Loqate andAdvanced Matching Module components and you want to seethe MatchScore field output for each stage, use a Transformerstage to copy the MatchScore value to another field. Forexample, Validate Address Loqate produces an output fieldcalled MatchScore and then a Transformer stage copies theMatchScore field from Validate Address Loqate to a field calledAddressMatchScore. When the matcher stage runs it populatestheMatchScore field with the value from thematcher and passesthrough the AddressMatchScore value from Validate AddressLoqate.

Which address coder processed the address:ProcessedBy


Reports the success or failure of the match attempt. For multiplematches, this field is "F" for all the possible matches.

Status

Successnull

FailureF

Reason for failure, if there is one.Status.Code

• UnableToValidate

Description of the problem, if there is one.Status.Description

This value will appear ifStatus.Code=UnableToValidate.

Address Not Found



Field-Level Result Indicators

Field-level result indicators describe how ValidateAddressLoqate handled each address element.Field-level result indicators are returned in the qualifier "Result". For example, the field-level resultindicator for HouseNumber is contained in HouseNumber.Result.

To enable field-level result indicators, .

The following table lists the field-level result indicators. If a particular field does not apply to an address,the result indicator may be blank.

Table 93: Field-Level Result Indicators


ApartmentLabel.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A


Dropped. The field provided on input was removed. U.S. andCanadian addresses only. For more information, see AboutAdditional Input Data.

D

Formatted. The spacing and/or punctuation was changed toconform to postal standards.

F


P

The apartment label is required but is missing from the inputaddress. U.S. addresses only.

R




V

ApartmentNumber.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A


Dropped. The field provided on input was removed. U.S.addresses only. For more information, see About AdditionalInput Data.

D


F

Pass-through. The data was not used in the validation process,but it was preserved in the output. U.S. addresses that are an

P

EWS match will have a value of P. U.S. and Canadianaddresses only.

The apartment number is required but is missing from the inputaddress. U.S. addresses only.

R


S




Unmatched.U


V

City.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A


Hyphens missing or punctuation errors. Canadian addressesonly.

F


M



P

The city is required but is missing from the input address. U.S.addresses only.

R


S



V

These result codes do not apply to U.S. or Canadian addresses.Country.Result


M


S

Unmatched.U


V

FirmName.Result Corrected. U.S. addresses only.C

Pass-through. The data was not used in the validationprocess, but it was preserved in the output. U.S. and Canadianaddresses only.

P


Validated. The data was confirmed correct and remainedunchanged from input. U.S. addresses only.

V

HouseNumber.Result Appended. The field was added to a blank input field.Canadian addresses only.

A






D


F

Out of range. Does not apply to U.S. or Canadian addresses.O


P

The house number is required but is missing from the inputaddress. Canadian addresses only.

R


S

Unmatched.U


V

LeadingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A

Corrected. Non-blank input was corrected to a non-blank value.U.S. addresses only.

C


D


F


M


P


Unmatched.U

Validated. The data was confirmed correct and remainedunchanged from input. Does not apply to Canadian addresses.

V

POBox.Result Appended. The field was added to a blank input field. Canadianaddresses only.

A



D





F

Multiple matches. The input address matchedmultiple recordsin the postal database, and each matching record has adifferent value in this field. U.S. addresses only.

M


P

The P.O. Box number is required but is missing from the inputaddress. U.S. addresses only.

R


Unmatched.U


V

PostalCode.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



F

Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field. Does not apply to Canadian addresses.

M


P

The postal code is required but is missing from the inputaddress. U.S. addresses only.

R


S

Unmatched. For example, if the street name does not matchthe postal code, both StreetName.Result andPostalCode.Result will contain U.

U


V

PostalCode.Type The ZIP Code™ contains only PO Box addresses. U.S.addresses only.

P

The ZIP Code™ is a unique ZIP Code™ assigned to aspecific company or location. U.S. addresses only.

U

The ZIP Code™ is for military addresses. U.S. addressesonly.

M

The ZIP Code™ is a standard ZIP Code™.null




These result codes apply to U.S. addresses only.RRHC.Type

The address is a Highway Contract address.HC

The address is a Rural Route address.RR

StateProvince.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.

A

Corrected. U.S. addresses only.C


M



P

The state is required but is missing from the input address.U.S. addresses only.

R


S



V

These result codes apply to international addresses only.Street.Result


M


P

Street corrected. House number is out of range. Applies toUK and Japanese records only.

R


S

Unmatched.U


V

StreetName.Result Appended. The field was added to a blank input field. Canadianaddresses only.

A



D


F





M


P


S

Unmatched.U


V

StreetSuffix.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



D


F


M


P


Unmatched. Does not apply to U.S. addresses.U


V

TrailingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.

A



D


F


M


P







V

Universal Name Module

OpenNameParserOpenNameParser breaks down personal and business names and other terms in the name data fieldinto their component parts. These parsed name elements are then subsequently available to otherautomated operations such as namematching, name standardization, or multi-record name consolidation.

OpenNameParser does the following:

• Determines the type of a name in order to describe the function that the name performs. Name entitytypes are divided into two major groups: personal names and business names. Within each of thesemajor groups are subgroups.

• Determines the form of a name in order to understand which syntax the parser should follow for parsing.Personal names usually take on a natural (signature) order or a reverse order. Business names areusually ordered hierarchically.

• Determines and labels the component parts of a name so that the syntactical relationship of eachname part to the entire name is identified. The personal name syntax includes prefixes, first, middle,and last name parts, suffixes, and account description terms, among other personal name parts. Thebusiness name syntax includes the firm name and suffix terms.

• Parses conjoined personal and business names and either retains them as one record or splits theminto multiple records. Examples of conjoined names include "Mr. and Mrs. John Smith" and "BaltimoreGas & Electric dba Constellation Energy".

• Parses output as records or as a list.• Assigns a parsing score that reflects the degree of confidence that the parsing is correct.

Resource URL

JSON endpoint:

http://server:port/rest/OpenNameParser/results.json

XML endpoint:

http://server:port/rest/OpenNameParser/results.xml



http://myserver:8080/rest/OpenNameParser/results.json?Data.Name=John+Williams+Smith




{"output_port": [{"Name": "John Williams Smith","CultureCodeUsedToParse": "","FirstName": "John","LastName": "Smith","MiddleName": "Williams","Names": [],"IsParsed": true,"IsPersonal": true,"IsConjoined": false,"IsReverseOrder": false,"IsFirm": false,"NameScore": 100,"user_fields": []

}]}



http://myserver:8080/rest/OpenNameParser/results.xml?Data.Name=John+Williams+Smith


<ns2:xml.OpenNameParserResponsexmlns:ns2="http://www.pb.com/spectrum/services/OpenNameParser">


<ns2:Name>John Williams Smith</ns2:Name><ns2:CultureCodeUsedToParse/><ns2:FirstName>John</ns2:FirstName><ns2:LastName>Smith</ns2:LastName><ns2:MiddleName>Williams</ns2:MiddleName><ns2:Names/><ns2:IsParsed>true</ns2:IsParsed><ns2:IsPersonal>true</ns2:IsPersonal><ns2:IsConjoined>false</ns2:IsConjoined><ns2:IsReverseOrder>false</ns2:IsReverseOrder><ns2:IsFirm>false</ns2:IsFirm><ns2:NameScore>100</ns2:NameScore><ns2:user_fields/>


</ns2:xml.OpenNameParserResponse>

Request


Table 94: Open Name Parser Input


The culture of the input name data. The options are listed below.Data.CultureCode

Global culture (default).Null (empty)

German.de

Spanish.es

Japanese.ja




If you added your own domain using the Open Parser DomainEditor, the cultures and culture codes for that domain are alsovalid.

Note:

The name you want to parse. This field is required.Data.Name

OptionsParameters for Parsing Options

The following table lists the options that control the parsing of names.

Table 95: Open Name Parser Parsing Options


Specifies whether to parse names where the is inthe order Title, First Name, Middle Name, LastName, and Suffix.

Option.ParseNaturalOrderPersonalNames

Parse personal names that are innatural order.

true

Do not parse names that are innatural order.

false

Specifies whether to parse names where the lastname is specified first.

Option.ParseReverseOrderPersonalNames

Parse personal names that are inreverse order.

true

Do not parse names that are inreverse order.

false

Specifies whether to parse conjoined names.Option.ParseConjoinedNames

Parse conjoined names.true

Do not parse conjoined names.false

Specifies whether to separate names containingmore than one individual into multiple records, forexample, Bill & Sally Smith.

Option.SplitConjoinedNames

Split conjoined names.true

Do not split conjoined names.false

Specifies whether to parse business names.Option.ParseBusinessNames

Parse business names.true

Do not parse business names.false

Specifies whether to return the parsed nameelements in a list form.

Option.OutputAsList

Return the parsed elements in a listform.

true




Do not return the parsed elements ina list form.

false

Specifies how to balance performance versusquality. A faster performance will result in lower

Option.ShortcutThreshold

quality output; likewise, higher quality will result inslower performance. When this threshold is met,no other processing will be performed on therecord.

Specify a value from 0 to 100. The default is 100.

Parameters for Culture Options

The following table lists the options that control name cultures.

Table 96: Open Name Parser Cultures Options


Specifies which culture(s) you want to include in the parsing grammar.Global Culture is the default selection.

Option.DefaultCulture

Specify cultures by specifying the two-character culture code in acomma-separated list in priority order. For example, to attempt to parsethe name using the Spanish culture first then Japanese, you wouldspecify:

es,ja,,

Parameters for Advanced Options

The following table lists the advanced options for name parsing.

Table 97: Open Name Parser Advanced Options

DescriptionOption

Specifies the domain to use when parsing natural order personal names.The valid values are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.

Option.NaturalOrderPersonalNamesDomain

Specify a number between 1 and 5 that indicates the priority of thenatural order personal names domain relative to the other domains that

Option.NaturalOrderPersonalNamesPriority

you are using. This determines the order in which you want the parsersto run.

Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches thatthreshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.



DescriptionOption

Specifies the domain to use when parsing reverse order personal names.The valid values are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.

Option.ReverseOrderPersonalNamesDomain

Specify a number between 1 and 5 that indicates the priority of thereverse order personal names domain relative to the other domains that

Option.ReverseOrderPersonalNamesPriority

you are using. This determines the order in which you want the parsersto run.


Specifies the domain to use when parsing natural order conjoinedpersonal names. The valid values are the domain names defined in theOpen Parser Domain Editor too in Enterprise Designer.

Option.NaturalOrderConjoinedPersonalNamesDomain

Specify a number between 1 and 5 that indicates the priority of thenatural order conjoined personal names domain relative to the other

Option.NaturalOrderConjoinedPersonalNamesPriority

domains that you are using. This determines the order in which youwant the parsers to run.


Specifies the domain to use when parsing reverse order conjoinedpersonal names. The valid values are the domain names defined in theOpen Parser Domain Editor too in Enterprise Designer.

Option.ReverseOrderConjoinedPersonalNamesDomain

Specify a number between 1 and 5 that indicates the priority of thereverse order conjoined personal names domain relative to the other

Option.ReverseOrderConjoinedPersonalNamesPriority

domains that you are using. This determines the order in which youwant the parsers to run.


Specifies the domain to use when parsing business names. The validvalues are the domain names defined in the Open Parser Domain Editortoo in Enterprise Designer.

Option.BusinessNamesDomain

Specify a number between 1 and 5 that indicates the priority of thebusiness names domain relative to the other domains that you are using.This determines the order in which you want the parsers to run.

Option.BusinessNamesPriority

Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches that



DescriptionOption

threshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.

Response

Table 98: Open Name Parser Output


An account description that is part of the name. For example,in "Mary Jones Account # 12345", the account description is"Account#12345".

StringAccountDescription

A hierarchical field that contains a list of parsed elements.This field is returned when you check the Output results aslist box under Parsing Options.

StringNames

Fields Related to Names of Companies

Indicates that the name of a firm contains a conjunction suchas "d/b/a" (doing business as), "o/a" (operating as), and "t/a"(trading as).

StringFirmConjunction

The name of a company. For example, "Pitney Bowes".StringFirmName

The corporate suffix. For example, "Co." and "Inc."StringFirmSuffix

Indicates that the name is a firm rather than an individual.StringIsFirm

Fields Related to Names ofIndividual People

Indicates that the name contains a conjunction such as "and","or", or "&".

StringConjunction

The culture codes contained in the input data.StringCultureCode

Identifies the culture-specific grammar that was used to parsethe data.

StringCultureCodeUsedToParse

Global culture (default).Null (empty)

German.de

Spanish.es

Japanese.ja

If you added your own domain using the Open ParserDomain Editor, the cultures and culture codes forthat domain will appear in this field as well.

Note:

The first name of a person.StringFirstName

A person's general/professional suffix. For example, MD orPhD.

StringGeneralSuffix

Indicates whether an output record was parsed. Values aretrue or false.

StringIsParsed




Indicates whether the name is an individual rather than a firm.Values are true or false.

StringIsPersonal

Indicates whether the input name is in reverse order. Valuesare true or false.

StringIsReverseOrder

The last name of a person. Includes the paternal last name.StringLastName

Non-name information that appears before a name.StringLeadingData

A person's maturity/generational suffix. For example, Jr. orSr.

StringMaturitySuffix

The middle name of a person.StringMiddleName

The personal or firm name that was provided in the input.StringName.

Indicates the average score of known and unknown tokensfor each name. The value of NameScore will be between 0

StringNameScore

and 100, as defined in the parsing grammar. 0 is returnedwhen no matches are returned.

In Spanish parsing grammar, the surname of a person'smother.

StringSecondaryLastName

Information that appears before a name, such as "Mr.", "Mrs.",or "Dr."

StringTitleOfRespect

Non-name information that appears after a name.StringTrailingData

Fields Related to ConjoinedNames

Indicates that a second, conjoined name contains aconjunction such as "and", "or", or "&".

StringConjunction2

Indicates that a third, conjoined name contains a conjunctionsuch as "and", "or", or "&".

StringConjunction3

The name of a second, conjoined company. For example,Baltimore Gas & Electric dba Constellation Energy.

StringFirmName2

The suffix of a second, conjoined company.StringFirmSuffix2

The first name of a second, conjoined name.StringFirstName2

The first name of a third, conjoined name.StringFirstName3

The general/professional suffix for a second, conjoined name.For example, MD or PhD.

StringGeneralSuffix2

The general/professional suffix for a third, conjoined name.For example, MD or PhD.

StringGeneralSuffix3

Indicates that the input name is conjoined. An example of aconjoined name is "John and Jane Smith".

StringIsConjoined

The last name of a second, conjoined name.StringLastName2

The last name of a third, conjoined name.StringLastName3

Thematurity/generational suffix for a second, conjoined name.For example, Jr. or Sr.

StringMaturitySuffix2




The maturity/generational suffix for a third, conjoined name.For example, Jr. or Sr.

StringMaturitySuffix3

The middle name of a second, conjoined name.StringMiddleName2

The middle name of a third, conjoined name.StringMiddleName3

Information that appears before a second, conjoined name,such as "Mr.", "Mrs.", or "Dr."

StringTitleOfRespect2

Information that appears before a third, conjoined name, suchas "Mr.", "Mrs.", or "Dr."

StringTitleOfRespect3



Appendix

In this section:

• The ACR Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227• Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231• Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233• ValidateAddress Confidence Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

AThe ACR Code

In this section:

• The ACR Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228

The ACR CodeThe Address Correction Result (ACR) code describes what data has been changed in each record. Anexample of an ACR is:

L5-P0S0A5T1R0Z0C4-098

ACR codes consist of three parts:

• Validation Level• Component Status• Validation Match Score

Validation Level

The first two characters of the address correction result state the type and level of validation.

The first character, which is always alphabetic, specifies the type of validation:

• U—Unable to standardize address• C—Address is in component form• L—Address has been formatted into address lines• R—Address has been reverted and has not reached acceptable level

The second character, which is always numeric, specifies the level of validation. The higher the level,the better the validation will be. The levels that can be achieved are as follows:

• 0—No components validated• 1—Country only validated• 2—City and country validated• 3—City, postal code and country validated• 4—Street, city, postal code and country validated• 5—Premise number, building name, sub-building, PO box, company, street, city, postal code, andcountry validated.

Component Status

The second part of the ACR code gives the status of the main address components. The addresscomponents are identified as follows:

• Character 3-4: P—Premise/house number• Character 5-6: S—Street• Character 7-8: A—Subcity (city area)• Character 9-10: T—City• Character 11-12: R—Region/state• Character 13-14: Z—Postal code/ZIP Code®

• Character 15-16: C—Country

A number follows each component and can take one of the following values:

• 0—Not found/empty• 1—Derived using position in input data• 2—Recognized using the Address Now Module database• 3—Recognized and updated to standard form using the Address Now Module database• 4—Validated using Address Now Module database• 5—Updated/corrected using Address Now Module database• 6—Added using Address Now Module database• 7—Correctly empty


• 8—Partial recognition using Address Now Module database• 9—Needs correcting to match Address Now Module database

Validation Match Score

The Validation Match Score comprises characters 17-19, the final three digits of the ACR code. This isa comparison between the standardized data (in component format) and the suggested match returnedfrom the Address Now Module database.

This score is calculated by examining all fields returned from the Address Now Module database andcomparing them individually with the existing component data. The overall match score is then calculatedby combining these individual values into an average score, taking into account the match scoreweightings, which can be set from the address validation options dialog box. For example,

Input data:

AddressLine1: 11 High StreetCity: AnytownCountry: UK

Standardized data:

Premise: 11Street: High StreetCity: Anytown

When validated, the data returned from the Address Now Module database for this record may be:

Premise: 11Street: High StreetCity: AnytownPostal Code: ZZ9 9ZZ

Comparing the Address Now Module database to the standardized data we get:

• Premise: 100% match• Street: 100% match• City: 100% match• Postal Code: not used, because empty on input

Combining these percentages gives us a match score of 100%.

Another example may be:

Input data:

AddressLine1: bergerstrasse 12AddressLine2: munichAddressLine3: 80124Country: Germany

Standardized data:

Premise: 12Street: Bergerstr.City: MünchenPostal Code: 80124

Address Now Module database output:

Premise: 12Street: Burgerstr.City: MünchenPostal Code: 80142


Appendix A: The ACR Code

Comparing the Address Now Module database output to the standardized data we get:

• Premise:100% match• Street: 90% match (the actual figure is determined by a textual comparison of the two values)• City: 100% match• Postal Code: 80% match (because the numbers are transposed)

This gives an overall match score of 92% if the match score weightings are all set at 1. Increasing thematch score weighting of the postal code will decrease the match score, because the postal codecomponent score (80%) will be made more important in the calculation. Increasing the match scoreweighting of the city will increase the match score, because the city component score (100%) will bemade more important.

For example:

L5-P4S4A5T5R4Z4C4-098

• L shows that formatting has been carried out to create the address lines• The validation level is 5, meaning that the highest level of matching against the Address Now Moduledatabase was attained

• All component codes except subcity (A) and city (T) are set to 4 indicating that they were validatedusing the Address Now Module database

• The subcity code and city code are set to 5 indicating that these components were corrected usingthe Address Now Module database

The overall address matched the Address Now Module database at 98%.

You may also receive a value of "SDS" for the Validation Match Score. A return of SDS indicatesthat the address has not been standardized, possibly as a result of the address being reverted.

Note:


BBuffering

In this section:

• Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232

BufferingUse buffering to define areas that are close to the edges of a polygon, line, or point.

Buffered Point (circle)Buffered Line (corridor)Buffered Polygon (zone)

For example, if you work for an insurance company you may want to know if a potential customer's houseis within 500 feet of a flood plain so that you can suggest that they buy flood insurance even though theyare not actually within the flood plain. The following illustration shows this scenario using a bufferedpolygon. The dotted line indicates the boundary of the flood plain and the shaded area shows a 500-footbuffer zone around the boundary.

The buffer area extends on both sides of the boundary (inside and outside). When you use buffering,the output field BufferRelation indicates whether or not the point is in the buffered zone, and whetherthe point is inside or outside of the polygon, as shown in the following illustrations.

The point is outside the polygonbut in the buffer area.

The point is inside the polygonand in the buffer area.

The point is inside the polygonand not in the buffer area.

The output field BufferRelationwill contain "B".

The output field BufferRelationwill contain "I".

The output field BufferRelationwill contain "P".

Specify the size of polygon buffers using the BufferWidth input field to set it on a record-by-record basisand the option to set a default polygon buffer width for the job.


CCountry Codes

In this section:

• Country ISO Codes and Module Support . . . . . . . . . . . .234

Country ISO Codes and Module SupportThe following table lists the ISO codes for each country as well as the modules that support addressing,geocoding, and routing for each country.

Supported ModulesISO 3116-1Alpha-3

ISO 3116-1Alpha-2

ISO Country Name (English)

Address Now ModuleUniversal Addressing Module

AFGAFAfghanistan


ALAAXAland Islands


ALBALAlbania


DZADZAlgeria


ASMASAmerican Samoa

Address Now ModuleEnterprise Geocoding Module1


ANDADAndorra

Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module

AGOAOAngola


AIAAIAnguilla


ATAAQAntarctica


ATGAGAntigua And Barbuda


ARGARArgentina


ARMAMArmenia


ABWAWAruba

Address Now ModuleEnterprise Geocoding Module

AUSAUAustralia

Enterprise Routing ModuleUniversal Addressing Module

1 Andorra is covered by the Spain geocoder



ISO 3116-1Alpha-2



AUTATAustria



AZEAZAzerbaijan


BHSBSBahamas


BHRBHBahrain


BGDBDBangladesh


BRBBBBarbados


BLRBYBelarus


BELBEBelgium



BLZBZBelize


BENBJBenin


BMUBMBermuda


BTNBTBhutan


BOLBOBolivia, Plurinational State Of


BESBQBonaire, Saint Eustatius AndSaba


BIHBABosnia And Herzegovina


BWABWBotswana


Appendix C: Country Codes


ISO 3116-1Alpha-2



BVTBVBouvet Island


BRABRBrazil



IOTIOBritish Indian Ocean Territory


BRNBNBrunei Darussalam


BGRBGBulgaria


BFABFBurkina Faso


BDIBIBurundi


KHMKHCambodia


CMRCMCameroon


CANCACanada



CPVCVCape Verde


CYMKYCayman Islands


CAFCFCentral African Republic


TCDTDChad


CHLCLChile



ISO 3116-1Alpha-2



CHNCNChina


CXRCXChristmas Island


CCKCCCocos (Keeling) Islands


COLCOColombia


COMKMComoros


COGCGCongo


CODCDCongo, The DemocraticRepublic Of The


COKCKCook Islands


CRICRCosta Rica


CIVCICôte d'Ivoire


HRVHRCroatia


CUBCUCuba


CUWCWCuracao


CYPCYCyprus


CZECZCzech Republic


DNKDKDenmark





ISO 3116-1Alpha-2



DJIDJDjibouti


DMADMDominica


DOMDODominican Republic


ECUECEcuador


EGYEGEgypt


SLVSVEl Salvador


GNQGQEquatorial Guinea


ERIEREritrea


ESTEEEstonia


ETHETEthiopia


FLKFKFalkland Islands (Malvinas)


FROFOFaroe Islands


FJIFJFiji


FINFIFinland



FRAFRFrance


Address Now ModuleEnterprise Geocoding Module 2


GUFGFFrench Guiana

2 French Guiana is covered by the France geocoder



ISO 3116-1Alpha-2



PYFPFFrench Polynesia


ATFTFFrench Southern Territories


GABGAGabon


GMBGMGambia


GEOGEGeorgia


DEUDEGermany



GHAGHGhana

Address Now ModuleEnterprise GeocodingModule 3UniversalAddressing Module

GIBGIGibraltar


GRCGRGreece


GRLGLGreenland


GRDGDGrenada



GLPGPGuadeloupe


GUMGUGuam


GTMGTGuatemala


GGYGGGuernsey

3 Gibraltar is covered by the Spain geocoder4 Guadeloupe is covered by the France geocode




ISO 3116-1Alpha-2



GINGNGuinea


GNBGWGuinea-Bissau


GUYGYGuyana


HTIHTHaiti


HMDHMHeard Island and McDonaldIslands



VATVAHoly See (Vatican City State)


HNDHNHonduras


HKGHKHong Kong


HUNHUHungary


ISLISIceland


INDINIndia


IDNIDIndonesia


IRNIRIran, Islamic Republic Of


IRQIQIraq


IRLIEIreland


5 The Vatican is covered by the Italy geocoder



ISO 3116-1Alpha-2



IMNIMIsle Of Man


ISRILIsrael


ITAITItaly



JAMJMJamaica


JPNJPJapan


JEYJEJersey


JORJOJordan


KAZKZKazakhstan


KENKEKenya


KIRKIKiribati


PRKKPKorea, Democratic People'sRepublic Of


KORKRKorea, Republic Of


KOSKSKosovo


KWTKWKuwait


KGZKGKyrgyzstan


LAOLALao People's DemocraticRepublic


LVALVLatvia




ISO 3116-1Alpha-2



LBNLBLebanon


LSOLSLesotho


LBRLRLiberia


LBYLYLibyan Arab Jamahiriya


LIELILiechtenstein



LTULTLithuania


LUXLULuxembourg



MACMOMacao


MKDMKMacedonia, Former YugoslavRepublic Of


MDGMGMadagascar


MWIMWMalawi


MYSMYMalaysia



MDVMVMaldives


MLIMLMali

6 Liechtenstein is covered by the Switzerland geocoder7 Luxembourg is covered by the Belgium geocoder



ISO 3116-1Alpha-2



MLTMLMalta


MHLMHMarshall Islands


MTQMQMartinique

Guadeloupe is covered by the Francegeocode Universal Addressing Module


MRTMRMauritania


MUSMUMauritius

Address Now ModuleEnterprise Geocoding Module UniversalAddressing Module

MYTYTMayotte


MEXMXMexico


FSMFMMicronesia, Federated StatesOf


MDAMDMoldova, Republic Of

Address Now ModuleEnterprise Geocoding Module10Universal Addressing Module

MCOMCMonaco


MNGMNMongolia


MNEMEMontenegro


MSRMSMontserrat


MARMAMorocco


MOZMZMozambique

8 Martinique is covered by the France geocoder.9 Mayotte is covered by the France geocoder.10 Monaco is covered by the France geocoder




ISO 3116-1Alpha-2



MMRMMMyanmar


NAMNANamibia


NRUNRNauru


NPLNPNepal


NLDNLNetherlands



NCLNCNew Caledonia


NZLNZNew Zealand



NICNINicaragua


NERNENiger


NGANGNigeria


NIUNUNiue


NFKNFNorfolk Island


MNPMPNorthern Mariana Islands


NORNONorway



OMNOMOman



ISO 3116-1Alpha-2



PAKPKPakistan


PLWPWPalau


PSEPSPalestinian Territory,Occupied


PANPAPanama


PNGPGPapua New Guinea


PRYPYParaguay


PERPEPeru


PHLPHPhilippines


PCNPNPitcairn


POLPLPoland



PRTPTPortugal



PRIPRPuerto Rico


QATQAQatar

Address Now ModuleEnterprise Geocoding Module11Universal Addressing Module

REUREReunion


ROURORomania

11 Reunion is covered by the France geocoder




ISO 3116-1Alpha-2



RUSRURussian Federation


RWARWRwanda


BLMBLSaint Barthelemy


SHESHSaint Helena, Ascension &Tristan Da Cunha


KNAKNSaint Kitts and Nevis


LCALCSaint Lucia


MAFMFSaint Martin (French Part)


SPMPMSaint Pierre and Miquelon


VCTVCSaint Vincent And TheGrenadines


WSMWSSamoa



SMRSMSan Marino


STPSTSao Tome And Principe


SAUSASaudi Arabia


SENSNSenegal


SRBRSSerbia


SYCSCSeychelles

12 San Marino is covered by the Italy geocoder



ISO 3116-1Alpha-2



SLESLSierra Leone


SGPSGSingapore


Universal Addressing ModuleSXMSXSint Maarten (Dutch Part)


SVKSKSlovakia


SVNSISlovenia


SLBSBSolomon Islands


SOMSOSomalia


ZAFZASouth Africa


SGSGSSouth Georgia And The SouthSandwich Islands


SSDSSSouth Sudan


ESPESSpain



LKALKSri Lanka


SDNSDSudan


SURSRSuriname


SJMSJSvalbard And Jan Mayen


SWZSZSwaziland




ISO 3116-1Alpha-2



SWESESweden



CHECHSwitzerland



SYRSYSyrian Arab Republic


TWNTWTaiwan, Province of China


TJKTJTajikistan


TZATZTanzania, United Republic Of


THATHThailand



TLSTLTimor-Leste


TGOTGTogo


TKLTKTokelau


TONTOTonga


TTOTTTrinidad and Tobago


TUNTNTunisia


TURTRTurkey


TKMTMTurkmenistan



ISO 3116-1Alpha-2



TCATCTurks And Caicos Islands


TUVTVTuvalu


UGAUGUganda


UKRUAUkraine


AREAEUnited Arab Emirates


GBRGBUnited Kingdom



USAUSUnited States



UMIUMUnited States Minor OutlyingIslands


URYUYUruguay


UZBUZUzbekistan


VUTVUVanuatu


VENVEVenezuela, BolivarianRepublic Of


VNMVNViet Nam


VGBVGVirgin Islands, British


VIRVIVirgin Islands, U.S.


WLFWFWallis and Futuna




ISO 3116-1Alpha-2



ESHEHWestern Sahara


YEMYEYemen


ZMBZMZambia


ZWEZWZimbabwe


DValidateAddress ConfidenceAlgorithm

In this section:

• Introduction to the Validate Address ConfidenceAlgorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252

• Confidence Algorithm for U.S. and Canadian Addresses .252• Confidence Algorithm for International Addresses . . .253

Introduction to the Validate Address Confidence AlgorithmValidateAddress computes a confidence score for each validated address. This score describes howlikely it is that the validated address is correct. Confidence code values range from 0 to 100, with a zeroconfidence level indicating no confidence and 100 indicating a very high level of confidence that thematch results are correct. Confidence codes are calculated based on an algorithm that takes into accountthe match results for individual output fields. The output fields involved in this calculation include:

• Country• City• State• PostalCode• StreetName• HouseNumber• LeadingDirectional• TrailingDirectional• StreetSuffix• ApartmentNumber

Each field has its own Weight in the algorithm. Additionally, for each field the match result could belabeled as Success, Failure, or Changed. ("Changed" refers to cases where the contents of the fieldhave been corrected in order to get a match.) The match result—Success, Failure, orChanged—determines what the Factor is for that field. Thus, the calculation for the confidence code isa product of Weight by Factor as follows:

Confidence = (Weight * Factor) for City+ (Weight * Factor) for Country+ (Weight * Factor) for State+ (Weight * Factor) for PostalCode+ (Weight * Factor) for StreetName+ (Weight * Factor) for HouseNumber+ (Weight * Factor) for Directionals+ (Weight * Factor) for Street Suffix+ (Weight * Factor) for ApartmentNumber

Confidence Algorithm for U.S. and Canadian AddressesThe following table details the scoring and logic behind the ValidateAddress confidence algorithm forU.S. and Canadian addresses.

Table 99: Confidence Algorithm for U.S. and Canadian Addresses

Factor If Filled14Factor ifChanged13

Weight/Match ScoreField

0%100%10Country

75%50%10City

75%50%15State

25%25%15PostalCode

75%50%15StreetName

14 Refers to instances when the input data in this field is not present but is filled in order to achievea match.

13 Refers to instances when the input data in this field is changed in order to achieve a match.


Factor If Filled14Factor ifChanged13


75%50%15HouseNumber

75%50%10Directionals

75%50%5StreetSuffix

75%50%5ApartmentNumber

Confidence Algorithm for International AddressesThere are two confidence algorithms for addresses outside the U.S. and Canada, one for addresses incountries that use postal codes and one for addresses in countries that do not use postal codes.

The following table details the confidence algorithm for non-U.S. and non-Canadian addresses fromcountries that use postal codes.

Table 100: Confidence Algorithm for Countries With Postal Codes

Factor if PostalDataUnavailable

Factor IfFilled16

Factor ifChanged15


0%0%100%11.1111111111111Country

0%75%1750%11.1111111111111City

80%100100%16.6666666666667State

80%100%100%16.6666666666667PostalCode

50%75%50%16.6666666666667StreetName

50%75%50%16.6666666666667HouseNumber

0%75%50%0Directionals

50%75%50%5.55555555555556StreetSuffix

50%75%50%5.55555555555556ApartmentNumber


13 Refers to instances when the input data in this field is changed in order to achieve a match.16 Refers to instances when the input data in this field is not present but is filled in order to achieve

a match.15 Refers to instances when the input data in this field is changed in order to achieve a match.17 If the country is a Category C country, this value is 50%. Countries fall into one of these categories:

• Category A—Enables the validation and correction of an address's postal code, city name, state/countyname, street address elements, and country name.

• Category B—Enables the validation and correction of an address's postal code, city name, state/countyname, and country name. It does not support the validation or correction of street address elements.

• Category C—Enables the validation and correction of the country name, and the validation of theformat of the postal code.


Appendix D: ValidateAddress Confidence Algorithm

The following table details confidence algorithm for countries that do not use postal codes.

Table 101: Confidence Algorithm for Countries Without Postal Codes

Factor if PostalDataUnavailable

Factor IfFilled19

Factor ifChanged18


0%0%100%13.3333333333333Country

0%75%2050%13.3333333333333City

80%100100%20State

50%75%50%20StreetName

50%75%50%20HouseNumber

0%75%50%0Directionals

50%75%50%6.66666666666667StreetSuffix

50%75%50%6.66666666666667ApartmentNumber

The following table lists countries without postal codes.

Table 102: Countries Without Postal Codes

AngolaAlbaniaAfghanistan

BarbadosBahamasAnguilla

BhutanBeninBelize

BurundiBurkina FasoBotswana

Central African Rep.Cayman IslandsCameroon

ColumbiaCocos IslandsChad

Congo (Rep.)Congo (Dem. Rep.)Comoros

DjiboutiKorea (North)Cote d'Ivoire

EritreaEquatorial GuineaDominica

GambiaGabonFiji

GuyanaGrenadaGhana


18 Refers to instances when the input data in this field is changed in order to achieve a match.20 If the country is a Category C country, this value is 50%. Countries fall into one of these categories:

• Category A—Enables the validation and correction of an address's postal code, city name, state/countyname, street address elements, and country name.

• Category B—Enables the validation and correction of an address's postal code, city name, state/countyname, and country name. It does not support the validation or correction of street address elements.

• Category C—Enables the validation and correction of the country name, and the validation of theformat of the postal code.


KiribatiJamaicaIreland

MaliMalawiLibya

NauruNamibiaMauritania

PeruPanamaPalaos

Saint LuciaRwandaQatar

Sao Tome & PrincipeSamoaSaint Vincent & Grenadines

SurinameSierra LeoneSeychelles

TogoTimorTanzania

TuvaluTrinidad & TobagoTonga

VanuatuUnited Arab EmiratesUganda

ZimbabweYemen


Appendix D: ValidateAddress Confidence Algorithm

Notices

© 2013 Pitney Bowes Software Inc. All rights reserved. MapInfo and Group 1 Software are trademarksof Pitney Bowes Software Inc. All other marks and trademarks are property of their respective holders.

USPS® Notices

Pitney Bowes Inc. holds a non-exclusive license to publish and sell ZIP + 4® databases on optical andmagnetic media. The following trademarks are owned by the United States Postal Service: CASS, CASSCertified, DPV, eLOT, FASTforward, First-Class Mail, Intelligent Mail, LACSLink, NCOALink, PAVE,PLANET Code, Postal Service, POSTNET, Post Office, RDI, SuiteLink , United States Postal Service,Standard Mail, United States Post Office, USPS, ZIP Code, and ZIP + 4. This list is not exhaustive ofthe trademarks belonging to the Postal Service.

Pitney Bowes Inc. is a non-exclusive licensee of USPS® for NCOALink® processing.

Prices for Pitney Bowes Software's products, options, and services are not established, controlled, orapproved by USPS® or United States Government. When utilizing RDI™ data to determine parcel-shippingcosts, the business decision on which parcel delivery company to use is not made by the USPS® orUnited States Government.

Data Provider and Related Notices

Data Products contained on this media and used within Pitney Bowes Software applications are protectedby various trademarks and by one or more of the following copyrights:

© Copyright United States Postal Service. All rights reserved.

© 2013 TomTom. All rights reserved. TomTom and the TomTom logo are registered trademarks ofTomTom N.V.

© Copyright NAVTEQ. All rights reserved

Data © 2013 NAVTEQ North America, LLC

Fuente: INEGI (Instituto Nacional de Estadística y Geografía)

Based upon electronic data © National Land Survey Sweden.

© Copyright United States Census Bureau

© Copyright Nova Marketing Group, Inc.

Portions of this program are © Copyright 1993-2007 by Nova Marketing Group Inc. All Rights Reserved

© Copyright Canada Post Corporation

This CD-ROM contains data from a compilation in which Canada Post Corporation is the copyright owner.

© 2007 Claritas, Inc.

The Geocode Address World data set contains data licensed from the GeoNames Project(www.geonames.org) provided under the Creative Commons Attribution License ("Attribution License")located at http://creativecommons.org/licenses/by/3.0/legalcode. Your use of the GeoNames data(described in the Spectrum™ Technology PlatformUser Manual) is governed by the terms of the AttributionLicense, and any conflict between your agreement with Pitney Bowes Software, Inc. and the AttributionLicense will be resolved in favor of the Attribution License solely as it relates to your use of the GeoNamesdata.

ICU Notices

Copyright © 1995-2011 International Business Machines Corporation and others.

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software andassociated documentation files (the "Software"), to deal in the Software without restriction, includingwithout limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of theSoftware, and to permit persons to whom the Software is furnished to do so, provided that the above


http://www.geonames.org

http://creativecommons.org/licenses/by/3.0/legalcode

copyright notice(s) and this permission notice appear in all copies of the Software and that both theabove copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THEWARRANTIES OF MERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NOEVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLEFORANYCLAIM,ORANYSPECIAL INDIRECTORCONSEQUENTIALDAMAGES,ORANYDAMAGESWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTIONOF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR INCONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising orotherwise to promote the sale, use or other dealings in this Software without prior written authorizationof the copyright holder.


Copyright

rest web services guide - pitney...

Documents