SOAP Web Services Guide - Pitney Bowes Support |...

Spectrum Technology PlatformVersion 9.0 SP3

SOAP Web Services Guide

Contents

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

Chapter 2: Web Services..................................................................................11Address Now Module..........................................................................................12

BuildGlobalAddress....................................................................................12GetGlobalCandidateAddresses..................................................................23ValidateGlobalAddress...............................................................................29

Enterprise Routing Module................................................................................49GetTravelBoundary.....................................................................................49GetTravelCostMatrix...................................................................................63GetTravelDirections....................................................................................77GetRouteData.............................................................................................94PersistentUpdate........................................................................................97

Enterprise Tax Module......................................................................................105AssignGeoTAXInfo...................................................................................105CalculateDistance.....................................................................................143ReverseGeoTAXInfoLookup.....................................................................146Match and Location Codes.......................................................................168

GeoConfidence Module....................................................................................177GeoConfidenceSurface............................................................................177

Global Sentry Module.......................................................................................179GlobalSentry.............................................................................................179

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

Universal Addressing Module..........................................................................185AutoCompleteLoqate................................................................................185GetCandidateAddresses..........................................................................191GetCandidateAddressesLoqate...............................................................199GetCityStateProvince...............................................................................204GetCityStateProvinceLoqate....................................................................207GetPostalCodes.......................................................................................209ValidateAddress........................................................................................212

ValidateAddressGlobal.............................................................................268ValidateAddressLoqate.............................................................................286

Universal Name Module....................................................................................305OpenNameParser.....................................................................................305

Appendix..........................................................................................................313

Appendix A: The ACR Code.................................................................315The ACR Code.........................................................................................316

Appendix B: Buffering..........................................................................319Buffering...................................................................................................320

Appendix C: Country Codes.................................................................321Country ISO Codes and Module Support.................................................322

Appendix D: ValidateAddress Confidence Algorithm........................341Introduction to the Validate Address Confidence Algorithm.....................342Confidence Algorithm for U.S. and Canadian Addresses........................342Confidence Algorithm for International Addresses...................................343

Spectrum Technology Platform 9.0 SP34

1Getting Started

In this section:

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

The SOAP InterfaceThe Spectrum™ Technology Platform server provides access to services using SOAP in document/literalmode. This method allows you to create an XML schema to enforce the contract between the client andthe server. Document/literal web services are the WS-I compliant format for web services.

To view the SOAP web services available on your Spectrum™ Technology Platform server, go to:

http://server:port/soap

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

Note:

WSDL URL

You can access the WSDL for each web service available on your system using this URL:

http://server:port/soap/service_name?wsdl

For example:

http://myserver:8080/soap/ValidateAddress?wsdl

The web service model is a generic model for all services. The WSDL for any Spectrum™ TechnologyPlatform web service contains the same definition of data types and operations. What differentiates theWSDL is the target service and the values (options and data) provided at runtime.

Sample SOAP Request

The following sample SOAP request calls the ValidateAddress service. The sections for options androws are all dependent on the metadata for that particular web service; therefore, different componentswill have different metadata entries. Additionally, there is a user_fields section that allows you to passin field values that will be returned, unmodified, in the response.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:val="http://www.pb.com/spectrum/services/ValidateAddress"><soapenv:Header/><soapenv:Body>

<val:ValidateAddressRequest><val:options>

<val:OutputFormattedOnFail>Y</val:OutputFormattedOnFail></val:options><val:input_port>

<val:Address><val:AddressLine1>1525B Kramer Lane</val:AddressLine1><val:AddressLine2>Suite 100</val:AddressLine2><val:PostalCode>78758</val:PostalCode>

</val:Address></val:input_port>

</val:ValidateAddressRequest></soapenv:Body>

</soapenv:Envelope>

Sample SOAP Response

The sample request above would return the following response.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body>

<ns3:ValidateAddressResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/ValidateAddress">

<ns3:output_port><ns3:Address>


The SOAP Interface

<ns3:Confidence>88</ns3:Confidence><ns3:RecordType>Normal</ns3:RecordType><ns3:CountryLevel>A</ns3:CountryLevel><ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:MatchScore>0</ns3:MatchScore>

<ns3:AddressLine1>1525B Kramer Ln Ste 100</ns3:AddressLine1>

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

</ns3:Address></ns3:output_port>

</ns3:ValidateAddressResponse></soap:Body>

</soap:Envelope>

Related LinksExposing a Service as a Web Service on page 7

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. Tomake the service available as a SOAPweb service, check the box Expose as SOAP web service.5. To make the service available as a REST web service, check the box Expose as REST web service

and complete the following steps.a) If you want to override the default endpoint, specify the endpoint you want to use in the Path

field.

Specifying a path is optional. By default, a REST web service's endpoint is:

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

If you want to use a different endpoint, the path you specify is added after the service name. Forexample, if you specify Americas/Shipping in the Path field, your JSON endpoint would besomething like this:

http://myserver:8080/rest/MyService/Americas/Shipping/results.json

You can use fields and options from the dataflow as variable names in the path by clicking theInsert variable drop-down menu and selecting the field or option you want to use. The variableis represented in the path using the notation ${Option.Name} for dataflow options and${Data.Name} for dataflow fields.

b) By default RESTweb services support the GETmethod and return data in XML and JSON formats.You can define additional HTTP methods and output formats by clicking Add to add a resourceto the web service.

When you add a resource, you can choose the HTTP method (GET or POST). The supporteddata formats are listed below. You may not have all these formats available to you because someformats are only available if you have certain modules installed on your Spectrum™ TechnologyPlatform server.

The default XML format. Use this format if you want to use XML as the format forrequests and responses, and there is no specialized XML format for the kind ofdata you want to process.

XML

7SOAP Web Services Guide

Chapter 1: Getting Started

The default JSON format. Use this format if you want to use JSON as the formatfor requests and responses, and there is no specialized JSON format for the kindof data you want to process.

JSON

c) Click OK.

The new resource is added to the web service.

6. Click OK when you are done configuring the web service options.7. Click the gray light bulb in the tool bar to expose the service.

When a dataflow is exposed the light bulb button in the Enterprise Designer tool bar indicates thatthe dataflow is exposed as shown here:

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

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

Related LinksThe SOAP Interface on page 6

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

using System;using System.Collections.Generic;using System.Diagnostics;using System.Linq;using System.Net;using System.Text;using ConsoleApplication1.ValidateAddress_Reference;

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"

};


Sample Web Application

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();

}}

}


Chapter 1: Getting Started

2Web Services

In this section:

• Address Now Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12• Enterprise Routing Module . . . . . . . . . . . . . . . . . . . . . . . .49• Enterprise Tax Module . . . . . . . . . . . . . . . . . . . . . . . . . . .105• GeoConfidence Module . . . . . . . . . . . . . . . . . . . . . . . . . .177• Global Sentry Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .179• Location Intelligence Module . . . . . . . . . . . . . . . . . . . . . .185• Universal Addressing Module . . . . . . . . . . . . . . . . . . . . .185• Universal Name Module . . . . . . . . . . . . . . . . . . . . . . . . . .305

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

http://server:port/soap/BuildGlobalAddress

Example

The following shows a SOAP request for the initialization (init) action to obtain a session ID fromBuildGlobalAddress:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:buil="http://www.pb.com/spectrum/services/BuildGlobalAddress"xmlns:spec="http://spectrum.pb.com/">

<soapenv:Header/><soapenv:Body>

<buil:BuildGlobalAddressRequest><buil:input_port>

<buil:Search><buil:Action>init</buil:Action><buil:Country>USA</buil:Country>

</buil:Search></buil:input_port>

</buil:BuildGlobalAddressRequest></soapenv:Body>

</soapenv:Envelope>

This would be the response. The init action returns a session ID which is then used in subsequent callsto BuildGlobalAddress as the user builds the address:


<ns3:BuildGlobalAddressResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/BuildGlobalAddress">

<ns3:output_port><ns3:Result>

<ns3:Action>init</ns3:Action><ns3:Country>USA</ns3:Country><ns3:SessionId>r679p6drw0</ns3:SessionId><ns3:Field.0.Name>Zip</ns3:Field.0.Name><ns3:Field.0.Index>0</ns3:Field.0.Index><ns3:Field.0.Value/><ns3:Field.0.CommitFlag>N</ns3:Field.0.CommitFlag><ns3:Field.1.Name>City</ns3:Field.1.Name><ns3:Field.1.Index>1</ns3:Field.1.Index><ns3:Field.1.Value/><ns3:Field.1.CommitFlag>N</ns3:Field.1.CommitFlag><ns3:Field.2.Name>State</ns3:Field.2.Name><ns3:Field.2.Index>2</ns3:Field.2.Index><ns3:Field.2.Value/><ns3:Field.2.CommitFlag>N</ns3:Field.2.CommitFlag><ns3:Field.3.Name>County</ns3:Field.3.Name><ns3:Field.3.Index>3</ns3:Field.3.Index><ns3:Field.3.Value/><ns3:Field.3.CommitFlag>N</ns3:Field.3.CommitFlag>


Address Now Module

<ns3:Field.4.Name>Street</ns3:Field.4.Name><ns3:Field.4.Index>4</ns3:Field.4.Index><ns3:Field.4.Value/><ns3:Field.4.CommitFlag>N</ns3:Field.4.CommitFlag><ns3:Field.5.Name>Company</ns3:Field.5.Name><ns3:Field.5.Index>5</ns3:Field.5.Index><ns3:Field.5.Value/><ns3:Field.5.CommitFlag>N</ns3:Field.5.CommitFlag><ns3:Field.6.Name>Building</ns3:Field.6.Name><ns3:Field.6.Index>6</ns3:Field.6.Index><ns3:Field.6.Value/><ns3:Field.6.CommitFlag>N</ns3:Field.6.CommitFlag><ns3:Field.7.Name>Premise-No</ns3:Field.7.Name><ns3:Field.7.Index>7</ns3:Field.7.Index><ns3:Field.7.Value/><ns3:Field.7.CommitFlag>N</ns3:Field.7.CommitFlag><ns3:Field.8.Name>Sub-Building</ns3:Field.8.Name><ns3:Field.8.Index>8</ns3:Field.8.Index><ns3:Field.8.Value/><ns3:Field.8.CommitFlag>N</ns3:Field.8.CommitFlag><ns3:Field.9.Name>PO-Box</ns3:Field.9.Name><ns3:Field.9.Index>9</ns3:Field.9.Index><ns3:Field.9.Value/><ns3:Field.9.CommitFlag>N</ns3:Field.9.CommitFlag><ns3:Field.10.Name>+4</ns3:Field.10.Name><ns3:Field.10.Index>10</ns3:Field.10.Index><ns3:Field.10.Value/><ns3:Field.10.CommitFlag>N</ns3:Field.10.CommitFlag><ns3:SearchFieldIndex>-1</ns3:SearchFieldIndex><ns3:Alternatives.InContext/><ns3:Alternatives.InContext.Count>

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

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

</ns3:Result></ns3:output_port>

</ns3:BuildGlobalAddressResponse></soap:Body>

</soap:Envelope>

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.


Chapter 2: Web Services

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

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


Address Now Module

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

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:StringAction

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:

• 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

StringAlternativeContext

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


Address Now Module


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]

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]

Country

Data.Countrychose 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 322.

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]

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]

SearchValue

in FieldIndex. For example, if you specified the ZIP Code fieldin FieldIndex, then you would enter a ZIP Code or partial ZIP




Code 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 22.

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]

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

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.

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

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.

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

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


Address Now Module


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

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

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

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

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

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

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




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

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

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

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

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

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


Address Now Module


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

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

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


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


Address Now Module

• 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

http://server:port/soap/GetGlobalCandidateAddresses

Example

The following shows a SOAP request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetGlobalCandidateAddresses"xmlns:spec="http://spectrum.pb.com/">


<get:GetGlobalCandidateAddressesRequest><get:input_port>

<get:Address><get:AddressLine1>1070 Maple</get:AddressLine1><get:City>Batavia</get:City><get:StateProvince>NY</get:StateProvince>

</get:Address></get:input_port>

</get:GetGlobalCandidateAddressesRequest></soapenv:Body>

</soapenv:Envelope>

This would be the response:

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

Note:


<ns3:GetGlobalCandidateAddressesResponsexmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/GetGlobalCandidateAddresses">




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

</ns3:Address><ns3:Address>

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


</ns3:GetGlobalCandidateAddressesResponse></soap:Body>

</soap:Envelope>

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]

AddressLine1

Second address lineString[79]

AddressLine2

Third address lineString[79]

AddressLine3

Fourth address lineString[79]

AddressLine4

Fifth address lineString[79]

AddressLine5


Address Now Module


Sixth address lineString[79]

AddressLine6

Seventh address lineString[79]

AddressLine7

Eighth address lineString[79]

AddressLine8

City nameString[79]

City

State or province.String[79]

StateProvince

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

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

StringCountry

Company or firm nameString[79]

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

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.


OutputCountryFormat

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

Specifies the casing of the output data. One of the following: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.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.

MaximumResults

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

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


Address Now Module


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

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

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

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


Address Now Module


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

http://server:port/soap/ValidateGlobalAddress

Resource URL

http://server:port/soap/ValidateAddressGlobal

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:val="http://www.pb.com/spectrum/services/ValidateGlobalAddress"xmlns:spec="http://spectrum.pb.com/">


<val:ValidateGlobalAddressRequest><val:input_port>

<val:Address><val:AddressLine1>1825 Kramer Ln</val:AddressLine1><val:City>Austin</val:City><val:StateProvince>TX</val:StateProvince><val:PostalCode></val:PostalCode><val:Country>USA</val:Country>


</val:ValidateGlobalAddressRequest></soapenv:Body>

</soapenv:Envelope>


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


<ns3:ValidateGlobalAddressResponse xmlns:ns2="http://spectrum.pb.com/"



xmlns:ns3="http://www.pb.com/spectrum/services/ValidateGlobalAddress"><ns3:output_port>

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


</ns3:ValidateGlobalAddressResponse></soap:Body>

</soap:Envelope>

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]

AddressLine1


AddressLine2


AddressLine3


AddressLine4


AddressLine5


AddressLine6

Seventh address lineString[79]

AddressLine7

Eighth address lineString[79]

AddressLine8

City nameString[79]

City


Address Now Module



StateProvince

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

String[79]:

9999999999-9999

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]

Country

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


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

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

Output Data Options

Table 11: ValidateGlobalAddress Output Data Options



OutputCountryFormat

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

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.

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

FormatAddress

Yes, format addresses (default).Y

No, do not format addresses.N


Address Now Module

Standardization Options

Table 12: ValidateGlobalAddress Standardization Options


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

StandardizeComponent.Department

Yes (default)Y

NoN

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

StandardizeComponent.FirmName

Yes (default)Y

NoN

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

StandardizeComponent.Building

Yes (default)Y

NoN

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

StandardizeComponent.SubBuilding

Yes (default)Y

NoN

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

StandardizeComponent.HouseNumber

Yes (default)Y

NoN

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

StandardizeComponent.SubStreet

Yes (default)Y

NoN

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

StandardizeComponent.StreetName

Yes (default)Y

NoN

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

StandardizeComponent.POBox

Yes (default)Y

NoN

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

StandardizeComponent.SubCity

Yes (default)Y

NoN




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

StandardizeComponent.City

Yes (default)Y

NoN

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

StandardizeComponent.USCountyName

Yes (default)Y

NoN

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

StandardizeComponent.StateProvince

Yes (default)Y

NoN

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

StandardizeComponent.Principality

Yes (default)Y

NoN

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

StandardizeComponent.PostalCode

Yes (default)Y

NoN

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

StandardizeComponent.Plus4

Yes (default)Y

NoN

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

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.

ReportVulgarWords

YesY

No (default)N

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

FlagVulgarWords

YesY

No (default)N

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

DebugOutput

YesY


Address Now Module


No (default)N

Validation Options

Table 13: ValidateGlobalAddress Validation Options


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

ValidateComponent.Department

YesY

No (default)N

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

ValidateComponent.FirmName

YesY

No (default)N

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

ValidateComponent.Building

Yes (default)Y

NoN

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

ValidateComponent.SubBuilding

Yes (default)Y

NoN

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

ValidateComponent.HouseNumber

Yes (default)Y

NoN

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

ValidateComponent.SubStreet

Yes (default)Y

NoN

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

ValidateComponent.StreetName

Yes (default)Y

NoN

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

ValidateComponent.POBox

Yes (default)Y




NoN

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

ValidateComponent.SubCity

Yes (default)Y

NoN

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

ValidateComponent.City

Yes (default)Y

NoN

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

ValidateComponent.USCountyName

Yes (default)Y

NoN

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

ValidateComponent.StateProvince

Yes (default)Y

NoN

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

ValidateComponent.Principality

Yes (default)Y

NoN

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

ValidateComponent.PostalCode

Yes (default)Y

NoN

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

ValidateComponent.Plus4

Yes (default)Y

NoN

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

ValidateComponent.Country

Yes (default)Y

NoN

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

ForceUpdate.Department

Yes (default)Y

NoN


Address Now Module


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

ForceUpdate.FirmName

Yes (default)Y

NoN

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

ForceUpdate.Building

Yes (default)Y

NoN

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

ForceUpdate.SubBuilding

Yes (default)Y

NoN

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

ForceUpdate.HouseNumber

Yes (default)Y

NoN

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

ForceUpdate.SubStreet

Yes (default)Y

NoN

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

ForceUpdate.StreetName

Yes (default)Y

NoN

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

ForceUpdate.POBox

Yes (default)Y

NoN

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

ForceUpdate.SubCity

Yes (default)Y

NoN

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

ForceUpdate.City

Yes (default)Y

NoN




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

ForceUpdate.USCountyName

Yes (default)Y

NoN

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

ForceUpdate.StateProvince

Yes (default)Y

NoN

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

ForceUpdate.Principality

Yes (default)Y

NoN

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

ForceUpdate.PostalCode

Yes (default)Y

NoN

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

ForceUpdate.Plus4

Yes (default)Y

NoN

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

ForceUpdate.Country

Yes (default)Y

NoN

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

ReplaceAlias.Department

YesY

No (default)N

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

ReplaceAlias.FirmName

YesY

No (default)N

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

ReplaceAlias.Building

YesY

No (default)N


Address Now Module


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

ReplaceAlias.SubBuilding

YesY

No (default)N

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

ReplaceAlias.HouseNumber

YesY

No (default)N

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

ReplaceAlias.SubStreet

YesY

No (default)N

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

ReplaceAlias.StreetName

YesY

No (default)N

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

ReplaceAlias.POBox

YesY

No (default)N

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

ReplaceAlias.SubCity

YesY

No (default)N

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

ReplaceAlias.City

YesY

No (default)N

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

ReplaceAlias.USCountyName

YesY

No (default)N

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

ReplaceAlias.StateProvince

YesY

No (default)N




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

ReplaceAlias.Principality

YesY

No (default)N

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

ReplaceAlias.PostalCode

Yes (default)Y

NoN

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

ReplaceAlias.Plus4

YesY

No (default)N

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

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.

CautiousUpdate

YesY

No (default)N

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

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

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


Address Now Module


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.

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

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

AcceptanceLevel

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

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

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.

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

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.

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


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

CityWeight

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


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

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

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.

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.

FormatComponent.Department

Yes (default)Y

NoN

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

FormatComponent.FirmName

Yes (default)Y

NoN

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

FormatComponent.Building

Yes (default)Y

NoN


Address Now Module


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

FormatComponent.SubBuilding

Yes (default)Y

NoN

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

FormatComponent.HouseNumber

Yes (default)Y

NoN

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

FormatComponent.SubStreet

Yes (default)Y

NoN

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

FormatComponent.StreetName

Yes (default)Y

NoN

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

FormatComponent.POBox

Yes (default)Y

NoN

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

FormatComponent.SubCity

Yes (default)Y

NoN

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

FormatComponent.City

Yes (default)Y

NoN

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

FormatComponent.USCountyName

Yes (default)Y

NoN

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

FormatComponent.StateProvince

Yes (default)Y

NoN

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

FormatComponent.Principality

Yes (default)Y

NoN




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

FormatComponent.PostalCode

Yes (default)Y

NoN

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

FormatComponent.Plus4

Yes (default)Y

NoN

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

FormatComponent.Country

YesY

No (default)N

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

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


Address Now Module


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


City

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

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

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




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


Address Now Module

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

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

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

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 316). 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 Now Module

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.

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. Multiple costs canbe given as input by providing the costs as a “;” delimited string.

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://server:port/soap/GetTravelBoundary

Example with JSON Response

The following example requests a JSON response:

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

The JSON returned by this request would be:



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"

}]}]}



Example with XML Response

The following example requests an XML response:

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

The XML returned by this request would be:


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

Example

Case 1, Single Cost:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetTravelBoundary">


<get:GetTravelBoundaryRequest><get:input_port>

<get:IsoRouteRequest><get:Latitude>33.751748</get:Latitude><get:Longitude>-84.364014</get:Longitude><get:TravelBoundaryCost>10</get:TravelBoundaryCost>

<get:TravelBoundaryCostUnits>Kilometers</get:TravelBoundaryCostUnits></get:IsoRouteRequest>

</get:input_port></get:GetTravelBoundaryRequest>

</soapenv:Body></soapenv:Envelope>




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


<ns4:IsoNodeResponse/><ns4:IsoPolygonResponse

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



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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>



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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos>...


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

</ns4:IsoRouteResponse></ns4:output_port>

</ns4:GetTravelBoundaryResponse></soap:Body>

</soap:Envelope>

Case 2, Multiple Costs:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetTravelBoundary">


<get:GetTravelBoundaryRequest><get:input_port>

<get:IsoRouteRequest><get:Latitude>33.751748</get:Latitude><get:Longitude>-84.364014</get:Longitude><get:TravelBoundaryCost>5;10</get:TravelBoundaryCost>

<get:TravelBoundaryCostUnits>Kilometers</get:TravelBoundaryCostUnits></get:IsoRouteRequest>

</get:input_port></get:GetTravelBoundaryRequest>





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


<ns4:cost>5</ns4:cost><ns4:costUnits>Kilometers</ns4: costUnits ><ns4:IsoNodeResponse/>

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





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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos>...



</ns4:IsoRouteResponse><ns4:IsoRouteResponse>

<ns4:cost>10</ns4:cost><ns4:costUnits>Kilometers</ns4: costUnits ><ns4:IsoNodeResponse/>

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



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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos>



<ns3:Pos><ns3:X>-84.3694506405556</ns3:X><ns3:Y>33.69293307108579</ns3:Y>

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos><ns3:Pos>

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

</ns3:Pos>...



</ns4:IsoRouteResponse></ns4:output_port>

</ns4:GetTravelBoundaryResponse></soap:Body>

</soap:Envelope>

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 CoordinateFormat option.

StringLatitude

Longitude of the point. Specify longitude in theformat chosen in the CoordinateFormat option.

StringLongitude

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

StringTravelBoundaryCost

field or the DefaultTravelBoundaryCostUnits option.




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.

You can also specify multiple costs by specifyingthe values as a ";" delimited string. It will return aseparate Iso Route Response for every costspecified. If you specify multiple costs, everyresponse will have cost and costUnits associatedwith that response.

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

StringTravelBoundaryCostUnits

• 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

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

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.

For more information on EPSG codes, see www.spatialreference.org. Toretrieve a list of supported codespaces for EPSG, you can submit the SOAPrequest List Supported CoordSys by Code Space from the Geometry Service



http://spatialreference.org/


Demo page athttp://localhost:8080/Spatial/GeometryService/DemoPage.html.

Specifies the format of latitude/longitude coordinates in the input.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.DefaultTravelBoundaryCost

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

DefaultTravelBoundaryCostUnits

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

Specifies whether the routing calculation uses the historic traffic speeds.These speeds are based on different time-of-day buckets. The data must

HistoricTrafficTimeBucket

have historic traffic speeds included in order to use this feature. The data foreach country/region has the same bucket definitions, where the speeds forthese bucket values may vary. The options are:

The default value. Historic traffic data is not used in thecalculation. Instead an averaged speed value is used.

None

Calculate routes with the peak AM speeds. The AMPeaktime bucket is from 07:00 to 10:00hr time of day.

AMPeak

Calculate routes with the peak PM speeds. The PMPeaktime bucket is from 16:00 to 19:00hr time of day.

PMPeak

Calculate routes with the off peak (daytime) speeds. TheOffPeak time bucket is from 10:00 to 16:00hr time of day.

OffPeak

Calculate routes with the nighttime speeds. The Night timebucket is from 22:00 to 04:00hr time of day.

Night



http://localhost:8080/Spatial/UserManagementService/DemoPage.html

Output Options

Table 19: GetTravelBoundary Output Options


Specifies the type of result you want returned. One of the following: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.

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.

BandingStyle

Each boundary is determined by subtracting outthe next smallest boundary.

Donut

Each boundary is determined independent of allothers.

Encompassing

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.

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.

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

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 a




value 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:

Units

• Kilometer (default)• Meter• Mile

Specifies whether to include all roads in the calculation or justmajor roads. By default, the Get Travel Boundary is calculated

MajorRoads

with major roads set to true. This improves performance butthe accuracy may decrease.

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.

DefaultAmbientSpeed

This option is available only when you specify a time valuein the DefaultCostUnits option or the TravelBoundaryCostUnitsfield. The default is 15. Specify the speed units in theAmbientSpeedUnit option.

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 theMaximumOffRoadDistance option.

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 theDefaultAmbientSpeed 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

AmbientSpeed.RoadType.<Type>

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

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.

Resource URL

http://server:port/soap/GetTravelCostMatrix



Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:get="http://www.pb.com/spectrum/services/GetTravelCostMatrix"xmlns:spec="http://spectrum.pb.com/"xmlns:get1="http://www.g1.com/services/GetTravelCostMatrix"xmlns:typ="http://www.g1.com/services/erm/types"><soapenv:Header/><soapenv:Body>

<get:GetTravelCostMatrixRequest><get:input_port>

<get:RouteMatrixRequest><get:StartPoints>

<get:StartPoint><get:Latitude>33.751748</get:Latitude>

<get:Longitude>-84.364014</get:Longitude></get:StartPoint><get:StartPoint>

<get:Latitude>33.870416</get:Latitude><get:Longitude>-78.62915</get:Longitude>

</get:StartPoint><get:StartPoint>


</get:StartPoint></get:StartPoints><get:EndPoints>

<get:EndPoint><get:Latitude>33.664925</get:Latitude><get:Longitude>-80.90332</get:Longitude>

</get:EndPoint><get:EndPoint>




</get:EndPoint></get:EndPoints>

</get:RouteMatrixRequest></get:input_port>

</get:GetTravelCostMatrixRequest></soapenv:Body>

</soapenv:Envelope>



<ns5:GetTravelCostMatrixResponse xmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.g1.com/services/erm/types"xmlns:ns4="http://www.g1.com/services/GetTravelCostMatrix"xmlns:ns5="http://www.pb.com/spectrum/services/GetTravelCostMatrix">

<ns5:output_port><ns5:RouteMatrixResponse>

<ns5:TimeUnits>Minutes</ns5:TimeUnits><ns5:DistanceUnits>Miles</ns5:DistanceUnits><ns5:RouteCosts>

<ns5:RouteCost><ns5:StartPointRef>1</ns5:StartPointRef><ns5:EndPointRef>1</ns5:EndPointRef><ns5:Time>215.82</ns5:Time><ns5:Distance>218.441</ns5:Distance>



</ns5:RouteCost><ns5:RouteCost>

<ns5:StartPointRef>2</ns5:StartPointRef><ns5:EndPointRef>2</ns5:EndPointRef><ns5:Time>124.82</ns5:Time><ns5:Distance>103.437</ns5:Distance>

</ns5:RouteCost><ns5:RouteCost>

<ns5:StartPointRef>3</ns5:StartPointRef><ns5:EndPointRef>3</ns5:EndPointRef><ns5:Time>22.53</ns5:Time><ns5:Distance>15.005</ns5:Distance>

</ns5:RouteCost></ns5:RouteCosts><ns5:user_fields/>

</ns5:RouteMatrixResponse></ns5:output_port>

</ns5:GetTravelCostMatrixResponse></soap:Body>

</soap:Envelope>

Request

Parameters for Input DataThe input to Get Travel Cost Matrix is a list of start points and end points expressed as latitude/longitudecoordinates. You can also include user-defined fields.

The order of start and end points in the input determines the order of the sequences in the response.For example, if you specify two start points and two end points in the request, the response will containthe following order of sequences (where S is start and E is end): S1 to E1, S1 to E2, S2 to E1, S2 to E2.

The Get Travel Cost Matrix service is only available as a web service. The Get Travel Cost Matrixis not available through the Java, C++, C, .NET, or COM APIs.

Note:

Table 22: Get Travel Cost Matrix Input


The latitude for a start or end point. Specify the latitude using the formatselected in the CoordinateFormat option.

Latitude

The longitude for a start or end point. Specify the longitude using theformat selected in the CoordinateFormat option.

Longitude

An identification you assign to the point. Specify an ID comprised ofalpha and/or numeric characters to represent a point. This IDcorresponds to the StartPointID or EndPointID field in output.

ID

A schema containing the update types for the transient update. Transientupdates are updates made on a request that only apply to that particular

MatrixTransientUpdate

request. Transient updates are similar to Persistent updates, exceptthat Transient updates are only for a particular request and Persistentupdates are for all the requests. You have the ability to set a speed fora point, a segment id, or a road class, as well as the ability to updatethe road class for a segment (specified by the segment id).

For transient update options and example, see Transient Options onpage 71.



Parameters for OptionsTravel Options

This set of preferences allows you to set the desirability for each road type. For instance, you can requestthat the server attempt to avoid all of the major road types.

Table 23: Travel Preferences Options


Specifies the priority to give to different types of roads when determiningthe route.

RoadType_<type>

• access way• back road• connector• ferry• footpath• limited access dense urban• limited access rural• limited access suburban• limited access urban• local road dense urban• local road rural• local road suburban• local road urban• major local road dense urban• major local road rural• major local road suburban• major local road urban• major road dense urban• major road rural• major road suburban• major road urban• minor local road dense Urban• minor local road rural• minor local road suburban• minor local road urban• mormal road dense urban• normal road rural• normal road rural• normal road urban• primary highway dense urban• primary highway rural• primary highway suburban• primary highway urban• ramp dense urban• ramp limited access• ramp major road• ramp primary highway• ramp rural• ramp secondary highway




• ramp urban• ramp suburban• secondary highway dense urban• secondary highway rural• secondary highway suburban• secondary highway urban

For each road type you can specify one of the following:

Exclude the road type from routes if possible.Avoid

It is not always possible to exclude a road typefrom the travel directions. Depending on the

Note:

situation, the alternative to an avoided road typemay be so poor that the software will choose aroute that uses an avoided road type. Also, if thestarting or ending point lies along a segment whoseroad type has been avoided, the software will stilluse that segment.

Prefer the road type over other road types.High

Prefer other road types over this road type.Low

Give this road type equal preference with other road types.If no preference is specified for a road type, the default isMedium.

Medium

Specifies whether to include all roads in the calculation or just majorroads. If you choose to include only major roads, performance willimprove but accuracy may decrease.

MajorRoads

This map represents a travel boundary with travel allowed on all roads:

This map represents a travel boundary with travel restricted to majorroads only:







Specifies that a Commercial Vehicle Restrictions (CVR) priority is usedwhen determining the route.

UseVehicleRestriction

This is a boolean value.

Specifies that barriers will be removed when determining the route.These restrictions aremost often when a commercial vehicle is prohibited

LooseningBarrierRestrictions

from traversing a segment due to local ordinance or a commercial vehicleis allowed on the segment but only when it must (for example, last mileaccess, local delivery, etc.). Routes where a barrier has been removedwill still have a higher route cost even if the route it shorter/faster thana route with no barrier.


Specifies that type of vehicle that will be restricted based on the height,weight, length, or width when determining the route. Commercial vehicles

VehicleType

are divided into different types ranging from short trailers to long triples.The Commercial Vehicle Restrictions attribution is organized on aper-vehicle type basis. This means it is entirely possible for a segmentto be preferred for one vehicle type and the same segment have arestriction for another type of vehicle.

This is a string value. The types of vehicles are:ALL,STRAIGHT,SEMI_TRAILOR,STANDARD_DOUBLE,INTERMEDIATE_DOUBLE,LONG_DOUBLE,TRIPLE,OTHER_LONG_COMBINATION_VEHICLE

Specifies that maximum length of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleLength

Specifies the length unit of a vehicle that will be restricted whendetermining the route.

VehicleLengthUnit




This is a string value. The types of length are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximum height of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleHeight

Specifies the Height unit of a vehicle that will be restricted whendetermining the route.

VehicleHeightUnit

This is a string value. The types of Height are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximumWidth of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleWidth

Specifies the Width unit of a vehicle that will be restricted whendetermining the route.

VehicleWidthUnit

This is a string value. The types of Width are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximum Weight of a vehicle. Any vehicles over thisvalue will be restricted when determining the route.

DefaultVehicleWeight

Specifies the Weight unit of a vehicle that will be restricted whendetermining the route.

VehicleWeightUnit

This is a string value. The types of Weight are:Kilogram,Pound,Metric Tonnes,Ton

Routing Options

Table 24: Routing Options


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

DataSetResourceName

Routing Module Routing Database Resources tool. For moreinformation, see theSpectrum™ Technology Platform AdministrationGuide.

Specifies whether to find the shortest distance or the shortest time.OptimizeBy


Optimize by fastest time traveled. Default.Time

Optimize by shortest distance traveled.Distance

Specifies whether to return only the optimized route for each startpoint/end point combination. The optimized route is either the fastest

ReturnOptimalRoutesOnly

route or the shortest distance, depending on the selection youmakefor the OptimizeBy option.

For example, if you have one start point (S1) and two end points(E1 and E2) and it is faster to go from S1 to E2 than from S1 to E1,and you choose to return only the optimal route, then only the routecost information for S1 to E2 will be returned.

Yes, return only optimal routes. Default.Y




No, return all routes not just the optimal routes.N

Specifies the data format of the route cost matrix. One of thefollowing:

RouteCostMatrixFormat

The route cost matrix is returned as list that you canview in Management Console, Enterprise Designer, or

Hierarchy

Interactive Driver. Choose this option if you want toview the data in these tools or if you want to work withthe data in tabular format. Default.

The route cost matrix is returned as a data object thatyou cannot interact with directly. Only select this option

Object

if the output is going directly to another stage in adataflow or a web service call, or if it will be used byanother application to visualize the routes, such asinput to mapping software.

The coordinate system of the input coordinates. The format mustbe the European Petroleum Survey Group (EPSG) code, the SRID

CoordinateSystem

code, or the MAPINFO code. Specify the coordinate referencesystem in the format codespace:code. For example, a geometryin Latitude/Longitude (WGS 84) would be EPSG:4326. The defaultvalue is EPSG:4326, which is also known as Latitude/Longitude(WGS 84). This is a worldwide system and is the terrestrialreference frame associated with the NAVSTAR Global PositioningSystem (GPS) used extensively for navigation and surveying. Thisdatum is earth-centered ("geocentric") and defined with satelliteand terrestrial data.

For more information on EPSG codes, seewww.spatialreference.org. To retrieve a list of supportedcodespaces for EPSG, you can submit the SOAP request ListSupported CoordSys by Code Space from the Geometry ServiceDemo page athttp://localhost:8080/Spatial/GeometryService/DemoPage.html.


Use this option only if you specify a Latitude/Longitudecoordinate system. If the coordinate system is not a

Note:

Latitude/Longitude coordinate system, set the coordinateformat to Decimal.


(90.000000, 180.000000). Default.Decimal

(90000000, 180000000).DecimalAssumed

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

(090000000N, 180000000W)PreZero


Specifies how GetTravelCostMatrix should return distance values.One of the following:

DistanceUnits

Return distance in feet.Feet

Return distance in kilometers.Kilometers

Return distance in meters.Meters

Return distance in miles. Default.Miles






Return distance in yards.Yards

Specifies how to return time. One of the following:TimeUnits

Return time in hours.Hours

Return time in minutes. Default.Minutes

Return time in seconds.Seconds

Specifies whether the routing calculation uses the historic trafficspeeds. These speeds are based on different time-of-day buckets.


The data must have historic traffic speeds included in order to usethis feature. The data for each country/region has the same bucketdefinitions, where the speeds for these bucket values may vary.The options are:

The default value. Historic traffic data is not usedin the calculation. Instead an averaged speed valueis used.

None

Calculate routes with the peak AM speeds. TheAMPeak time bucket is from 07:00 to 10:00hr timeof day.

AMPeak

Calculate routes with the peak PM speeds. ThePMPeak time bucket is from 16:00 to 19:00hr timeof day.

PMPeak

Calculate routes with the off peak (daytime) speeds.The OffPeak time bucket is from 10:00 to 16:00hrtime of day.

OffPeak

Calculate routes with the nighttime speeds. TheNight time bucket is from 22:00 to 04:00hr time ofday.

Night

Transient Options

This set of preferences allows you to set transient updates for each request. For instance, you canrequest that the server attempt to avoid all of the major road types. Each request can contain one ormore updates.

The transient update functionality is only available through the SOAP API, and is not availablethrough the Management Console or Enterprise Designer.

Note:

Table 25: Transient Update Options


Point updates are changes applied to a corresponding point (Latitude,Longitude). For a particular point, you can: exclude the point, set the

PointUpdate

speed of the point or change (increase or decrease) the speed of thepoint by a value or percentage. Youmust specify a Pointwhich consistsof a Latitude and Longitude, then specify one of the following:

This is a speed update where you define the newspeed of the point by specifying the velocity unit and

Velocity

new velocity. For speed updates, the velocity unit canhave one of the following values: kph (kilometers per




hour), mph (miles per hour), mps (meters persecond).

This is a speed update where you define an increasein the speed of the point by specifying either the

SpeedIncrease

velocity (unit and value) or a percentage to increasethe speed. For speed updates, the velocity unit canhave one of the following values: kph (kilometers perhour), mph (miles per hour), mps (meters persecond).

This is a speed update where you define a decreasein the speed of the point by specifying either the

SpeedDecrease

velocity (unit and value) or a percentage to decreasethe speed. For speed updates, the velocity unit canhave one of the following values: kph (kilometers perhour), mph (miles per hour), mps (meters persecond).

This is a sting value to exclude the specified pointfrom the route calculation. To exclude a point you

Exclude

need to specify the point and include the Excludeparameter defined as Y. Valid values are Y (yes) andN (no).

Segment updates are changes applied to a corresponding segment ID(Latitude, Longitude). For a particular segment, you can: exclude the

SegmentUpdate

segment, set the speed of the segment, change (increase or decrease)the speed of the segment by a value or percentage, or change the roadtype of the segment. You must specify a valid RoutingSegmentID,then specify one of the following:

This is a speed update where you define the newspeed of the segment by specifying the velocity unit

Velocity

and new velocity. For speed updates, the velocityunit can have one of the following values: kph(kilometers per hour), mph (miles per hour), mps(meters per second).

This is a speed update where you define an increasein the speed of the segment by specifying either the

SpeedIncrease


This is a speed update where you define a decreasein the speed of the segment by specifying either the

SpeedDecrease


This is a string value to change the value of the roadtype for the segment for the route calculation.

RoadType




The RoadType can be one of the following:

• access way• back road• connector• ferry• footpath• limited access dense urban• limited access rural• limited access suburban• limited access urban• local road dense urban• local road rural• local road suburban• local road urban• major local road dense urban• major local road rural• major local road suburban• major local road urban• major road dense urban• major road rural• major road suburban• major road urban• minor local road dense Urban• minor local road rural• minor local road suburban• minor local road urban• mormal road dense urban• normal road rural• normal road rural• normal road urban• primary highway dense urban• primary highway rural• primary highway suburban• primary highway urban• ramp dense urban• ramp limited access• ramp major road• ramp primary highway• ramp rural• ramp secondary highway• ramp urban• ramp suburban• secondary highway dense urban• secondary highway rural• secondary highway suburban• secondary highway urban




This is a sting value to exclude the specified segmentfrom the route calculation. To exclude a segment you

Exclude

need to specify the segment ID and include theExclude parameter defined as Y. Valid values areY (yes) and N (no).

Road type updates are changes applied to a corresponding road type.For a particular road type, you can: set the speed of the roadtype, or

RoadTypeUpdate

change (increase or decrease) the speed of the road type by a valueor percentage. You must specify a RoadType to update (see the aboveroad types in the segment update), then specify one of the following:


Velocity



SpeedIncrease



SpeedDecrease


GetTravelCostMatrix Transient Update SOAP ExampleThe following shows a standard GetTravelCostMatrix SOAP request with all of the transient updateoptions available (not a working example, this is used to show all the syntax). Each request can have aMatrixTransientUpdate which will be used to calculate each route matrix. You can have multipleUpdate definitions within a MatrixTransientUpdate. You can only have a single update type(PointUpdate, SegmentUpdate, or RoadTypeUpdate) within an Update. You can also only havea single update within one of the update types (PointUpdate, SegmentUpdate, or RoadTypeUpdate).

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:get="http://www.pb.com/spectrum/services/GetTravelCostMatrix"xmlns:spec="http://spectrum.pb.com/"xmlns:get1="http://www.g1.com/services/GetTravelCostMatrix"xmlns:typ="http://www.g1.com/services/erm/types"><soapenv:Header/><soapenv:Body>

<get:GetTravelCostMatrixRequest><get:input_port>

<get:RouteMatrixRequest><get:StartPoints>

<get:StartPoint>



<get:Latitude>33.751748</get:Latitude>

<get:Longitude>-84.364014</get:Longitude></get:StartPoint><get:StartPoint>


</get:StartPoint><get:StartPoint>


</get:StartPoint></get:StartPoints><get:EndPoints>

<get:EndPoint><get:Latitude>33.664925</get:Latitude><get:Longitude>-80.90332</get:Longitude>





</get:EndPoint></get:EndPoints>

<get:MatrixTransientUpdate><typ:Update><typ:PointUpdate><typ:Point><typ:Latitude>?</typ:Latitude><typ:Longitude>?</typ:Longitude></typ:Point><typ:SpeedUpdate><typ:Velocity VelocityUnit=""/><typ:SpeedIncrease><typ:Velocity VelocityUnit=""/><typ:Percentage>?</typ:Percentage></typ:SpeedIncrease><typ:SpeedDecrease><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage></typ:SpeedDecrease></typ:SpeedUpdate><typ:Exclude>?</typ:Exclude></typ:PointUpdate><typ:SegmentUpdate><typ:RoutingSegmentID>?</typ:RoutingSegmentID><typ:SpeedUpdate><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:SpeedIncrease><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage></typ:SpeedIncrease><typ:SpeedDecrease><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage></typ:SpeedDecrease></typ:SpeedUpdate><typ:RoadType>?</typ:RoadType><typ:Exclude>?</typ:Exclude></typ:SegmentUpdate><typ:RoadTypeUpdate><typ:RoadType>?</typ:RoadType><typ:SpeedUpdate><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:SpeedIncrease><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage></typ:SpeedIncrease>



<typ:SpeedDecrease><typ:Velocity VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage></typ:SpeedDecrease></typ:SpeedUpdate></typ:RoadTypeUpdate></typ:Update></get:MatrixTransientUpdate>

</get:RouteMatrixRequest></get:input_port>

</get:GetTravelCostMatrixRequest></soapenv:Body>

</soapenv:Envelope>

ResponseThe output from GetTravelCostMatrix contains a number of route sequences, each containing the startand end points for the candidates used in the matrix route as well as the time and distance for eachroute that has been calculated. The output may contain all routes in the matrix, or only the optimal routebetween each start/end point, depending on how you configure the OptimizeBy option.

If GetTravelCostMatrix cannot find a route between a start and end point in the matrix, an error will belogged in the server log but the routes that could be determined will be returned. For example, if youhave start point A and end points 1 and 2, and GetTravelCostMatrix can find a route from A to 1 but notfrom A to 2, GetTravelCostMatrix will return the route from A to 1 and log an error that the route from Ato 2 could not be determined.

GetTravelCostMatrix output is either in list format or object format depending on how you configure theReturnRouteCostMatrix option. You cannot interact directly with object output.

Table 26: Get Travel Cost Matrix Output


The distance from the start point to the end point. The value isin the units indicated in the DistanceUnits element.

StringDistance

The unit of measurement used for distance. One of the following:StringDistanceUnits

The distance is in feet.Feet

The distance is in kilometers.Kilometers

The distance is in meters.Meters

The distance is in miles. Default.Miles

The distance is in yards.Yards

A reference ID that corresponds to the order in which the endpoints were specified in the input. The first end point specified

StringEndPointRef

has a reference ID of 1, the second has an ID of 2, and so on.You must develop your own process for associating thelatitude/longitude coordinates in the input with the reference IDreturned by Get Travel Cost Matrix.

An identification you assigned to the corresponding end point inthe ID field of the Input stage. For example, the first end point

StringEndPointID

could have an EndPointID of N, the second end point could havean EndPointID of O, and so on.




This field is active only when the Route Cost MatrixFormat field is set to "Hierarchy."

Note:

A reference ID that corresponds to the order in which the startpoints were specified in the input. The first start point specified

StringStartPointRef

has a reference ID of 1, the second has an ID of 2, and so on.You must develop your own process for associating thelatitude/longitude coordinates in the input with the reference IDreturned by Get Travel Cost Matrix.

An identification you assigned to the corresponding start point inthe ID field of the Input stage. For example, the first start point

StringStartPointID

could have a StartPointID of A, the second start point could havea StartPointID of B, and so on.

This field is active only when the Route Cost MatrixFormat field is set to "Hierarchy."

Note:

The total time from the start point to the end point. The value isin the units indicated in the TimeUnits element.

StringTime

The unit of measurement used for time. One of the following:StringTimeUnits

The time is in hours.Hours

The time is in minutes. Default.Minutes

The time is in seconds.Seconds

Reports the success or failure of the match.String[1]

Status

Successnull

FailureF

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

Status.Code

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

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.



Resource URL

http://server:port/soap/GetTravelDirections

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetTravelDirections"xmlns:typ="http://www.g1.com/services/erm/types">


<get:GetTravelDirectionsRequest><get:input_port>

<get:PointToPointRequest><get:RoutePoints>

<get:RoutePoint><get:Latitude>33.751748</get:Latitude>

<get:Longitude>-84.364014</get:Longitude></get:RoutePoint><get:RoutePoint><get:Latitude>33.664925</get:Latitude><get:Longitude>-80.90332</get:Longitude>

</get:RoutePoint></get:RoutePoints>

</get:PointToPointRequest></get:input_port>

</get:GetTravelDirectionsRequest></soapenv:Body>

</soapenv:Envelope>


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


<ns6:GetTravelDirectionsResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.g1.com/services/erm/types"xmlns:ns4="http://www.g1.com/services/GetTravelDirections"xmlns:ns5="http://www.mapinfo.com/midev/service/geometries/v1"xmlns:ns6="http://www.pb.com/spectrum/services/GetTravelDirections">

<ns6:output_port><ns6:PointToPointResponse>

<ns6:Time>215.82</ns6:Time><ns6:TimeUnits>Minutes</ns6:TimeUnits><ns6:Distance>218.441</ns6:Distance><ns6:DistanceUnits>Miles</ns6:DistanceUnits><ns6:Format>Normal</ns6:Format><ns6:Language>en</ns6:Language><ns6:RouteDirections>

<ns6:RouteDirection><ns6:Instruction/><ns6:Time>0.03</ns6:Time><ns6:TimeUnits>Minutes</ns6:TimeUnits><ns6:Distance>0.013</ns6:Distance><ns6:DistanceUnits>Miles</ns6:DistanceUnits>

</ns6:RouteDirection><ns6:RouteDirection>

<ns6:Instruction>Turn left on Short St SE and travelSouth 0.10 mi (0.3 min).</ns6:Instruction>

<ns6:Time>0.28</ns6:Time><ns6:TimeUnits>Minutes</ns6:TimeUnits><ns6:Distance>0.099</ns6:Distance><ns6:DistanceUnits>Miles</ns6:DistanceUnits>

</ns6:RouteDirection>



...<ns6:RouteDirection>

<ns6:Instruction>Turn left on Un-named street andtravel East 0.11 mi (0.2 min).</ns6:Instruction>


</ns6:RouteDirection><ns6:RouteDirection>

<ns6:Instruction>Turn right to reach your destinationto the East.</ns6:Instruction>


</ns6:RouteDirection></ns6:RouteDirections><ns6:user_fields/>

</ns6:PointToPointResponse></ns6:output_port>

</ns6:GetTravelDirectionsResponse></soap:Body>

</soap:Envelope>

Request

Parameters for Input DataGetTravelDirections takes route points, which include starting and ending latitudes and longitudes asinput. The following table provides information on the format and layout of the input.

If you intend to interact with the GetTravelDirections service, note that it is only available as aweb service. The Get Travel Directions service is not available through the Java, C++, C, .NET,or COM APIs.

Note:

Table 27: GetTravel Directions Input Data


A schema containing the latitude string and the longitudestring.

ListRoutePoints

For information on creating a process list, see the Spectrum™

Technology Platform Dataflow Designer's Guide.

Specifies the language in which GetTravelDirections shouldreturn directions.

StringLanguage


Return directions in Chinese (Taiwan).zh_TW

Return directions in Croatian.hr

Return directions in Czech.cs

Return directions in Danish.da

Return directions in Dutch.nl

Return directions in English. Defaulten

Return directions in American English.en_US

Return directions in Estonian.et




Return directions in Finnish.fi

Return directions in French.fr

Return directions in German.de

Return directions in Hungarian.hu

Return directions in Italian.it

Return directions in Japanese.ja

Return directions in Latvian.lv

Return directions in Lithuanian.lt

Return directions in Norwegian.no

Return directions in Portuguese.pt

Return directions in Romanian.ro

Return directions in Slovak.sk

Return directions in Slovenian.sl

Return directions in Spanish.es

Return directions in Swedish.sv

Return directions in Russian.ru

Return directions in Turkish.tr

An entry in this input field will override an entry in theDefault Language option.

Note:

A schema containing the update types for the transient update.Transient updates are updates made on a request that only

ListTravelDirectionTransientUpdate

apply to that particular request. Transient updates are similarto Persistent updates, except that Transient updates are onlyfor a particular request and Persistent updates are for all therequests. You have the ability to set a speed for a point, asegment id, or a road class, as well as the ability to updatethe road class for a segment (specified by the segment id).

For transient update options and example, see TransientOptions on page 88.

Parameters for OptionsRouting

The following table lists the configuration options for GetTravelDirections.

Table 28: Get Travel Directions Configuration Options


The name of the database that contains the data to use in the searchprocess. Use the database name specified in theManagement Console

DataSetResourceName






Specifies whether GetTravelDirections should find the shortest distanceor the shortest time.

OptimizeBy


Optimize by shortest time traveled. Default.Time

Optimize by shortest distance traveled.Distance

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

CoordinateSystem

the MAPINFO code. Specify the coordinate reference system in theformat codespace:code. For example, a geometry inLatitude/Longitude (WGS 84) would be EPSG:4326. The default valueis EPSG:4326, which is also known as Latitude/Longitude (WGS 84).This is a worldwide system and is the terrestrial reference frameassociated with the NAVSTAR Global Positioning System (GPS) usedextensively for navigation and surveying. This datum is earth-centered("geocentric") and defined with satellite and terrestrial data.

For more information on EPSG codes, seewww.spatialreference.org.To retrieve a list of supported codespaces for EPSG, you can submitthe SOAP request List Supported CoordSys by Code Space from theGeometry Service Demo page athttp://localhost:8080/Spatial/GeometryService/DemoPage.html.


Use this option only if you specify a Latitude/Longitudecoordinate system. If the coordinate system is not a

Note:

Latitude/Longitude coordinate system, set the coordinate formatto Decimal.


(90.000000, 180.000000). Default.Decimal

(90000000, 180000000).DecimalAssumed

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

(090000000N, 180000000W)PreZero


Specifies how directions should be returned.DirectionsStyle


Return directions in a normal format. Default.Normal

Return directions in a terse format. Terse directionsare more suitable for wireless devices.

Terse

Specifies how GetTravelDirections should return distance values.DistanceUnits


Return distance in feet.Feet






Return distance in kilometers.Kilometers

Return distance in meters.Meters

Return distance in miles. Default.Miles

Return distance in yards.Yards

Specifies how GetTravelDirections should return time.TimeUnits


Return time in hours.Hours

Return time in minutes. Default.Minutes

Return time in seconds.Seconds

Specifies the focus of the route. A focused route is a subset of the wholeroute that concentrates on either the beginning or end of the route. A

FocusOfRoute

route focused at the start will route the user from their origin to (andincluding) the first major highway. A route focused at the end will routethe user from the last major highway in the route (including that highway)to the destination. If there are no major highways in the route, thefocused route will be the same as an unfocused route.


Return just the start of the route.Start

Return just the end of the route.End

Return the whole route. Default.None

Specifies whether the routing calculation uses the historic traffic speeds.These speeds are based on different time-of-day buckets. The data


must have historic traffic speeds included in order to use this feature.The data for each country/region has the same bucket definitions, wherethe speeds for these bucket values may vary. The options are:

The default value. Historic traffic data is not used in thecalculation. Instead an averaged speed value is used.

None

Calculate routes with the peak AM speeds. The AMPeaktime bucket is from 07:00 to 10:00hr time of day.

AMPeak

Calculate routes with the peak PM speeds. The PMPeaktime bucket is from 16:00 to 19:00hr time of day.

PMPeak

Calculate routes with the off peak (daytime) speeds.The OffPeak time bucket is from 10:00 to 16:00hr timeof day.

OffPeak

Calculate routes with the nighttime speeds. The Nighttime bucket is from 22:00 to 04:00hr time of day.

Night

Specifies whether GetTravelDirections re-orders the intermediate pointsin an optimal manner during route computation.

OptimizeIntermediatePoints

Yes, optimize intermediate points. Directions optimally ordersthe intermediate points. Default.

Y




No, do not optimize intermediate points. Directions preservesthe specified order of the points.

N

Directions

Table 29: Get Travel Directions Direction Options


Specifies whether to return the distance for the route.ShowDistance

Yes, return the distance for the route. Default.Y

No, do not return the distance for the route.N

Specifies whether to return turn-by-turn directions for the route. Thisoption is enabled by default.

ReturnRouteDirections

Yes, return textual turn-by-turn directions. Default.Y

No, do not return textual turn-by-turn directions.N

Specifies whether to return a set of latitude/longitude points thatrepresent a geometry for a segment within a route. The segment

ReturnSegmentGeometry

geometry is used to create the route geometry. The output of this fieldis shown within the RouteDirections output field. For more informationabout route geometry, see What is Route Geometry? on page 84.

Specifies whether to return a set of latitude/longitude points thatrepresent a route geometry. The route geometry can be used to createa route map and to perform analysis on the route.

ReturnRouteGeometry


Return all points in the route geometry.All

Return just the end points of each route segmentgeometry.

End

Do not return route geometry. Default.None

Specifies the language in which GetTravelDirections should returndirections.

DefaultLanguage


Return directions in Chinese (Taiwan).zh_TW

Return directions in Croatian.hr

Return directions in Czech.cs

Return directions in Danish.da

Return directions in Dutch.nl

Return directions in English. Defaulten

Return directions in American English.en_US

Return directions in Estonian.et

Return directions in Finnish.fi

Return directions in French.fr

Return directions in German.de




Return directions in Hungarian.hu

Return directions in Italian.it

Return directions in Japanese.ja

Return directions in Latvian.lv

Return directions in Lithuanian.lt

Return directions in Norwegian.no

Return directions in Portuguese.pt

Return directions in Romanian.ro

Return directions in Slovak.sk

Return directions in Slovenian.sl

Return directions in Spanish.es

Return directions in Swedish.sv

Return directions in Russian.ru

Return directions in Turkish.tr

Specifies whether GetTravelDirections should return the time it takesto follow a direction within the route.

ShowTime

Yes, return the time for the route. Default.Y

No, do not return the time for the route.N

Specifies whether GetTravelDirections should return all names for agiven street in the directions or if it should return just the primary namefor a street.

ShowPrimaryNameOnly

Yes, return just the primary name.Y

Return all names for a street. Default.N

What is Route Geometry?

A route geometry is a series of latitude/longitude points that form a route. A route geometry can be assimple as a single point, such as a route that starts and ends on the same street segment:

Since the starting point is always known the route geometry in this very simple example could be justthe end point. So if A is the starting point, the route geometry could be the latitude/longitude of point B.

In a more complex route geometry involving multiple route segments there can be several points in theroute geometry. Consider the route highlighted below which starts at point A and ends at point C, travelingthrough intersections X, Y, and B:



In this route, the full route geometry would consist of the latitude/longitude of points A, X, Y, B, and C.Note that you can control which points to actually return and may choose to include all points in the routegeometry or just the end points of each route segment. In the above example, the end points are B andC, since A to B is one route segment and B to C is another.

Travel Options

This set of preferences allows you to set the desirability for each road type. For instance, you can requestthat the server attempt to avoid all of the major road types.

Table 30: Travel Preferences Options


Specifies the priority to give to different types of roads when determiningthe route.

RoadType_<type>

• access way• back road• connector• ferry• footpath• limited access dense urban• limited access rural• limited access suburban• limited access urban• local road dense urban• local road rural• local road suburban• local road urban• major local road dense urban• major local road rural• major local road suburban• major local road urban• major road dense urban• major road rural• major road suburban• major road urban• minor local road dense Urban• minor local road rural• minor local road suburban




• minor local road urban• mormal road dense urban• normal road rural• normal road rural• normal road urban• primary highway dense urban• primary highway rural• primary highway suburban• primary highway urban• ramp dense urban• ramp limited access• ramp major road• ramp primary highway• ramp rural• ramp secondary highway• ramp urban• ramp suburban• secondary highway dense urban• secondary highway rural• secondary highway suburban• secondary highway urban

For each road type you can specify one of the following:

Exclude the road type from routes if possible.Avoid

It is not always possible to exclude a road typefrom the travel directions. Depending on the

Note:

situation, the alternative to an avoided road typemay be so poor that the software will choose aroute that uses an avoided road type. Also, if thestarting or ending point lies along a segment whoseroad type has been avoided, the software will stilluse that segment.

Prefer the road type over other road types.High

Prefer other road types over this road type.Low

Give this road type equal preference with other road types.If no preference is specified for a road type, the default isMedium.

Medium

Specifies whether to include all roads in the calculation or just majorroads. If you choose to include only major roads, performance willimprove but accuracy may decrease.

MajorRoads

This map represents a travel boundary with travel allowed on all roads:




This map represents a travel boundary with travel restricted to majorroads only:




Specifies that a Commercial Vehicle Restrictions (CVR) priority is usedwhen determining the route.

UseVehicleRestriction


Specifies that barriers will be removed when determining the route.These restrictions aremost often when a commercial vehicle is prohibited

LooseningBarrierRestrictions




from traversing a segment due to local ordinance or a commercial vehicleis allowed on the segment but only when it must (for example, last mileaccess, local delivery, etc.). Routes where a barrier has been removedwill still have a higher route cost even if the route it shorter/faster thana route with no barrier.


Specifies that type of vehicle that will be restricted based on the height,weight, length, or width when determining the route. Commercial vehicles

VehicleType

are divided into different types ranging from short trailers to long triples.The Commercial Vehicle Restrictions attribution is organized on aper-vehicle type basis. This means it is entirely possible for a segmentto be preferred for one vehicle type and the same segment have arestriction for another type of vehicle.

This is a string value. The types of vehicles are:ALL,STRAIGHT,SEMI_TRAILOR,STANDARD_DOUBLE,INTERMEDIATE_DOUBLE,LONG_DOUBLE,TRIPLE,OTHER_LONG_COMBINATION_VEHICLE

Specifies that maximum length of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleLength

Specifies the length unit of a vehicle that will be restricted whendetermining the route.

VehicleLengthUnit

This is a string value. The types of length are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximum height of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleHeight

Specifies the Height unit of a vehicle that will be restricted whendetermining the route.

VehicleHeightUnit

This is a string value. The types of Height are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximumWidth of a vehicle. Any vehicles over this valuewill be restricted when determining the route.

DefaultVehicleWidth

Specifies the Width unit of a vehicle that will be restricted whendetermining the route.

VehicleWidthUnit

This is a string value. The types of Width are:Feet,Yards,Miles,Meters,Kilometers

Specifies that maximum Weight of a vehicle. Any vehicles over thisvalue will be restricted when determining the route.

DefaultVehicleWeight

Specifies the Weight unit of a vehicle that will be restricted whendetermining the route.

VehicleWeightUnit

This is a string value. The types of Weight are:Kilogram,Pound,Metric Tonnes,Ton

Transient Options

This set of preferences allows you to set transient updates for each request. For instance, you canrequest that the server attempt to avoid all of the major road types. Each request can contain one ormore updates.



The transient update functionality is only available through the SOAP API, and is not availablethrough the Management Console or Enterprise Designer.

Note:

Table 31: Transient Update Options


Point updates are changes applied to a corresponding point (Latitude,Longitude). For a particular point, you can: exclude the point, set the

PointUpdate

speed of the point or change (increase or decrease) the speed of thepoint by a value or percentage. Youmust specify a Pointwhich consistsof a Latitude and Longitude, then specify one of the following:

This is a speed update where you define the newspeed of the point by specifying the velocity unit and

Velocity

new velocity. For speed updates, the velocity unit canhave one of the following values: kph (kilometers perhour), mph (miles per hour), mps (meters persecond).

This is a speed update where you define an increasein the speed of the point by specifying either the

SpeedIncrease


This is a speed update where you define a decreasein the speed of the point by specifying either the

SpeedDecrease


This is a sting value to exclude the specified pointfrom the route calculation. To exclude a point you

Exclude

need to specify the point and include the Excludeparameter defined as Y. Valid values are Y (yes) andN (no).

Segment updates are changes applied to a corresponding segment ID(Latitude, Longitude). For a particular segment, you can: exclude the

SegmentUpdate

segment, set the speed of the segment, change (increase or decrease)the speed of the segment by a value or percentage, or change the roadtype of the segment. You must specify a valid RoutingSegmentID,then specify one of the following:


Velocity



SpeedIncrease

velocity (unit and value) or a percentage to increase




the speed. For speed updates, the velocity unit canhave one of the following values: kph (kilometers perhour), mph (miles per hour), mps (meters persecond).


SpeedDecrease


This is a string value to change the value of the roadtype for the segment for the route calculation.

RoadType


• access way• back road• connector• ferry• footpath• limited access dense urban• limited access rural• limited access suburban• limited access urban• local road dense urban• local road rural• local road suburban• local road urban• major local road dense urban• major local road rural• major local road suburban• major local road urban• major road dense urban• major road rural• major road suburban• major road urban• minor local road dense Urban• minor local road rural• minor local road suburban• minor local road urban• mormal road dense urban• normal road rural• normal road rural• normal road urban• primary highway dense urban• primary highway rural• primary highway suburban• primary highway urban• ramp dense urban




• ramp limited access• ramp major road• ramp primary highway• ramp rural• ramp secondary highway• ramp urban• ramp suburban• secondary highway dense urban• secondary highway rural• secondary highway suburban• secondary highway urban

This is a sting value to exclude the specified segmentfrom the route calculation. To exclude a segment you

Exclude

need to specify the segment ID and include theExclude parameter defined as Y. Valid values areY (yes) and N (no).

Road type updates are changes applied to a corresponding road type.For a particular road type, you can: set the speed of the roadtype, or

RoadTypeUpdate

change (increase or decrease) the speed of the road type by a valueor percentage. You must specify a RoadType to update (see the aboveroad types in the segment update), then specify one of the following:


Velocity



SpeedIncrease



SpeedDecrease


GetTravelDirections Transient Update SOAP ExampleThe following shows a standard GetTravelDirections SOAP request with all of the transient update optionsavailable (not a working example, this is used to show all the syntax). You can have multiple Updatedefinitions within a TravelDirectionTransientUpdate. You can only have a single update type



(PointUpdate, SegmentUpdate, or RoadTypeUpdate) within an Update. You can also only havea single update within one of the update types (PointUpdate, SegmentUpdate, or RoadTypeUpdate).

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetTravelDirections"xmlns:typ="http://www.g1.com/services/erm/types">


<get:GetTravelDirectionsRequest><get:input_port>

<get:PointToPointRequest><get:RoutePoints>

<get:RoutePoint><get:Latitude>33.751748</get:Latitude>

<get:Longitude>-84.364014</get:Longitude></get:RoutePoint><get:RoutePoint><get:Latitude>33.664925</get:Latitude><get:Longitude>-80.90332</get:Longitude>

</get:RoutePoint></get:RoutePoints>

<get:Language>en_US</get:Language><get:TravelDirectionTransientUpdate>

<typ:Update><typ:PointUpdate>

<typ:Point><typ:Latitude>?</typ:Latitude><typ:Longitude>?</typ:Longitude>

</typ:Point><typ:SpeedUpdate>

<typ:Velocity VelocityUnit=""/><typ:SpeedIncrease>

<typ:Velocity VelocityUnit=""/><typ:Percentage>?</typ:Percentage>

</typ:SpeedIncrease><typ:SpeedDecrease>

<typ:VelocityVelocityUnit="?">?</typ:Velocity>

<typ:Percentage>?</typ:Percentage></typ:SpeedDecrease>

</typ:SpeedUpdate><typ:Exclude>?</typ:Exclude>

</typ:PointUpdate><typ:SegmentUpdate><typ:RoutingSegmentID>?</typ:RoutingSegmentID>

<typ:SpeedUpdate><typ:Velocity

VelocityUnit="?">?</typ:Velocity><typ:SpeedIncrease>


<typ:Percentage>?</typ:Percentage></typ:SpeedIncrease><typ:SpeedDecrease>



</typ:SpeedUpdate><typ:RoadType>?</typ:RoadType><typ:Exclude>?</typ:Exclude>

</typ:SegmentUpdate><typ:RoadTypeUpdate>

<typ:RoadType>?</typ:RoadType><typ:SpeedUpdate>


<typ:SpeedIncrease><typ:Velocity



VelocityUnit="?">?</typ:Velocity><typ:Percentage>?</typ:Percentage>




</typ:SpeedUpdate></typ:RoadTypeUpdate>

</typ:Update></get:TravelDirectionTransientUpdate>

</get:PointToPointRequest></get:input_port>

</get:GetTravelDirectionsRequest></soapenv:Body>

</soapenv:Envelope>

ResponseGetTravelDirections returns the following fields:

Table 32: GetTravelDirections Outputs


The distance of each segment in the route.StringDistance

The unit of measurement for distance.StringDistanceUnits

Value of the format used to generate directions.StringFormat

Language of the directions.StringLanguage

Turn-by-turn directions for the route.ListRouteDirections

A geometry object containing the coordinates of each pointin the route. For more information, see What is RouteGeometry? on page 84

Geometryobject

RouteGeometry

.

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

Total time it takes to follow the route in minutes.StringTime

The unit of measurement for time.StringTimeUnits



GetRouteDataGetRouteData returns routing segment information for a point or segment ID. When you specify a point,the closest route segments are returned. When you specify a segment ID, the route segment for thatsegment ID is returned.

Get Route Data is only available as a service (Management Console and SOAP web service).Get Route Data is not available through a stage or REST API. It is also not available through theJava, C++, C, .NET, or COM APIs.

Note:

GetRouteData is part of the Enterprise Routing Module.

Resource URL

http://server:port/soap/GetRouteData

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.g1.com/services/GetRouteData"><soapenv:Header/><soapenv:Body>

<get:GetRouteDataRequest><get:options>

<get:DataSetResourceName>US</get:DataSetResourceName><get:CoordinateSystem>epsg:4326</get:CoordinateSystem>

</get:options><get:rows>

<get:row><get:RoutingData>

<get:RouteDataPoint><get:Longitude>-74.843</get:Longitude><get:Lattitude>40.0077</get:Lattitude>

</get:RouteDataPoint></get:RoutingData>

</get:row></get:rows>

</get:GetRouteDataRequest></soapenv:Body>

</soapenv:Envelope>


Some of the segment information has been removed from this example to shorten it.Note:


<GetRouteDataResponse xmlns="http://www.g1.com/services/GetRouteData">

<rows><row>

<Segments><SegmentDetails>

<Segment><RoutingSegmentID>b81740d3:4b3526</RoutingSegmentID>

<SegmentData><PrimaryName>New Jersey Tpke S</PrimaryName><PrimaryNameLanguage>en</PrimaryNameLanguage><AlternateNameList>

<AlternateName><Name>New Jersey Tpke S</Name><Language>en</Language>



</AlternateName></AlternateNameList><SegmentLength>8.397</SegmentLength><SegmentLengthUnit>Miles</SegmentLengthUnit><TimeTaken>7.866666666666666</TimeTaken><TimeUnit>Minutes</TimeUnit><TurnAngle>0.0</TurnAngle><TurnAngleUnit>degree</TurnAngleUnit><CompassDirection/>

<speedOfTravel>64.01366022429013</speedOfTravel>

<speedOfTravelUnit>Miles/hour</speedOfTravelUnit>

<RoadType>primary highway rural</RoadType><SegmentDirection>from_to</SegmentDirection><StartJunctionType>Other</StartJunctionType><EndJunctionType/><IsRoundabout>false</IsRoundabout><IsTollRoad>true</IsTollRoad><PointsInSegment>

<RouteDataPoint><Longitude>-74.823861</Longitude><Lattitude>40.024421</Lattitude>

</RouteDataPoint><RouteDataPoint>

<Longitude>-74.824133</Longitude><Lattitude>40.024149</Lattitude>

</RouteDataPoint>...

</PointsInSegment></SegmentData>

</Segment></SegmentDetails>

</Segments></row>

</rows></GetRouteDataResponse>

</soap:Body></soap:Envelope>

Request

Parameters for InputGetRouteData takes either a point latitude and longitude or a route segment ID as input. You also needto specify the route data source and coordinate system for the route data. The following table providesinformation on the format and layout of the input.

Table 33: GetRouteData Input Data


The point to query to return segment information. You must specify a pointwhich consists of a Latitude and Longitude.

RouteDataPoint

The route segment ID to return segment information.RoutingSegmentID

The name of the database that contains the data to query for segmentinformation. Use the database name specified in the Enterprise Routing

DataSetResourceName

Module Routing Database Resource tool. For more information, see theSpectrum™ Technology Platform Administration Guide.





CoordinateSystem


For more information on EPSG codes, see www.spatialreference.org. Toretrieve a list of supported codespaces for EPSG, you can submit the SOAPrequest List Supported CoordSys by Code Space from the Geometry ServiceDemo page athttp://localhost:8080/Spatial/GeometryService/DemoPage.html.

Options

Table 34: Get Route Data Options


This is a sting value to specify the format of the coordinates for the pointdata returned in the response. The options are Decimal,DecimalAssumed, PreZero, PreZeroDecimal, and DegMinSec.

CoordinateFormat

This is a sting value to specify the format of the segment distance values(length of segment) returned in the response. The options are Feet,Yards, Miles, Meters, and Kilometers.

DistanceUnits

This is a sting value to specify the format of the segment time values(time to travel segment) returned in the response. The options areSeconds, Minutes and Hours.

TimeUnits

This is a sting value to specify the format of the segment speed valuesreturned in the response. The options are KPH (kilometers per hour),MPH (miles per hour) and MTPS (meters per second).

VelocityUnits

This is a sting value to specify the format of the segment turn values(turn angle units) returned in the response. The options are radian,degree, minute, second, grad and gon.

AngularUnits

This is a sting value to specify if the list of route preferences are returnedin the response. The options are Y or N. The default is no routepreferences are returned.

ReturnActualPreferences

This is a sting value to specify the amount of detail to be returned forthe segment geometry. The options are NONE, ALL, or END. If ALL is

ReturnSegmentGeometry

specified, the entire segment geometry will be returned. If END isspecified, only the end point for the segments will be returned. Thedefault is ALL segment geometries are returned.





Response

ResponseGetRouteData returns the following fields:

Table 35: GetRouteData Outputs


One or more route segment IDsStringRoutingSegmentID

All information for the route segmenet. This informationincludes:

StringSegmentData

• PrimaryName• PrimaryNameLanguage• AlternateNameList• SegmentLength• SegmentLengthUnit• TimeTaken• TimeUnit• TurnAngle• TurnAngleUnit• speedOfTravel• speedOfTravelUnit• RoadType• SegmentDirection• StartJunctionType• IsRoundabout• IsTollRoad• PointsInSegment

The route geometries (points) for the segment is returned inthe PointsInSegment parameter.

PersistentUpdatePersistentUpdate allows changes to the routing data that are made at the server level and apply to allroute requests or stages. These updates remain intact even if the server is restarted. Updates can bebased on four types:

1. Point Updates2. Segment Updates3. Road-Type Updates4. Reset Updates

Using persistent updates to make these types of modifications, you have the ability to:

• Exclude a point• Exclude a segment• Set the speed of a point, segment, or road type• Change (increase or decrease) the speed of a point, segment, or road type by a value• Change (increase or decrease) the speed of a point, segment, or road type by a percentage



Persistent Update is only available as a service (Management Console and SOAP web service).Persistent Update is not available through a stage or REST API. It is also not available throughthe Java, C++, C, .NET, or COM APIs.

Note:

Since persistent updates are changes made on a system-wide basis for routing data and allupdates will persist, they should be used with caution.

Note:

PersistentUpdate is part of the Enterprise Routing Module.

Resource URL

http://server:port/soap/PersistentUpdate

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:per="http://www.g1.com/services/PersistentUpdate"xmlns:typ="http://www.g1.com/services/erm/types">


<per:PersistentUpdateRequest><per:context>

<per:account.id>admin</per:account.id><per:account.password>admin</per:account.password>

</per:context><per:options>

<per:DataSetResourceName>US</per:DataSetResourceName><per:RestoreDefaults>N</per:RestoreDefaults>

</per:options><per:rows>

<per:row><per:PersistentUpdates>

<typ:UpdateList><typ:Update>

<typ:PointUpdate><typ:Point>

<typ:Latitude>34.40691</typ:Latitude><typ:Longitude>-80.062866</typ:Longitude>


<typ:VelocityVelocityUnit="mph">15</typ:Velocity>

</typ:SpeedUpdate></typ:PointUpdate>

</typ:Update></typ:UpdateList>

</per:PersistentUpdates></per:row>

</per:rows></per:PersistentUpdateRequest>




Request


Table 36: PersistentUpdate Input Options


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

DataSetResourceName




CoordinateSystem


For more information on EPSG codes, see www.spatialreference.org. Toretrieve a list of supported codespaces for EPSG, you can submit the SOAPrequest List Supported CoordSys by Code Space from the Geometry ServiceDemo page athttp://localhost:8080/Spatial/GeometryService/DemoPage.html.

All persistent updates made to the DataSetResourceNamewill be revertedto their original state. Specify Y to restore the defaults.

RestoreDefaults

Point Options

This set of preferences allows you to set the point updates for each persistent update. Point updatesare changes applied to a corresponding point (Latitude, Longitude). For a particular point, you can:exclude the point, set the speed of the point or change (increase or decrease) the speed of the point bya value or percentage.

You must specify a Point which consists of a Latitude and Longitude, then specify the type ofpoint update. Each request can contain one or more updates.

Table 37: Point Update Options


The point to perform the persistent update. You must specify a pointwhich consists of a Latitude and Longitude.

Point

This is a sting value to exclude the specified point from all routecalculations. To exclude a point you need to specify the point and include

Exclude

the Exclude parameter defined as Y. Valid values are Y (yes) and N(no).






This is a speed update where you define the new speed of the point byspecifying the velocity unit and new velocity. For speed updates, the

Velocity

velocity unit can have one of the following values: kph (kilometers perhour), mph (miles per hour), mps (meters per second).

This is a speed update where you define an increase in the speed ofthe point by specifying either the velocity (unit and value) or a percentage

SpeedIncrease

to increase the speed. For speed updates, the velocity unit can haveone of the following values: kph (kilometers per hour), mph (miles perhour), mps (meters per second).

This is a speed update where you define a decrease in the speed of thepoint by specifying either the velocity (unit and value) or a percentage

SpeedDecrease

to decrease the speed. For speed updates, the velocity unit can haveone of the following values: kph (kilometers per hour), mph (miles perhour), mps (meters per second).

Segment Options

This set of preferences allows you to set the segment updates for each persistent update. Segmentupdates are changes applied to a corresponding route segment ID. For a particular segment, you can:exclude the segment, set the speed of the segment, change (increase or decrease) the speed of thesegment by a value or percentage, or change the road type of the segment.

You must specify a RoutingSegmentID, then specify the type of segment update. Each request cancontain one or more updates.

Table 38: Segment Update Options


The route segment ID to perform the persistent update.RoutingSegmentID

This is a sting value to exclude the specified segment from all routecalculations. To exclude a segment you need to specify the segment

Exclude

ID and include the Exclude parameter defined as Y. Valid values areY (yes) and N (no).

This is a string value to change the value of the road type for thesegment for the route calculation.

RoadType


• access way• back road• connector• ferry• footpath• limited access dense urban• limited access rural• limited access suburban• limited access urban• local road dense urban• local road rural




• local road suburban• local road urban• major local road dense urban• major local road rural• major local road suburban• major local road urban• major road dense urban• major road rural• major road suburban• major road urban• minor local road dense Urban• minor local road rural• minor local road suburban• minor local road urban• mormal road dense urban• normal road rural• normal road rural• normal road urban• primary highway dense urban• primary highway rural• primary highway suburban• primary highway urban• ramp dense urban• ramp limited access• ramp major road• ramp primary highway• ramp rural• ramp secondary highway• ramp urban• ramp suburban• secondary highway dense urban• secondary highway rural• secondary highway suburban• secondary highway urban

This is a speed update where you define the new speed of the segmentby specifying the velocity unit and new velocity. For speed updates, the

Velocity


This is a speed update where you define an increase in the speed ofthe segment by specifying either the velocity (unit and value) or a

SpeedIncrease

percentage to increase the speed. For speed updates, the velocity unitcan have one of the following values: kph (kilometers per hour), mph(miles per hour), mps (meters per second).

This is a speed update where you define a decrease in the speed of thesegment by specifying either the velocity (unit and value) or a percentage

SpeedDecrease




Road-type Options

This set of preferences allows you to set the road type updates for each persistent update. Road typeupdates are changes applied to a corresponding road type. For a particular road type, you can: set thespeed of the roadtype, or change (increase or decrease) the speed of the road type by a value orpercentage.

You must specify a RoadType, then specify the type of update. Each request can contain one or moreupdates.

Table 39: Road Type Update Options


This is a string value to change the speed value of the road type for theroute calculation.

RoadType

The road 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• NormalRoadSuburban• NormalRoadUrban• PrimaryHighwayDenseUrban• PrimaryHighwayRural• PrimaryHighwaySuburban• PrimaryHighwayUrban• RampDenseUrban• RampLimitedAccess




• RampMajorRoad• RampPrimaryHighway• RampRural• RampSecondaryHighway• RampSuburban• RampUrban• SecondaryHighwayDenseUrban• SecondaryHighwayRural• SecondaryHighwaySuburban• SecondaryHighwayUrban

This is a speed update where you define the new speed of the segmentby specifying the velocity unit and new velocity. For speed updates, the

Velocity


This is a speed update where you define an increase in the speed ofthe segment by specifying either the velocity (unit and value) or a

SpeedIncrease

percentage to increase the speed. For speed updates, the velocity unitcan have one of the following values: kph (kilometers per hour), mph(miles per hour), mps (meters per second).

This is a speed update where you define a decrease in the speed of thesegment by specifying either the velocity (unit and value) or a percentage

SpeedDecrease


Reset Options

This set of preferences allows you to reset (undo) the updates for each point, segment, or road typeupdate. This will simply clear the updates already applied for a point/segment/road type from the serverand set them to their default values.

Table 40: Reset Update Options


The point that has the persistent update to be reset. You must specifya point which consists of a Latitude and Longitude, and specify the

PointReset

type of update to be reset for the point. The options for the Reset Typeare Exclude and Speed.

The segment that has the persistent update to be reset. Youmust specifythe RoutingSegmentID and specify the type of update to be reset for

SegmentReset

the segment. The options for the Reset Type are Exclude, RoadType, and Speed.

The road type that has the persistent update to be reset. By specifyinga road type, the speed update applied to that type will be reset.

RoadTypeReset



Persistent Update SOAP Example

The following shows a standard PersistentUpdate SOAP request with all of the update options available(not a working example, this is used to show all the request syntax). You can have multiple Update orReset definitions within a PersistentUpdates. You can only have a single update type (PointUpdate,SegmentUpdate, or RoadTypeUpdate) within an Update. Similarily you can only have a single resettype (PointReset, SegmentReset, or RoadTypeReset) within an Reset. You can also only have asingle update or reset within one of the update or reset types.

To perform a reset on all updates, you only need to specify the DataSetResourceName and set theRestoreDefaults parameter to Y.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:per="http://www.g1.com/services/PersistentUpdate"xmlns:typ="http://www.g1.com/services/erm/types">


<per:PersistentUpdateRequest><per:options>

<per:DataSetResourceName>US</per:DataSetResourceName><per:CoordinateSystem>?</per:CoordinateSystem>

<per:RestoreDefaults>N</per:RestoreDefaults></per:options><per:rows>

<per:row><per:PersistentUpdates>

<typ:UpdateList><typ:Update>

<typ:PointUpdate><typ:Point>

<typ:Latitude>?</typ:Latitude><typ:Longitude>?</typ:Longitude>


<typ:Velocity VelocityUnit=""/><typ:SpeedIncrease>

<typ:Velocity VelocityUnit=""/><typ:Percentage>?</typ:Percentage>




</typ:SpeedUpdate><typ:Exclude>?</typ:Exclude>

</typ:PointUpdate><typ:SegmentUpdate><typ:RoutingSegmentID>?</typ:RoutingSegmentID>

<typ:SpeedUpdate><typ:Velocity






</typ:SpeedUpdate><typ:RoadType>?</typ:RoadType><typ:Exclude>?</typ:Exclude>

</typ:SegmentUpdate><typ:RoadTypeUpdate>

<typ:RoadType>?</typ:RoadType><typ:SpeedUpdate>

<typ:Velocity








</typ:SpeedUpdate></typ:RoadTypeUpdate>

</typ:Update></typ:UpdateList><typ:ResetList>

<typ:Reset><typ:PointReset ResetType="?">

<typ:Point><typ:Latitude>?</typ:Latitude><typ:Longitude>?</typ:Longitude>

</typ:Point></typ:PointReset><typ:SegmentReset ResetType="?">

<typ:RoutingSegmentID>?</typ:RoutingSegmentID></typ:SegmentReset><typ:RoadTypeReset>

<typ:RoadType>?</typ:RoadType></typ:RoadTypeReset>

</typ:Reset></typ:ResetList>

</per:PersistentUpdates></per:row>

</per:rows></per:PersistentUpdateRequest>


Response

ResponsePersistentUpdate returns the following field:

Table 41: PersistentUpdate Outputs


Returns if the update or reset was completed successfully.StringSuccessMessage

Enterprise Tax Module

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

• Latitude/longitude coordinates



• FIPS state codes and county codes• County names• MCD/CCD codes and names• CBSA/CSA 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.

• Sales and Use Tax Rates—Using the optional Pitney Bowes Software Sales and Use Tax Rate file,AssignGeoTAXInfo can return sales and use tax rates for each of the assigned tax jurisdictions aswell as the total tax rate for the assigned locations.

AssignGeoTAXInfo is part of the Enterprise Tax Module.

Resource URL

http://server:port/soap/AssignGeoTaxInfo

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ass="http://www.pb.com/spectrum/services/AssignGeoTAXInfo"xmlns:spec="http://spectrum.pb.com/">


<ass:AssignGeoTAXInfoRequest><ass:input_port>

<ass:Address><ass:AddressLine1>1 Global View</ass:AddressLine1>



<ass:City>Troy</ass:City><ass:StateProvince>NY</ass:StateProvince><ass:PostalCode>12180</ass:PostalCode>

</ass:Address></ass:input_port>

</ass:AssignGeoTAXInfoRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:AssignGeoTAXInfoResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/AssignGeoTAXInfo"><ns3:output_port>

<ns3:Address><ns3:Confidence>100.0</ns3:Confidence><ns3:ProcessedBy>GTX</ns3:ProcessedBy><ns3:Census.MatchCode>S</ns3:Census.MatchCode><ns3:Census.MatchLevel>Street</ns3:Census.MatchLevel><ns3:County.Code>083</ns3:County.Code><ns3:County.Name>Rensselaer</ns3:County.Name><ns3:StateCode>36</ns3:StateCode><ns3:LatLong>42.683028-073.702968</ns3:LatLong><ns3:LatLong.MatchCode>R</ns3:LatLong.MatchCode><ns3:LatLong.MatchLevel>Rooftop</ns3:LatLong.MatchLevel><ns3:Latitude>42.683028</ns3:Latitude><ns3:Longitude>-073.702969</ns3:Longitude><ns3:State.Abbreviation>NY</ns3:State.Abbreviation><ns3:Place.Code>00000</ns3:Place.Code>

<ns3:Place.IncorporatedFlag>Uninc</ns3:Place.IncorporatedFlag><ns3:AddressLine1>1 GLOBAL VW</ns3:AddressLine1><ns3:City>TROY</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>121808371</ns3:PostalCode>

<ns3:AddressMatch.MatchCode>S80</ns3:AddressMatch.MatchCode>

<ns3:AddressMatch.LocationCode>AS0</ns3:AddressMatch.LocationCode><ns3:AddressMatch.LastLine>TROY, NY

12180-8371</ns3:AddressMatch.LastLine><ns3:AddressMatch.Zip>12180</ns3:AddressMatch.Zip><ns3:AddressMatch.Zip4>8371</ns3:AddressMatch.Zip4><ns3:AddressMatch.GenRC>S</ns3:AddressMatch.GenRC>

<ns3:AddressMatch.DataTypeName>TOMTOM</ns3:AddressMatch.DataTypeName>

<ns3:MCD.DistanceToBorder>000002938</ns3:MCD.DistanceToBorder>

<ns3:Place.DistanceToBorder>00000000</ns3:Place.DistanceToBorder><ns3:GNISCode>000000000</ns3:GNISCode>


</ns3:AssignGeoTAXInfoResponse></soap:Body>

</soap:Envelope>

Request

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



Table 42: AssignGeoTAXInfo Input Data



AddressLine1


AddressLine2


AddressLine3


AddressLine4

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

String[10]

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

This field overrides the value specified in theDefaultBufferWidth option. Specify the border width in theunits specified by the DistanceUnits option.

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

For a multi-match outcome, indicates which match resultshould be returned; valid values are 1-9.

String [1]CandidateID

City nameString[50]

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]

Country

AssignGeoTAXInfo only supports US addresses.Note:

Company or firm nameString[var]

FirmName

Nine-digit ZIP CodeString [9]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]

StateProvince

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

Long[10]

UserBufferWidth

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

This field overrides the value specified in theDefaultBufferWidth option. Specify the border width in theunits specified by the DistanceUnits option.




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

Matching OptionsMatching options control the address search methodology and match results handling returned byAssignGeoTAXInfo. Table 43: AssignGeoTAXInfo Matching Options on page 109 lists the addresssearch and matching options.

Table 43: AssignGeoTAXInfo Matching Options


Optional files: The following options enable the database resource(s) to use in the search process.

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

UseGeoTaxAuxiliaryFile

Use the GeoTAX Auxiliary file for matching.Y

Do not use the GeoTAX Auxiliary file for matching. (default)N

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

UseAuxiliaryFile

the Enterprise Tax Module uses to override results from the masterfiles in street-level matching.

Use the User Auxiliary file for matching.Y

Do not use the User Auxiliary file for matching. (default)N

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

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.If a state match cannot be found, it attempts a match to the masterfiles.

Use the State-supplied file for matching.Y

Do not use the State-supplied file for matching. (default)N




Youmust install the appropriate State-supplied file to use theseoptions. For instructions, see the Spectrum™ TechnologyPlatform Installation Guide.

Note:

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

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.

UseRelaxedSecondaryMatching

Use relaxed secondary matching.Y

Do not use relaxed secondary matching. (default)N

Address Searching and Matching Options: The following options can be enabled for use in theaddress search and match processes.

Match modes determine the leniency used to make a match betweenyour input and the reference database. Select a match mode based

GsMatchMode

on the quality of your input and your desired output. For example, ifyou have an input database that is prone to errors, you may want toselect the relaxed match mode.

Requires a very tight match. This restrictive modegenerates the fewest match candidates, which decreases

0 - Exact

the processing time. When using this mode, ensure thatyour input is very clean; free of misspellings andincomplete addresses.

Requires a close match and generates a moderatenumber of match candidates. (default)

1 - Close

Allows a loose match and generates the most matchcandidates, which increases the processing time and

2 -Relaxed

results in more multiple matches. Use this mode if youare not confident that your input is clean; free ofmisspellings and incomplete addresses. This is the onlymode that does not respect the street parity whenmakingan address match.

The search area options allow for searching the address' finance areaor an expanded area specified by distance.

GsSearchArea

Searches the entire finance area for a match. A finance area isa region defined by the U.S. Postal Service and typically consistsof a set of contiguous ZIP Codes.(default)

1

Searches the area specified by the radius in miles. The searcharea can be extended up to a 99-mile radius from the centroid

2

of the input ZIP Code to assist in finding a match when the inputaddress contains limited or inaccurate city or ZIP Codeinformation. The expanded area is confined to within the state'sborders.




Radius for search area.GsSearchRadius

Search radius. (default = 25 miles)1-99 miles

Looks for the correct first letter of a street address if the first letter ismissing or incorrect. The Enterprise Tax Module searches through the

GsEnableFirstLetterExpanded

alphabet looking for possible correct first letters to complete the streetaddress.

This feature is disabled by default and cannot be enabled inExact mode.

Note:

Enable first letter change matches.Y

Do not allow first letter change matches. (default)N

Matches to a house range input. Some business locations are identifiedby address ranges. For example, a shopping plaza could be addressed

GsEnableRangedAddress

as 10-12 Front St. - this is how business mail is typically addressed tosuch a business location. When this feature is enabled, the addressrange is geocoded to the interpolated mid-point of the range.

Allow address range matches.Y

Do not allow address range matches. (default)N

This option allows specifying the preferred way to match when bothan address and firm name are provided. The matching method can be

GsAlternateLookup

set to match to the address rather than the firm name or vice versa. Ifneither are specified, the default matching method is to match to theaddress line only.

Searches for street name, but if there isn't a match, will usethe firm name.

1

Looks up the firm name, but if there isn't a match, will usethe street name.

2

Searches only street records. (default)3

Amulti-match occurs whenmultiple equally-scored matches are foundin either the Points or Streets files and cannot be resolved to a single

GsMultiMatchResolution

best candidate. There are several choices for handling a multi-matchoutcome:

No matches are returned. (default)N

Return the first match candidate in the list.R

The information for all the match candidates is returned.A

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 OptionsGeocoding 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/longitude coordinates.

Table 44: AssignGeoTAXInfo Geocoding Options


Select the database resource to use in the geocoding process.Database.GTX

Latitude/Longitude placement: The following options can be set for the geocode result.

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

The offset distance is used in street-level geocoding to preventthe geocode from being in the middle of a street. It compensatesfor the fact that street-level geocoding returns a latitude andlongitude point in the center of the street where the address islocated. Since the building represented by an address is not onthe street itself, you do not want the geocode for an address tobe a point on the street. Instead, you want the geocode torepresent the location of the building which sits next to the street.For example, an offset of 50 feet means that the geocode willrepresent a point 50 feet back from the center of the street. Thedistance is calculated perpendicular to the portion of the streetsegment for the address. Offset is also used to prevent addressesacross the street from each other from being given the same point.The following diagram shows an offset point in relation to theoriginal point.

No offset. (default)0

Twenty feet offset from street center line.20




Forty feet offset from street center line.40

Sixty feet offset from street center line.60

Specifies if AssignGeoTAXInfo should squeeze the street endpoints when determining the geocode of an address in street-level

Squeeze

matching. The squeeze value is 5% (2.5% from each endpoint).The following diagram compares the end points of a streetsegment to the squeezed end points of a street segment.

Apply squeeze.Y

Do not apply squeeze. (default)N

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

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: 9000 00N180 00 00W.

DegMinSec

Expanded Geocoding options: The following options enable additional geocoding functionality.

Address point interpolation uses a patented process that improvesupon regular street segment interpolation by inserting point datainto the interpolation process.

GsEnableAddressPointInterpolation

This feature is only for use with point-level geocoding.Note:

Amatch is first attempted using the loaded points data. If an exactpoint match is found in the points data, then searching ceasesand the point match is returned. If an exact point match was notfound, the Enterprise Tax Module attempts to find high and lowboundary address points to use for address point interpolation.

Enable address point interpolation.Y

Disable address point interpolation. (default)N

Minimum geocode quality:




The default search does not perform a search of geographiccentroids. When enabled, the Geographic Fallback feature locates

GsEnableGeographicFallback

the first city, county and/or state centroid, and then matches fromthe set of possible matches found.

If a definitive match cannot be made, then return thenext higher level geographic centroid.

Y

Disable geographic fallback feature. (default)N

If an input street address cannot be found using the street numberand name, the Enterprise Tax Module then searches the input

GsEnableStreetCentroid

ZIP Code or city/state for the closest match. If the Enterprise TaxModule is able to locate the street, it returns a geocode along thematched street segment rather than the geocode for the enteredZIP Code or ZIP + 4.

When using street locator geocoding, if no exact matching housenumber is found, a match code of either E029 (no matching range,single street segment found), or E030 (nomatching range, multiplestreet segment) returns. For example, if you enter Main St andthere are both an E Main St and a W Main St within the input ZIPCode, then an E030 returns and the location code returned isreflective of the input ZIP Code. The location code returned beginswith a 'C' when matched to a single street segment, indicated byE029. The Enterprise Tax Module does not change the streetname on the output address.

If a street or point match cannot be made, then returna street level centroid.

Y

Do not return a street level centroid if a match cannotbe made. (default)

N

Boundary matching: The following options can be set when matching to a boundary file such as SPD,IPD, PAY, Place and MCD or user-defined.

Specifies the units in which to measure distance. One of thefollowing:

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. Thetax district boundary files are the Special Purpose District (SPD)

DefaultBufferWidth

file, the Insurance Premium District (IPD) file, the Payroll TaxDistrict (PAY) file, the Personal Property Tax District (PTD) fileand Place and MCD files.

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

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




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

DefaultUserBufferWidth

Distance units option. For information on buffers, see Bufferingon page 320. The default buffer width that you specify here can beoverridden on a record-by-record basis using the BufferWidthinput field.

To use buffers, the user-defined boundary file mustsupport buffers.

Note:

Output Data OptionsData options control the data returned by AssignGeoTAXInfo. Table 45: AssignGeoTAXInfo DataOptions on page 115 lists the output data options.

Table 45: AssignGeoTAXInfo Data Options


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

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• B—PB Software Sales and Use Tax Rate 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 116.

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 Taxware, select which vendor you use. This

TaxKey

controls the value returned in the GeoTAXKey output field. One of thefollowing:

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 sales and use tax rate type to return or None:TaxRate

Do not return sales and use tax rates. (default)N

Return the General sales and use tax rates.G

Return the Automotive sales and use tax rates.A

Return the Construction sales and use tax rates.C

Return the Medical sales and use tax rates.

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.

OutputFields

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

Output Format

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

Table 46: AssignGeoTAXInfo Output Format Options


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

OutputCasing


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

M

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

Response

Result IndicatorsThe following table lists the results returned from the address matching and geocoding process.



Table 47: Address Matching and Geocoding Status Output Fields

DescriptionMax.Field

Length(bytes)

Response Element

Indicates the confidence in the output provided; from 0to 100. The higher the score, the higher the confidence

4Confidence

in the match. Calculated based on the match results forindividual output fields, using the following algorithm:

Census.MatchCode + LatLong.StreetMatchCode +LatLong.MatchCode

The maximum confidence score is 100, so if thiscalculation results in a value greater than 100, theConfidence 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

Indicates the confidence surface type. Setting a non-zerobuffer width enables confidence generation. To

3Confidence.SurfaceType

determine a confidence level, a confidence surface isfirst generated. The confidence surface provides thesmallest possible area wherein an address is likely tobe located.

Undefined0

The search failed - the address was notfound.

1

Intersection confidence surface generated.2

Interpolated street segment.3

Point-level match.4

State confidence surface generated.5

County confidence surface generated.6

City confidence surface generated.7

Reserved8

A ZIP Code confidence surface generated.9

A ZIP+2 confidence surface generated.10

A ZIP+4 confidence surface generated.11

Reserved12




Length(bytes)

Response Element

A street centroid confidence surfacegenerated.

13

The Match Code indicates the portions of the addressthat matched or did not match to the reference file.

5AddressMatch.MatchCode

For the list of match codes, see Match Codes.

General Return Code indicating the type of match.2AddressMatch.GenRC

ZIP Code match5

ZIP+4 Code match9

User Auxiliary file matchA

Street Centroid matchC

Geographic Fallback matchF

State-supplied file matchG

Intersection matchI

Landmark Auxiliary file matchL

Multiple match (multi-match)M

Input Latitude/Longitude coordinatesmatchO

Address point matchP

Street address matchS

Aborted processing or expired databaseX

Did not matchBlank

Indicates the file from which the match was obtained.One of the following:

20AddressMatch.DataTypeName

• USPS• TIGER• TOMTOM - Streets• NAVTEQ - Streets• TOMTOM_POINT• CENTRUS_POINT• NAVTEQ_POINT• STATE_FILE• USER_AUXILIARY• LANDMARK_AUXILIARY

When there are multiple equally-scoredmatches, returnsthe number of multiple match candidates found.

2AddressMatch.NumCandidates

The Location Code indicates the methodology used tocomplete the geocode and may also provide someinformation about the quality of the geocode.

5AddressMatch.LocationCode

For the list of location codes, see Location Codes.




Length(bytes)

Response Element

Latitude/Longitude General Return Code. Denotes thelevel for which the geocode was determined.

2LatLong.MatchCode

ZIP + 2 centroid2

ZIP + 4 Code centroid4

Block group centroidB

City centroidC

IntersectionI

Match using the Landmark Auxiliary fileL

Latitude/longitude was inputO

Address-level based on street addressR

State centroidS

Census tract centroidT

Address-level match using the GeoTAXAuxiliary Database

U

ZIP Code centroid based on a five-digit ZIPcode

Z

No latitude/longitude determinednull

If the General Return Code (see Result Indicators) is"P" (point match), then the following are possible valuesand have the following meaning:

Latitude/Longitude coordinates from UserDictionary.

0

Latitude/Longitude coordinates from ParcelCentroid.

2

Latitude/Longitude coordinates from AddressPoint.

4

Latitude/Longitude coordinates from StructureCentroid.

5

Latitude/Longitude coordinates frommanually-placed Point.

7

Latitude/Longitude coordinates from Front DoorPoint.

8

Latitude/Longitude coordinates from DrivewayOffset Point.

9

Latitude/Longitude coordinates from StreetAccess Point.

A

Latitude/Longitude coordinates from BaseParcel Point.

B

Output street address return code.2LatLong.StreetMatchCode




Length(bytes)

Response Element

House number not found on streetH

Latitude/longitude not determined onauxiliary match

L

Street not found in ZIP CodeS

ZIP Code not found in street addressdatabase

Z

Street-level matching option not selectedN

The street was successfully matchednull

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 48: Auxiliary File Output Fields


Length(bytes)

Response Element

Data retrieved as a result of an auxiliary match from theuser-defined area of the auxiliary file.

301AuxiliaryData.AuxiliaryFile

Data retrieved as a result of a state match. Data contentand format vary depending on the state file used.

201AuxiliaryData.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 49: Census Data Output Fields


Length(bytes)

Response Element

Census Block ID.4Census.Block

Census Block Group code.2Census.BlockGroup

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

This field is always included in the outputregardless of whether or not you choose toinclude 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.19Census.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 theCensus.BlockCode.

7Census.Tract

Three-digit Federal Information Processing Standards(FIPS) county code extracted from theCensus.BlockCode.

4County.Code


Note:

Name of the county.26County.Name




Length(bytes)

Response Element


Note:

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

6MCD.Code

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

41MCD.Name

An address can be compared to a Minor Civil Division(MCD)/county subdivision file (Cousub.txt). This output

2MCD.PointStatus

field returns the result for a comparison between thematched address point to the polygon defined by theCousub.txb file.

For more information on buffers, seeBuffering on page320.

The buffer distance for Cousub.txb is internallyset to zero and cannot be modified.

Note:

The point is in the polygon.P

The point is in the buffer area inside thepolygon.

I

The point is in the buffer area and outsideof the polygon.

B

Polygon not found.blank

Returns the distance in feet between the matchedaddress point to the polygon defined by the Cousub.txbfile.

10MCD.DistanceToBorder

Provides the percentage overlap of the geocode to theMCD polygon layer. The returned percentage valuedescribes the probability that the point falls in the MCD.

4MCD.Confidence

Core Based Statistical Area (CBSA) code.6CBSA.Code

Core Based Statistical Area (CBSA) name.76CBSA.Name

Indicates if the CBSA is a "Metropolitan Statistical Area"or a "Micropolitan Statistical Area".

2CBSA.MetroFlag

Metropolitan Statistical Area - A Core BasedStatistical Area associated with at least one

Y

urbanized area that has a population of at least50,000. TheMetropolitan Statistical Area comprisesthe central county or counties containing the core,plus adjacent outlying counties having a highdegree of social and economic integration with thecentral county as measured through commuting.




Length(bytes)

Response Element

Micropolitan Statistical Area - A Core BasedStatistical Area associated with at least one urban

N

cluster that has a population of at least 10,000, butless than 50,000. The Micropolitan Statistical Areacomprises the central county or counties containingthe core, plus adjacent outlying counties having ahigh degree of social and economic integration withthe central county asmeasured through commuting.

Core Based Statistical Area Division (CBSAD) code.6CBSAD.Code

Core Based Statistical Area Division (CBSAD) name.73CBSAD.Name

Combined Statistical Area (CSA) code.4CSA.Code

Combined Statistical Area (CSA) name.78CSA.Name

Two-character state abbreviation.3State.Abbreviation

This field is always included in the outputregardless of whether or not you choose toinclude census data in the output

Note:

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

3StateCode


Note:

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 50: Latitude/Longitude Output Fields


Length(bytes)

Response Element

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

8Latitude

Latitude directional.2Latitude.Directional

NorthN

SouthS




Length(bytes)

Response Element

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

23LatLong

Latitude/Longitude General Return Code. Denotes thelevel for which the geocode was determined.

2LatLong.MatchCode

ZIP + 2 centroid2

ZIP + 4 Code centroid4

Block group centroidB

City centroidC

IntersectionI

Match using the Landmark Auxiliary fileL

Latitude/longitude was inputO

Address-level based on street addressR

State centroidS

Census tract centroidT

Address-level match using the GeoTAXAuxiliary Database

U

ZIP Code centroid based on a five-digit ZIPcode

Z

No latitude/longitude determinednull

If the General Return Code (see Result Indicators) is"P" (point match), then the following are possible valuesand have the following meaning:

Latitude/Longitude coordinates from UserDictionary.

0

Latitude/Longitude coordinates from ParcelCentroid.

2

Latitude/Longitude coordinates from AddressPoint.

4

Latitude/Longitude coordinates from StructureCentroid.

5

Latitude/Longitude coordinates frommanually-placed Point.

7

Latitude/Longitude coordinates from Front DoorPoint.

8

Latitude/Longitude coordinates from DrivewayOffset Point.

9

Latitude/Longitude coordinates from StreetAccess Point.

A




Length(bytes)

Response Element

Latitude/Longitude coordinates from BaseParcel Point.

B

A description of the value returned in theLatLong.MatchCode field.

14LatLong.MatchLevel

ZIP + 2 centroidZIP+2

ZIP + 4 centroidZIP+4

Block group centroidBlock

City centroidCityCentroid

Intersection matchIntersection

Match using the LandmarkAuxiliary file

LandmarkAux

Input Latitude/Longitudecoordinates was used

LatLonInput

Exact address matchRooftop

State centroidStateCentroid

Census tract centroidTract

Address-level match using theGeoTAX Auxiliary Database

Auxiliary

ZIP Code centroidZIP

Output street address return code.2LatLong.StreetMatchCode

House number not found on streetH

Latitude/longitude not determined onauxiliary match

L

Street not found in ZIP CodeS

ZIP Code not found in street addressdatabase

Z

Street-level matching option not selectedN

The street was successfully matchednull

Street level match used to determine thelatitude/longitude

LatLong.StreetMatchLevel

Successful matchFullMatch

House number not found onstreet

HouseNotFound

Latitude/longitude not determinedon auxiliary match

LatLongNotFound

Street not found in ZIP CodeStreetNotFound

ZIP Code not found in streetaddress database

ZipNotFound




Length(bytes)

Response Element

Street-level matching option notselected

NotUsed

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

8Longitude

Longitude directional.2Longitude.Directional

EastE

WestW

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 51: Input Address Output Fields


Length(bytes)

Response Element

Input address line 1.101AddressLine1




Input address city.51City

Input address country.25Country

Input address firm name.101FirmName

Input address postal code10PostalCode

Input address state.51StateProvince

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 105. To include this data in theoutput, set GeoTAXOutputRecordType = W.

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



Table 52: Payroll System Tax Code Output Fields


Length(bytes)

Response Element

The number of payroll tax codes found for this address.2NumberPTCsFound

Indicates the level of match obtained for the address. Inorder from most specific match to least, the possiblematch codes are:

2 perPTC

PTCn.MatchCode

The address was matched to a specific PayrollDistrict 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 FIPScode.

F

The address was matched to a state's FIPScode. This is the least specific match.

S

A code that represents a taxing authority in a payrollapplication. This is a user-defined code. The specific

16 perPTC

PTCn.PayrollCode

codes are determined by the payroll application thatutilizes the data returned by AssignGeoTAXInfo.

A description of the purpose of this payroll code.41 perPTC

PTCn.PayrollDescription

A user-defined flag from the PTC database.7 perPTC

PTCn.PayrollFlag

The state abbreviation and county name.33StateCounty

Tax JurisdictionTax jurisdiction data contains information about the "place" for the location. A "place" is a geographicarea defined on the basis of population criteria that vary by state; or, an area recognized as significantbecause it is located in an incorporated municipality. Places are used to determine tax jurisdiction.

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

Table 53: Tax Jurisdiction Output Fields


Length(bytes)

Response Element

The value in this field varies depending on the optionyou specified in the TaxKey option:

10GeoTAXKey

If you specified T, GeoTAXKey contains the proprietarycodes used in Taxware tax compliance software. Youcan use this code in your Taxware application to find outthe tax rate for the jurisdiction.




Length(bytes)

Response Element

If you specified Y or V, GeoTAXKey contains theproprietary Vertex® jurisdiction code (comprised of atwo-digit Vertex® state code, three-digit FIPS countycode, and four-digit Vertex® city code). You can use thiscode in your Vertex® application to find out the tax ratefor the jurisdiction.

Return code denoting the level of match obtained againstthe Vertex or Taxware cross reference files.

2GeoTAXKey.MatchCode

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

E

Partial match using four fields: FIPS state code,FIPS county code, FIPS or GNIS place code,and ZIP Code.

P

Alternate match using two fields: ZIP Code,FIPS place name.

A

Record is default coded based on valid statecode.

N

No matching record found.null

A description of the value returned in theGeoTAXKey.MatchCode field.

12GeoTAXKey.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. Seedescription inGeoTAXKey.MatchCode.

DefaultCode

No matching record found.NoMatch

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

10GNISCode


Note:

Place class code. Place class codes are used todetermine the proper taxing jurisdictions

3Place.ClassCode

This field is always included in the outputregardless of whether or not you choose toinclude tax jurisdiction data in the output.

Note:




Length(bytes)

Response Element

An identifier for a specific place. A "place" is ageographic area defined on the basis of population

6Place.Code

criteria that vary by state. Or, an area recognized assignificant because it is located in an incorporatedmunicipality.


Note:

Indicates whether the address is located in anincorporated or unincorporated place. A "place" is a

8Place.IncorporatedFlag

geographic area defined on the basis of populationcriteria that vary by state. Or, an area recognized assignificant because it is located in an incorporatedmunicipality.


Note:

Incorporated place code.Inc

Unincorporated place code.Uninc

Incorporation status unknown.Unknown

Last annexed date, in the format MM/YYYY, representingthemonth and year of the most recent boundary changeor the most recent available boundary information.

8Place.LastAnnexedDate


Note:

Last updated date, in the format MM/YYYY, reflectingthe month and year when TomTom updated the

8Place.LastUpdatedDate

database to reflect attribute (name change, FIPS change,etc.) or boundary edits to the Place.


Note:

Last verified date, in the format MM/YYYY, representingthe month and year that TomTom verified municipalitychange information.

8Place.LastVerifiedDate


Note:

The name of the "place" where the address is located.A "place" is a geographic area defined on the basis of

41Place.Name

population criteria that vary by state. Or, an area




Length(bytes)

Response Element

recognized as significant because it is located in anincorporated municipality.


Note:

Returns the result for a comparison between thematched address point to the polygon defined by thePlace.txb file.

2Place.PointStatus


The buffer distance for Place.txb is internallyset to zero and cannot be modified.

Note:



I


B



Note:

Returns the distance between thematched address pointto the polygon defined by the Place.txb file.

10Place.DistanceToBorder


Note:

Provides the percentage overlap of the geocode to thePlace polygon layer. The returned percentage value

4Place.Confidence

describes the probability that the point falls in thespecified Place.


Note:

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 54: Output Fields for User-Defined Boundary Files


Length(bytes)

Response Element

The number of user-defined polygons found for theaddress.

3NumberUserBoundariesFound

A description of the polygon.51 perUser

Boundary

UserBoundaryn.BoundaryDescription

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

11 perUser

Boundary

UserBoundaryn.BoundaryID

Indicates where in the polygon the address resides inrelation to the edge of the area.

2 perUser

Boundary

UserBoundaryn.BufferRelation


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

P

buffer width. Buffer width is specified either by theoption or by the input field BufferWidth.

The address is inside the polygon but is close tothe edge. This indicates that the address is in the

I

buffer area specified either by the option or by theinput field BufferWidth.

The address is outside the polygon but is close tothe edge. This indicates that the address is in the

B


For more information, see Buffering on page 320.

Indicates the distance from the address to the border ofthe polygon. The distance is in the units specified by theoption.

10 perUser

Boundary

UserBoundaryn.DistanceToBorder

A supplemental ID as specified in the user-definedboundary file.

11 perUser

Boundary

UserBoundaryn.SupplementalBoundaryID

Provides the percentage overlap of the geocode to theUser-defined boundary polygon layer. The returned

4 perUser

Boundary

UserBoundaryn.BoundaryConfidence

percentage value describes the probability that the pointfalls in the User-defined boundary area.

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 105. To includeIPD data in the output, set GeoTAXOutputRecordType = I.

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



Table 55: Insurance Premium Tax District Output Fields


Length(bytes)

Response Element

The number of Insurance Premium Tax Districts foundfor the address

3NumberIPDsFound

Indicates where in the district the address resides inrelation to the edge of the district.

2 perIPD

IPDn.BoundaryBuffer.BufferRelation


The address is inside the district at a distance fromthe edge that is greater than the specified buffer

P

width. Buffer width is specified either by the optionor by the input field BufferWidth.

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

I


The address is outside the district but is close tothe edge. This indicates that the address is in the

B



Indicates the distance from the address to the border ofthe district.

10 perIPD

IPDn.BoundaryBuffer.DistanceToBorder

Provides the percentage overlap of the geocode to theIPD boundary polygon layer. The returned percentage

4 perIPD

IPDn.BoundaryConfidence

value describes the probability that the point falls in theIPD boundary area.

IPD ID.11 perIPD

IPDn.DistrictID

IPD name.61 perIPD

IPDn.DistrictName

IPD district type.7 perIPD

IPDn.DistrictType

IPD update date (MMYYYY).7 perIPD

IPDn.UpdateDate

IPD compiled date (MMYYYY).7 perIPD

IPDn.VersionDate

Tax code descriptions.21 perIPD

IPDn.Notes

For example: 01, 33, A, B

IPD change date.7 perIPD

IPDn.ChangeDate

MMDDYY - Identifies when district becomes active -State supplied

7 perIPD

IPDn.EffectiveDate




Length(bytes)

Response Element

For example: 010108

MMDDYY - Identifies when district becomes inactive -State supplied

7 perIPD

IPDn.ExpirationDate

For example: 063009

Format is dependent on associated flag21 perIPD

IPDn.FireRate

For example: .13, 15.00 or 3;7

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

IPDn.FireFlag

F - Flat Fee dollar amount

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


IPDn.CasualtyRate



IPDn.CasualtyFlag


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


IPDn.VehicleRate

Possible Values: .13, 15.00 or 3;7


IPDn.VehicleFlag




IPDn.MarineRate



IPDn.MarineFlag




IPDn.HealthRate



IPDn.HealthFlag




IPDn.LifeRate





Length(bytes)

Response Element


IPDn.LifeFlag




IPDn.OtherRate



IPDn.OtherFlag




IPDn.MinimumRate



IPDn.MinimumFlag



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 105. To include this data in the output, setGeoTAXOutputRecordType = R.


Table 56: Payroll Tax District Output Fields


Length(bytes)

Response Element

Number of PAYs returned.3NumberPAYsFound


2 perPAY

PAYn.BoundaryBuffer.BufferRelation



P



I




Length(bytes)

Response Element



B



Indicates the distance from the address to the border ofthe district. The distance is in the units specified by theoption.

10 perPAY

PAYn.BoundaryBuffer.DistanceToBorder

Provides the percentage overlap of the geocode to thePAY boundary polygon layer. The returned percentage

4 perPAY

PAYn.BoundaryConfidence

value describes the probability that the point falls in thePAY boundary area.

PAY district ID.11 perPAY

PAYn.DistrictID

PAY district name.61 perPAY

PAYn.DistrictName

PAY district type.7 perPAY

PAYn.DistrictType

PAY ID.11 perPAY

PAYn.ID

PAY municipality emergency municipal services tax.2 perPAY

PAYn.MunicipalEMSTax

The values for Pennsylvania are:

Levies the taxY

Does not levy the taxN

All other states are null.

PAY municipality income tax.2 perPAY

PAYn.MunicipalIncomeTax


ResidentR

Non-residentN

BothB

NoneX


PAY school district emergency municipal services tax.2 perPAY

PAYn.SchoolDistrictEMSTax

The Values for Pennsylvania are:

Levies the taxY





Length(bytes)

Response Element


PAY school district income tax.2 perPAY

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 105. To include this data in the output, setGeoTAXOutputRecordType = P.


Table 57: Property Tax District Output Fields


Length(bytes)

Response Element

Number of PTDs returned.3NumberPTDsFound


2 perPTD

PTDn.BoundaryBuffer.BufferRelation



P



I



B





Length(bytes)

Response Element



10 perPTD

PTDn.BoundaryBuffer.DistanceToBorder

Provides the percentage overlap of the geocode to thePTD boundary polygon layer. The returned percentage

4 perPTD

PTDn.BoundaryConfidence

value describes the probability that the point falls in thePTD boundary area.

PTD district ID.11 perPTD

PTDn.DistrictID

PTD district name.61 perPTD

PTDn.DistrictName

PTD district type. Only returned for Indiana.2 perPTD

PTDn.DistrictType

Reporting districtR

Billing districtB

PTD jurisdiction ID.11 perPTD

PTDn.JurisdictionID

PTD update date.7 perPTD

PTDn.UpdateDate

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 105. To include this datain the output, set GeoTAXOutputRecordType = S.


Table 58: Special Purpose Tax District Output Fields


Length(bytes)

Response Element

Number of SPDs returned.3NumberSPDsFound


2 perSPD

SPDn.BoundaryBuffer.BufferRelation



P





Length(bytes)

Response Element


I



B




10 perSPD

SPDn.BoundaryBuffer.DistanceToBorder

Provides the percentage overlap of the geocode to theSPD boundary polygon layer. The returned percentage

4 perSPD

SPDn.BoundaryConfidence

value describes the probability that the point falls in theSPD boundary area.

SPD compiled date.7 perSPD

SPDn.CompiledDate

3-digit district type code.4 perSPD

SPDn.DistrictCode

SPD name.61 perSPD

SPDn.DistrictName

SPD district number.6 perSPD

SPDn.DistrictNumber

SPD effective date.7 perSPD

SPDn.EffectiveDate

SPD update date.7 perSPD

SPDn.UpdateDate

SPD version date.7 perSPD

SPDn.VersionDate

Sales and Use Tax RatesThe following table lists the output fields that contain the sales and use tax rate data.

To include tax rate data in the output, set GeoTAXOutputRecordType = B.

To select the tax rate type, set TaxRate to one of the following:





Return the Medical sales and use tax rates.M



You must be a licensed user of the Pitney Bowes Software Sales and Use Tax Rate file to usethis feature.

Note:

Table 59: Sales and Use Tax Rate Output Fields


Length(bytes)

Response Element

Tax Rate return code denoting the level of matchobtained agained the Pitney Bowes Software Sales andUse Tax Rate file:

2TaxRate.RC

Exact match, using all 5 fieldsE

Partial match, using 4 fieldsP

Alternate match, using 3 fieldsA

Record is default-coded based on validstate code.

N

No matching PB Software Sales and UseTax Rate record found.

Blank

Municipality sales tax rate for the selected tax rate type.11Municipal.SalesTaxRate

County sales tax rate for the selected tax rate type.11County.SalesTaxRate

State sales tax rate for the selected tax rate type.11State.SalesTaxRate

Sales tax rate for up to 10 Special Purpose Districts(SPD).

11 perSPD

SPDn.SalesTaxRate

The sum of the individual Municipal, County, State andSPD sales tax rates.

11TaxRate.SalesTotal

Municipality use tax rate for the selected tax rate type.11Municipal.UseTaxRate

County use tax rate for the selected tax rate type.11County.UseTaxRate

State use tax rate for the selected tax rate type.11State.UseTaxRate

Use tax rate for up to 10 Special Purpose Districts (SPD).11 perSPD

SPDn.UseTaxRate

The sum of the individual Municipal, County, State andSPD use tax rates.

11TaxRate.UseTotal

Error ReportingThe following table defines the error reporting output fields.



Table 60: Error Output Fields


Length(bytes)

Response Element

This field contains a return code if the GeoTAX engineexperiences an abnormal termination.

3GTX.ErrorCode

This field contains the same set of codesreturned by the standalone GeoTAX software

Note:

and is intended for users who have migratedfrom GeoTAX to Spectrum™ TechnologyPlatform.

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

Matcher terminated normallyBlank

User Auxiliary file problemA

coubsub.txb file problemCE

Confidence engine problemCI

Boundary fileD

User-defined boundary file problemF

Address Matching engine problemG

Licensing problemL

State file problemS

GeoTAX Auxiliary file problemU

Combination of Street and state fileproblem

X

zip.gsb file problemZ

The second position is one of the following:

Fatal issue, program terminatingE

Expired databaseF

InformationalI

If the GeoTAX engine experiences an abnormaltermination, this field contains a text description of thereason. It is blank if GeoTAX terminated normally.

81GTX.ErrorDescription

This field contains the same set of descriptionsreturned by the standalone GeoTAX software

Note:


SI-"TS158 FILES NOT FOUND"SI-"TS158 FILES VINTAGE OR INCOMPLETE DBERROR"SI-"STATE FILES NOT FOUND"




Length(bytes)

Response Element

SE-"STATE AND TS158 FILES NOT FOUND"SE-"STATE NOT FOUND AND TS158 VINTAGEERROR"SI-"STATE FILES VINTAGE OR INCOMPLETE DBERROR"SE-"STATE VINTAGE ERROR AND TS158 NOTFOUND"SE-"STATE AND TS158 FILES VINTAGE ORINCOMPLETE DB ERROR"GI-"STREET FILES NOT FOUND"XI-"STREET AND TS158 FILES NOT FOUND"XI-"STREETNOTFOUNDANDTS158 FILESVINTAGEERROR"XI-"STREET AND STATE FILES NOT FOUND"XE-"STREET STATE AND TS158 FILES NOT FOUND"XE-"STREET AND STATE NOT FOUND AND TS158VINTAGE ERROR"XI-"STREET NOT FOUND AND STATE VINTAGEERROR"XE-"STREET AND TS158 NOT FOUND AND STATEVINTAGE ERROR"XE-"STREET NOT FOUND AND STATE AND TS158VINTAGE ERROR"GI-"STREET FILES VINTAGE OR INCOMPLETE DBERROR"XI-"STREET VINTAGE ERROR AND TS158 NOTFOUND"XI-"STREET AND TS158 FILES VINTAGE ORINCOMPLETE DB ERROR"XI-"STREET VINTAGE ERROR AND STATE NOTFOUND"XE-"STREET VINTAGE ERROR AND STATE ANDTS158 NOT FOUND"XE-"STREET AND TS158 VINTAGE ERROR ANDSTATE NOT FOUND"XI-"STREET AND STATE FILES VINTAGE ORINCOMPLETE DB ERROR"XE-"STREET AND STATE VINTAGE ERROR ANDTS158 NOT FOUND"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 BOUNDARYLICENSE"




Length(bytes)

Response Element

FI- "UNABLE TO OPEN USER BND FILE"FI- "USER BND FILE NOT FOUND"

This field contains warning codes returned by theGeoTAX engine. It is blank if no warnings were issued.

3GTX.WarnCode

A value of WN indicates a database will expire nextmonth.


Note:


A text description of any warnings returned by theGeoTAX engine.

81GTX.WarnDescription


Note:


Reports the success or failure of the match attempt.2Status

Successnull

Failure. Some examples of failures are yourlicense expired or you did not select any

F

output record types and fields forAssignGeoTAXInfo to return.

If AssignGeoTAXInfo could not process the address,this field will show the reason. Currently there is onepossible value for this field: Invalid Address.

12Status.Code

If AssignGeoTAXInfo could not process the address,this field will show a description of the failure. One of thefollowing:

64Status.Description

TS158 FILES NOT FOUNDTS158 FILES VINTAGEOR INCOMPLETEDBERRORSTATE FILES NOT FOUNDSTATE AND TS158 FILES NOT FOUNDSTATE NOT FOUND AND TS158 VINTAGE ERRORSTATE FILESVINTAGEOR INCOMPLETEDBERRORSTATE VINTAGE ERROR AND TS158 NOT FOUNDSTATEANDTS158 FILESVINTAGEOR INCOMPLETEDB ERRORSTREET FILES NOT FOUNDSTREET AND TS158 FILES NOT FOUNDSTREET NOT FOUND AND TS158 FILES VINTAGEERRORSTREET AND STATE FILES NOT FOUNDSTREET STATE AND TS158 FILES NOT FOUND




Length(bytes)

Response Element

STREET AND STATE NOT FOUND AND TS158VINTAGE ERRORSTREET NOT FOUND AND STATE VINTAGE ERRORSTREET AND TS158 NOT FOUND AND STATEVINTAGE ERRORSTREET NOT FOUND AND STATE AND TS158VINTAGE ERRORSTREET FILES VINTAGE OR INCOMPLETE DBERRORSTREET VINTAGE ERROR AND TS158 NOT FOUNDSTREET AND TS158 FILES VINTAGE ORINCOMPLETE DB ERRORSTREET VINTAGE ERROR AND STATE NOT FOUNDSTREET VINTAGE ERROR AND STATE AND TS158NOT FOUNDSTREET AND TS158 VINTAGE ERROR AND STATENOT FOUNDSTREET AND STATE FILES VINTAGE ORINCOMPLETE DB ERRORSTREET AND STATE VINTAGE ERROR AND TS158NOT 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

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

http://server:port/soap/CalculateDistance

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:cal="http://www.pb.com/spectrum/services/CalculateDistance"



xmlns:spec="http://spectrum.pb.com/"><soapenv:Header/><soapenv:Body>

<cal:CalculateDistanceRequest><spec:options>

<cal:LatLongFormat>Decimal</cal:LatLongFormat></spec:options><cal:input_port>

<cal:Coordinates><cal:FirstLatitude>41.857333</cal:FirstLatitude><cal:FirstLongitude>-88.325183</cal:FirstLongitude><cal:SecondLatitude>41.881833</cal:SecondLatitude><cal:SecondLongitude>-87.785587</cal:SecondLongitude>

</cal:Coordinates></cal:input_port>

</cal:CalculateDistanceRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:CalculateDistanceResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/CalculateDistance">


<ns3:Distance>27.799</ns3:Distance><ns3:user_fields/>


</ns3:CalculateDistanceResponse></soap:Body>

</soap:Envelope>

Request

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

Table 61: CalculateDistance Input Data


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

First latitude directional.FirstLatitude.Directional

NorthN

SouthS

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

First longitude directional.FirstLongitude.Directional

EastE

WestW

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

Second latitude directional.SecondLatitude.Directional




NorthN

SouthS

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

Second longitude directional.SecondLongitude.Directional

EastE

WestW


Table 62: Output Data and Format Options


Indicates the format of the input latitude/longitude. The options are: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: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 63: CalculateDistance Output Fields


Length(bytes)

Response Element

Distance between the two input coordinates in the unitsof measurement that you specified.

9Distance




Length(bytes)

Response Element

Reports the success or failure of the match attempt:2Status

Successnull

FailureF

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

2Status.Code

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

64Status.Description

ReverseGeoTAXInfoLookupReverseGeoTAXInfoLookup allows latitude/longitude coordinates to be supplied as input and identifiesthe tax districts that apply to the given coordinate. Specifically, ReverseGeoTAXInfoLookup can returnthe following information about a location:

• FIPS state codes and county codes• State and county names• MCD codes and names• Place codes and names• Boundary file districts• Cross-reference tax keys• The relationship of the input coordinates to user-defined polygons• Sales and use tax rates, if licensed for the Pitney Bowes Software Sales and Use Tax Rate File

ReverseGeoTAXInfoLookup optionally includes enhanced tax jurisdiction information for a location,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 byReverseGeoTAXInfoLookup:

• ReverseGeoTAXInfoLookup uses an additional database to determine payroll tax codes, resultingin more accurate payroll tax determination.

• Many payroll systems use specific codes to determine withholding amounts. Since you can customizethe payroll tax codes returned by ReverseGeoTAXInfoLookup, you can set up a process whereReverseGeoTAXInfo Lookup returns the exact payroll tax codes required by your payroll system,instead of returning 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 requires



the use of boundary files which require an additional license. Contact your Pitney Bowes Softwaresales representative for more information.

Using the optional Pitney Bowes Software Sales and Use Tax Rate file, ReverseGeoTAXInfoLookupincludes tax rate data for a location, including:

Tax rate type:

• General• Automotive• Medical• Construction

Sales and/or use tax rates for:

• State• County• Municipality• Up to 10 SPDs• Total Rate - the sum of the individual state, county, municipality and SPD rates.

Required input format

The required format for the input coordinates is as follows:

Table 64: Required Input Latitude/Longitude Format

FormatResponse Element

00.000000 or without the decimal point 00000000InputLatitude

000.000000 or without the decimal point 000000000, orInputLongitude

00.000000 or without the decimal point 00000000

ReverseGeoTAXInfoLookup is part of the Enterprise Tax Module.

Resource URL

http://server:port/soap/ReverseGeoTAXInfoLookup

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ass="http://www.pb.com/spectrum/services/ReverseGeoTAXInfoLookup"xmlns:spec="http://spectrum.pb.com/"> <soapenv:Header/>

<soapenv:Body><rev:ReverseGeoTAXInfoLookupRequest>

<rev:input_port><rev:Address>

<rev:InputLatitude>40.018998</rev:InputLatitude><rev:InputLongitude>-105.239580</rev:InputLongitude>

</rev:Address></rev:input_port>

</rev:ReverseGeoTAXInfoLookupRequest></soapenv:Body>

</soapenv:Envelope>





<ns3:ReverseGeoTAXInfoLookupResponsexmlns:ns3="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/ReverseGeoTAXInfoLookup"><ns3:output_port>

<ns3:Address><ns3:Confidence>100.0</ns3:Confidence><ns3:ProcessedBy>GTX</ns3:ProcessedBy><ns3:County.Code>013</ns3:County.Code><ns3:County.Name>Boulder</ns3:County.Name><ns3:StateCode>08</ns3:StateCode><ns3:State.Abbreviation>CO</ns3:State.Abbreviation>

<ns3:InputLatitude>40.018998</ns3:InputLatitude><ns3:InputLongitude>-105.239580</ns3:InputLongitude><ns3:GeoTAXKey.MatchCode></ns3:GeoTAXKey.MatchCode>

<ns3:GeoTAXKey.MatchLevel>NoMatch</ns3:GeoTAXKey.MatchLevel><ns3:GeoTAXKey/>

<ns3:Place.ClassCode>C1</ns3:Place.ClassCode><ns3:Place.Code>07850</ns3:Place.Code>

<ns3:Place.IncorporatedFlag>Inc</ns3:Place.IncorporatedFlag>

<ns3:Place.Name>Boulder</ns3:Place.Name>

<ns3:Place.LastAnnexedDate>10/2011</ns3:Place.LastAnnexedDate>

<ns3:Place.LastUpdatedDate>04/2013</ns3:Place.LastUpdatedDate>

<ns3:Place.LastVerifiedDate>01/2013</ns3:Place.LastVerifiedDate><ns3:Place.PointStatus>P</ns3:Place.PointStatus>

<ns3:Place.DistanceToBorder>000000387</ns3:Place.DistanceToBorder><ns3:GNISCode>002409883</ns3:GNISCode><ns3:GTX.ErrorCode/><ns3:GTX.ErrorDescription/><ns3:GTX.WarnCode/><ns3:GTX.WarnDescription/><ns3:user_fields/>


</ns3:ReverseGeoTAXInfoLookupResponse></soap:Body>

</soap:Envelope>

Request

Geocoding OptionsReverse geocoding information lookup is the process of taking an input latitude/longitude coordinateand returning jurisdictional tax information. The geocoding options define the database to use for matchingand specify the distance units and buffer distance to use when matching to a boundary file.

Table 65: ReverseGeoTAXInfoLookup Geocoding Options


Select the database resource to use in the reverse geocoding lookupprocess.

Database.GTX




Boundary matching: The following options can be set when matching to a boundary file such as SPD,IPD, PAY, Place and MCD, or user-defined.

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

Distances are measured in feet. (Default)Feet

Distances are measured in kilometers.Km

Distances are measured in meters.Meters

Distances are measured in miles.Miles

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

DefaultBufferWidth

Insurance Premium District (IPD) file, the Payroll Tax District (PAY) file,the Personal Property Tax District (PTD) file, Place and MCD files.

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

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

DefaultUserBufferWidth

option. For information on buffers, see Buffering on page 320. 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 Data OptionsData options control the data returned by ReverseGeoTAXInfoLookup. Table 66: ReverseGeoTAXInfoLookup Data Options on page 149 lists the output data options.

Table 66: ReverseGeoTAXInfo Lookup Data Options


Select one or more of the following to obtain the type of data you wantreturned. ReverseGeoTAXInfo Lookup groups the output fields into

GeoTAXOutputRecordType

record types. If you do not want all of the fields in a record type returned,do not select the check box, and list only those fields you want returnedin Extra Output Fields.

• C—Census• T—Tax Jurisdiction• U—User-defined boundary file• W—Payroll System Tax Codes• X—Auxiliary File• B—PB Software Sales and Use Tax Rate 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 151.

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

Note:

If you integrate ReverseGeoTAXInfo Lookup with third-party taxcompliance software from Vertex or Taxware, select which vendor you

TaxKey

use. This controls the value returned in the GeoTAXKey output field.One of the 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

Select the desired Sales tax rate type or None:TaxRate

Do not return sales tax rates. (default)N

Return the General sales tax rates.G

Return the Automotive sales tax rates.A

Return the Construction sales tax rates.C

Return the Medical sales tax rates.

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.

OutputFields

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

Output Format

Output format options control how ReverseGeoTAXInfo Lookup formats output data. The following tablelists the output format options.

Table 67: ReverseGeoTAXInfoLookup Output Format Options


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

OutputCasing





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

The output in upper case. For example: BOULDER.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 68: Auxiliary File Output Fields


Length(bytes)

Response Element

Data retrieved as a result of an auxiliary match from theuser-defined area of the auxiliary file.

301AuxiliaryData.AuxiliaryFile

Data retrieved as a result of a state match. Data contentand format vary depending on the state file used.

201AuxiliaryData.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 69: Census Data Output Fields


Length(bytes)

Response Element

Three-digit Federal Information Processing Standards(FIPS) county code extracted from theCensus.BlockCode.

4County.Code




Length(bytes)

Response Element


Note:

Name of the county.26County.Name


Note:

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

6MCD.Code

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

41MCD.Name

An address can be compared to a Minor Civil Division(MCD)/county subdivision file (Cousub.txt). This output

2MCD.PointStatus

field returns the result for a comparison between thematched geocode location to the polygon defined by theCousub.txb file.


The buffer distance for Cousub.txb is internallyset to zero and cannot be modified.

Note:



I


B


Returns the distance in feet between the matchedaddress point to the polygon defined by the Cousub.txbfile.

10MCD.DistanceToBorder

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

3StateCode


Note:

Input Latitude/LongitudeReverseGeoTAXInfoLookup always returns the input coordinates as part of the output. The inputlatitude/longitude fields are returned as input from the data. ReverseGeoTAXInfoLookup does not changethese input values.



Table 70: Input Latitude/Longitude Output Fields


Length(bytes)

Response Element

Input latitude.12InputLatitude

Input longitude.12InputLongitude

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 Reverse GeoTAX Info Lookup. To include this data in the output,set GeoTAXOutputRecordType = W.

ReverseGeoTAXInfoLookup returns up to six payroll tax codes per input location.Note:

Table 71: Payroll System Tax Code Output Fields


Length(bytes)

Response Element

The number of payroll system tax codes found for thislocation.

2NumberPTCsFound

Indicates the level of match obtained for the location. Inorder from most specific match to least, the possiblematch codes are:

2 perPTC

PTCn.MatchCode

The address was matched to a specific PayrollDistrict 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 FIPScode.

F

The address was matched to a state's FIPScode. This is the least specific match.

S

A code that represents a taxing authority in a payrollapplication. This is a user-defined code. The specific

16 perPTC

PTCn.PayrollCode

codes are determined by the payroll application thatutilizes the data returned by ReverseGeoTAXInfoLookup.

A description of the purpose of this payroll code.41 perPTC

PTCn.PayrollDescription

A user-defined flag from the PTC database.7 perPTC

PTCn.PayrollFlag

The state abbreviation and county name.33StateCounty



Tax JurisdictionTax jurisdiction data contains information about the "place" for the location. A "place" is a geographicarea defined on the basis of population criteria that vary by state; or, an area recognized as significantbecause it is located in an incorporated municipality. Places are used to determine tax jurisdiction.

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

Table 72: Tax Jurisdiction Output Fields


Length(bytes)

Response Element

The value in this field varies depending on the optionyou specified in the TaxKey option:

10GeoTAXKey

If you specified T, GeoTAXKey contains the proprietarycodes used in Taxware tax compliance software. Youcan use this code in your Taxware application to find outthe tax rate for the jurisdiction.

If you specified Y or V, GeoTAXKey contains theproprietary Vertex® jurisdiction code (comprised of atwo-digit Vertex® state code, three-digit FIPS countycode, and four-digit Vertex® city code). You can use thiscode in your Vertex® application to find out the tax ratefor the jurisdiction.

Return code denoting the level of match obtained againstthe Vertex or Taxware cross reference files.

2GeoTAXKey.MatchCode

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

E

Partial match using four fields: FIPS state code,FIPS county code, FIPS or GNIS place code,and ZIP Code.

P

Alternate match using two fields: ZIP Code,FIPS place name.

A

Record is default coded based on valid statecode.

N

No matching record found.null

A description of the value returned in theGeoTAXKey.MatchCode field.

12GeoTAXKey.MatchLevel

Exact match. See description inGeoTAXKey.MatchCode.

Exact

Partial match. See description inGeoTAXKey.MatchCode.

Partial

Alternate match. See description inGeoTAXKey.MatchCode.

Alternate




Length(bytes)

Response Element

Record is default coded. Seedescription inGeoTAXKey.MatchCode.

DefaultCode

No matching record found.NoMatch

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

10GNISCode


Note:

Place class code. Place class codes are used todetermine the proper taxing jurisdictions

3Place.ClassCode


Note:

An identifier for a specific place. A "place" is ageographic area defined on the basis of population

6Place.Code



Note:

Indicates whether the address is located in anincorporated or unincorporated place. A "place" is a

8Place.IncorporatedFlag

geographic area defined on the basis of populationcriteria that vary by state. Or, an area recognized assignificant because it is located in an incorporatedmunicipality.


Note:

Incorporated place code.Inc

Unincorporated place code.Uninc

Incorporation status unknown.Unknown

Last annexed date, in the format MM/YYYY, representingthemonth and year of the most recent boundary changeor the most recent available boundary information.

8Place.LastAnnexedDate


Note:




Length(bytes)

Response Element

Last updated date, in the format MM/YYYY, reflectingthe month and year when TomTom updated the

8Place.LastUpdatedDate

database to reflect attribute (name change, FIPS change,etc.) or boundary edits to the Place.


Note:

Last verified date, in the format MM/YYYY, representingthe month and year that TomTom verified municipalitychange information.

8Place.LastVerifiedDate


Note:

The name of the "place" for the location. A "place" is ageographic area defined on the basis of population

41Place.Name



Note:

Returns the result for a comparison between thematched geocode location to the polygon defined by thePlace.txb file.

2Place.PointStatus




I


B


Returns the distance in feet between the matchedaddress point to the polygon defined by the Place.txbfile.

10Place.DistanceToBorder

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.

ReverseGeoTAXInfoLookup can return up to 10 user-defined areas for each input location.Note:



Table 73: Output Fields for User-Defined Boundary Files


Length(bytes)

Response Element

The number of user-defined polygons found for theaddress.

3NumberUserBoundariesFound

A description of the polygon.51 perUser

Boundary

UserBoundaryn.BoundaryDescription

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

11 perUser

Boundary

UserBoundaryn.BoundaryID

Indicates where in the polygon the location resides inrelation to the edge of the area.

2 perUser

Boundary

UserBoundaryn.BufferRelation


The geocode is inside the polygon at a distancefrom the edge that is greater than the specified

P

buffer width. Buffer width is specified either by theoption or by the input field BufferWidth.

The geocode is inside the polygon but is close tothe edge. This indicates that the address is in the

I


The geocode is outside the polygon but is closeto the edge. This indicates that the address is in

B

the buffer area specified either by the option or bythe input field BufferWidth.


Indicates the distance in feet from the input location tothe border of the polygon.

10 perUser

Boundary

UserBoundaryn.DistanceToBorder

A supplemental ID as specified in the user-definedboundary file.

11 perUser

Boundary

UserBoundaryn.SupplementalBoundaryID

Insurance Premium Tax DistrictsThe following table lists the output fields that contain Insurance Premium Tax Districts (IPD) data. Formore information on insurance premium tax districts, seeReverseGeoTAXInfoLookup on page 146. Toinclude IPD data in the output, set GeoTAXOutputRecordType = I.

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



Table 74: Insurance Premium Tax District Output Fields


Length(bytes)

Response Element

The number of Insurance Premium Tax Districts foundfor the location.

3NumberIPDsFound

Indicates where in the district the location resides inrelation to the edge of the district.

2 perIPD

IPDn.BoundaryBuffer.BufferRelation


The location is inside the district at a distance fromthe edge that is greater than the specified buffer

P


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

I


The location is outside the district but is close tothe edge. This indicates that the location is in the

B



Indicates the distance in feet from the location to theborder of the district.

10 perIPD

IPDn.BoundaryBuffer.DistanceToBorder

IPD ID.11 perIPD

IPDn.DistrictID

IPD name.61 perIPD

IPDn.DistrictName

IPD district type.7 perIPD

IPDn.DistrictType

IPD update date (MMYYYY).7 perIPD

IPDn.UpdateDate

IPD compiled date (MMYYYY).7 perIPD

IPDn.VersionDate

Tax code descriptions.21 perIPD

IPDn.Notes

For example: 01, 33, A, B

IPD change date.7 perIPD

IPDn.ChangeDate

MMDDYY - Identifies when district becomes active -State supplied

7 perIPD

IPDn.EffectiveDate

For example: 010108

MMDDYY - Identifies when district becomes inactive -State supplied

7 perIPD

IPDn.ExpirationDate

For example: 063009




Length(bytes)

Response Element


IPDn.FireRate



IPDn.FireFlag


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


IPDn.CasualtyRate



IPDn.CasualtyFlag




IPDn.VehicleRate



IPDn.VehicleFlag




IPDn.MarineRate



IPDn.MarineFlag




IPDn.HealthRate



IPDn.HealthFlag




IPDn.LifeRate



IPDn.LifeFlag






Length(bytes)

Response Element


IPDn.OtherRate



IPDn.OtherFlag




IPDn.MinimumRate



IPDn.MinimumFlag



Payroll Tax DistrictsThe following table lists the output fields that contain Payroll Tax District (PAY) data. For more informationon payroll tax districts, see Reverse GeoTAX Info Lookup. To include this data in the output, setGeoTAXOutputRecordType = R.


Table 75: Payroll Tax District Output Fields


Length(bytes)

Response Element

Number of payroll tax districts found for the location.3NumberPAYsFound


2 perPAY

PAYn.BoundaryBuffer.BufferRelation



P



I



B





Length(bytes)

Response Element



10 perPAY

PAYn.BoundaryBuffer.DistanceToBorder

PAY district ID.11 perPAY

PAYn.DistrictID

PAY district name.61 perPAY

PAYn.DistrictName

PAY district type.7 perPAY

PAYn.DistrictType

PAY ID.11 perPAY

PAYn.ID

PAY municipality emergency municipal services tax.2 perPAY

PAYn.MunicipalEMSTax


Levies the taxY



PAY municipality income tax.2 perPAY

PAYn.MunicipalIncomeTax


ResidentR

Non-residentN

BothB

NoneX


PAY school district emergency municipal services tax.2 perPAY

PAYn.SchoolDistrictEMSTax

The Values for Pennsylvania are:

Levies the taxY



PAY school district income tax.2 perPAY

PAYn.SchoolDistrictIncomeTax


ResidentR

Non-residentN

BothB

NX

The values for Ohio are:

ResidentR




Length(bytes)

Response Element

NoneX


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


Table 76: Property Tax District Output Fields


Length(bytes)

Response Element

The number of Property Tax Districts found for thelocation.

3NumberPTDsFound


2 perPTD

PTDn.BoundaryBuffer.BufferRelation



P



I


The location is outside the district but is close tothe edge. This indicates that the address is in the

B




10 perPTD

PTDn.BoundaryBuffer.DistanceToBorder

PTD district ID.11 perPTD

PTDn.DistrictID

PTD district name.61 perPTD

PTDn.DistrictName

PTD district type. Only returned for Indiana.2 perPTD

PTDn.DistrictType

Reporting districtR




Length(bytes)

Response Element

Billing districtB

PTD jurisdiction ID.11 perPTD

PTDn.JurisdictionID

PTD update date.7 perPTD

PTDn.UpdateDate

Special Purpose Tax DistrictsThe following table lists the output fields that contain Special Purpose Tax Districts (SPD) data. For moreinformation on special purpose tax districts, see Reverse GeoTAX Info Lookup. To include this datain the output, set GeoTAXOutputRecordType = S.


Table 77: Special Purpose Tax District Output Fields


Length(bytes)

Response Element

Number of Special Purpose Tax Districts found for thelocation.

3NumberSPDsFound


2 perSPD

SPDn.BoundaryBuffer.BufferRelation



P



I



B



Indicates the distance in feet from the address to theborder of the district.

10 perSPD

SPDn.BoundaryBuffer.DistanceToBorder

SPD compiled date.7 perSPD

SPDn.CompiledDate

3-digit district type code.4 perSPD

SPDn.DistrictCode




Length(bytes)

Response Element

SPD name.61 perSPD

SPDn.DistrictName

SPD district number.6 perSPD

SPDn.DistrictNumber

SPD effective date.7 perSPD

SPDn.EffectiveDate

SPD update date.7 perSPD

SPDn.UpdateDate

SPD version date.7 perSPD

SPDn.VersionDate

Sales and Use Tax RatesThe following table lists the output fields that contain the sales and use tax rate data.

To include tax rate data in the output, set GeoTAXOutputRecordType = B.

To select the tax rate type, set TaxRate to one of the following:





Return the Medical sales and use tax rates.M

You must be a licensed user of the Pitney Bowes Software Sales and Use Tax Rate file to usethis feature.

Note:

Table 78: Sales and Use Tax Rate Output Fields


Length(bytes)

Response Element

Tax Rate return code denoting the level of matchobtained agained the Pitney Bowes Software Sales andUse Tax Rate file:

2TaxRate.RC

Exact match, using all 5 fieldsE

Partial match, using 4 fieldsP

Alternate match, using 3 fieldsA

Record is default-coded based on validstate code.

N

No matching PB Software Sales and UseTax Rate record found.

Blank




Length(bytes)

Response Element

Municipality sales tax rate for the selected tax rate type.11Municipal.SalesTaxRate

County sales tax rate for the selected tax rate type.11County.SalesTaxRate

State sales tax rate for the selected tax rate type.11State.SalesTaxRate

Sales tax rate for up to 10 Special Purpose Districts(SPD).

11 perSPD

SPDn.SalesTaxRate

The sum of the individual Municipal, County, State andSPD sales tax rates.

11TaxRate.SalesTotal

Municipality use tax rate for the selected tax rate type.11Municipal.UseTaxRate

County use tax rate for the selected tax rate type.11County.UseTaxRate

State use tax rate for the selected tax rate type.11State.UseTaxRate

Use tax rate for up to 10 Special Purpose Districts (SPD).11 perSPD

SPDn.UseTaxRate

The sum of the individual Municipal, County, State andSPD use tax rates.

11TaxRate.UseTotal

Error ReportingThe following table defines the error reporting output fields.

Table 79: Error Output Fields


Length(bytes)

Response Element

This field contains a return code if the GeoTAX engineexperiences an abnormal termination.

3GTX.ErrorCode


Note:


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

Matcher terminated normallyBlank

User Auxiliary file problemA

coubsub.txb file problemCE

Confidence engine problemCI

Boundary fileD

User-defined boundary file problemF




Length(bytes)

Response Element

Address Matching engine problemG

Licensing problemL

State file problemS

GeoTAX Auxiliary file problemU

Combination of Street and state fileproblem

X

zip.gsb file problemZ

The second position is one of the following:

Fatal issue, program terminatingE

Expired databaseF

InformationalI

If the GeoTAX engine experiences an abnormaltermination, this field contains a text description of the

81GTX.ErrorDescription

reason. It is blank if GeoTAX terminated normally. Themaximum length is 80.


Note:


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




Length(bytes)

Response Element

XE-"STREET NOT FOUND AND STATE AND TS158VINTAGE ERROR"GI-"STREET FILES VINTAGE OR INCOMPLETE DBERROR"XI-"STREET VINTAGE ERROR AND TS158 NOTFOUND"XI-"STREET AND TS158 FILES VINTAGE ORINCOMPLETE DB ERROR"XI-"STREET VINTAGE ERROR AND STATE NOTFOUND"XE-"STREET VINTAGE ERROR AND STATE ANDTS158 NOT FOUND"XE-"STREET AND TS158 VINTAGE ERROR ANDSTATE NOT FOUND"XI-"STREET AND STATE FILES VINTAGE ORINCOMPLETE DB ERROR"XE-"STREET AND STATE VINTAGE ERROR ANDTS158 NOT FOUND"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 BOUNDARYLICENSE"FI- "UNABLE TO OPEN USER BND FILE"FI- "USER BND FILE NOT FOUND"

This field contains warning codes returned by theGeoTAX engine. It is blank if no warnings were issued.

3GTX.WarnCode

A value of WN indicates a database will expire nextmonth.


Note:


A text description of any warnings returned by theGeoTAX engine.

81GTX.WarnDescription


Note:




Match and Location Codes

Match CodesThe following table lists the Match Codes. The Match Codes indicate the portions of the address thatmatched or did not match to the reference file. If a match could not be made, the Match Code beginswith E and the remaining digits indicate why the address did not match. The digits do not specificallyrefer to which address elements did not match, but rather why the address did not match. These fieldsare always included in the output from AssignGeoTAXInfo.

Table 80: Match Codes

DescriptionResponse Element

Same as Shh, but indicates match to an alias name record or analternate record.

Ahh

Street address did not match, but located a street segment based onthe input ZIP Code or city.

Chh

Matched to a small town with P.O. Box or General Delivery only.D00

Matched to an auxiliary file.Ghh

House number was changed.Hhh

Matched to USPS range records with unique ZIP Codes. CASS rulesprohibit altering an input ZIP if it matches a unique ZIP Code value.

Qhh

Matched to a ranged address.Rhh

Matched to USPS data. This is considered the best address match,because it matched directly against the USPS list of addresses. S is

Shh

returned for a small number of addresses when the matched addresshas a blank ZIP + 4.

Matched to a street segment record. Street segment records do notcontain ZIP Code information. If you enter a ZIP Code, the application

Thh

returns the ZIP Code you entered. If the input city and state has onlyone ZIP Code, the application returns that ZIP Code.

Matched to USPS data but cannot resolve the ZIP + 4 code without thefirm name or other information.

Uhh

Matched to an intersection of two streets, for example, “Clay St &Michigan Ave.” The first hex digit refers to the last line information, the

Xhhh

second hex digit refers to the first street in the intersection, and the thirdhex digit refers to the second street in the intersection.

The USPS does not allow intersections as a valid deliverableaddress

Note:

Same as Xhhh, but an alias name record was used for one or bothstreets.

Yhhh

No address given, but verified the provided ZIP Code.Z

Hex digit decoding

The following table contains the description of the hex digits for the Match Code values.



In second and third hex position means:In first hex position means:Code

No change in address line.No change in last line.0

Street type changed.ZIP Code changed.1

Pre-directional changed.City changed.2

Street type and pre-directional changed.City and ZIP Code changed.3

Post-directional changed.State changed.4

Street type and post-directional changed.State and ZIP Code changed.5

Pre-directional and post-directional changed.State and City changed.6

Street type, pre-directional, and postdirectionalchanged.

State, City, and ZIP Code changed.7

Street name changed.ZIP + 4 changed.8

Street name and street type changed.ZIP and ZIP + 4 changed.9

Street name and pre-directional changed.City and ZIP + 4 changed.A

Street name, street type, and pre-directionalchanged.

City, ZIP, and ZIP + 4 changed.B

Street name and post-directional changed.State and ZIP + 4 changed.C

Street name, street type, and post-directionalchanged.

State, ZIP, and ZIP + 4 changed.D

Street name, pre-directional, andpostdirectional changed.

State, City, and ZIP + 4 changed.E

Street name, street type, pre-directional, andpost-directional changed.

State, City, ZIP, and ZIP + 4 changed.F

Match Error CodesThe following table describes the values returned when an error occurs or the application cannot find amatch.

Table 81: Result Indicator Match Error Codes


Indicates an error, or nomatch. This can occur when the address entereddoes not exist in the database, or the address is badly formed and

Ennn, where nnn =

cannot be parsed correctly. The last three digits of an error code indicatewhich parts of an address the application could not match to thedatabase.

No match made.000

Low level error.001

Could not find data file.002

Incorrect GSD file signature or version ID.003

No city and state or ZIP Code found.010

Input ZIP not in the directory.011




Input city not in the directory.012

Input city not unique in the directory.013

Out of licensed area. Only occurs if using Group 1 licensing technology.014

Record count is depleted and license has expired.015

No matching streets found in directory.020

No matching cross streets for an intersection match.021

No matching segments.022

Unresolved match.023

No matching segments. (Same as 022.)024

Too many possible cross streets for intersection matching.025

No address found when attempting a multiline match.026

Invalid directional attempted.027

Record also matched EWS data, therefore the application denied thematch.

028

No matching range, single street segment found.029

No matching range, multiple street segments found.030

Location CodesThe Location Codes indicate the methodology used to compute the geocode andmay also provide someinformation about the quality of the geocode.

A Location Code of 'E' indicates a location code is not available. This usually occurs when you haverequested ZIP Code centroids of a high quality, and one is not available for that match. It can occurinfrequently when the does not have a 5-digit centroid location. An 'E' location code type may also bereturned when the input address cannot be standardized and there is no input ZIP Code. In this case,do not assume the ZIP Code returned with the nonstandardized address is the correct ZIP Code becausethe did not standardize the address; therefore, the does not return geocoding or Census Blockinformation.

Address Location CodesAddress location codes detail the known qualities about the geocode. An address location code has thefollowing characters.

Description**Characters

Always an 'A' indicating an address location.1st character

May be one of the following:2nd character

Interpolated address pointlocation.

C

GeoTAX Auxiliary fiel orLandmark Auxiliary file datalocation.

G



Description**Characters

Application infers the correctsegment from the candidaterecords.

I

Point-level data location.P

Location represents a rangedaddress.

R

Location on a street range.S

Location on an intersection of twostreets.

X

Digit indicating other qualities about the location.3rd and 4th characters

Table 82: Location Codes

Description**Response Element

ACn - Interpolated address point location

AIn - The correct segment is inferred from the candidate records at match time.

ASn - House range address geocode. This is the most accurate street interpolated geocode available.

where n =

Best location.0

Street side is unknown. The Census FIPS Block ID is assigned from the leftside; however, there is no assigned offset and the point is placed directly onthe street.

1

Indicates one or both of the following:2

• The address is interpolated onto a TIGER segment that did not initially containaddress ranges.

• The original segment name changed to match the USPS spelling. Thisspecifically refers to street type, predirectional, and postdirectional.

Only the second case is valid for non-TIGER data because segmentrange interpolation is only completed for TIGER data.

Note:

Both 1 and 2.3

Placeholder. Used when starting and ending points of segments contain thesame value and shape data is not available.

7

AGn - Indicates a geocode match to a GeoTAX Auxiliary or Landmark Auxiliary file,

where n =

The geocode represents the center of a parcel or building.0

The geocode is an interpolated address along a segment.1

The geocode is an interpolated address along a segment, and the side of thestreet cannot be determined from the data provided in the auxiliary file record.

2

The geocode is the midpoint of the street segment.3




APnn - Indicates a point-level geocode match representing the center of a parcel or building,

where nn =

Parcel centroid02

Indicates the center of an assessor’s parcel (tract or lot) polygon. When thecenter of an irregularly shaped parcel falls outside of its polygon, the centroidis manually repositioned to fall inside the polygon as closely as possible to theactual center.

Address point04

Represents field-collected GPS points with field-collected address data.

Structure centroid05

Indicates the center of a building footprint polygon, where the building receivesmail or has telephone service.

Usually a residential address consists of a single building. For houses withoutbuildings (detached garages, shed, barns, etc.), only the residences havea structure point. Condominiums and duplexes have multiple points for eachbuilding. Larger buildings, such as apartment complexes, typically receive mailat one address for each building and therefore individual apartments are notrepresented as discrete structure points.

Shopping malls, industrial complexes, and academic or medical centercampuses where one building accepts mail for the entire complex arerepresented as one point. When addresses are assigned to multiple buildingswithin one complex, each addressed structure is represented by a point.

If the center of a structure falls outside of its polygon, the center is manuallyrepositioned to fall inside the polygon.

Manually placed

Address points are manually placed to coincide with the midpoint of anassessor’s parcel’s street frontage at a distance from the center line.

07

Front door point

Represents the designated primary entrance to a building. If a building hasmultiple entrances and there is no designated primary entrance or the primary

08

entrance cannot readily be determined, the primary entrance is chosen basedon proximity to the main access street and availability of parking.

Driveway offset point

Represents a point located on the primary access road (most commonly adriveway) at a perpendicular distance of between 33- 98 feet (10-30 meters)from the main roadway.

09

Street access point

Represents the primary point of access from the street network. This addresspoint type is located where the driveway or other access road intersects themain roadway.

10

Base parcel point

The Centrus point data includes individual parcels that may be "stacked". Thesestacked parcels are individually identified by their unit or suite number, and

21




the is able to match to this unit number and return the correct APN. If an inputaddress is for a building or complex, without a unit number, the "base" parcelinformation returns and will not standardize to a unit number or return additionalinformation such as an APN.

The geocode is the midpoint of the street segment.3

ARn - Ranged address geocode,

where n =

The geocode is placed along a single street segment, midway between theinterpolated location of the first and second input house numbers in the range.

1

The geocode is placed along a single street segment, midway between theinterpolated location of the first and second input house numbers in the range,

2

and the side of the street is unknown. The Census FIPS Block ID is assignedfrom the left side; however, there is no assigned offset and the point is placeddirectly on the street.

The input range spans multiple USPS segments. The geocode is placed onthe endpoint of the segment which corresponds to the first input house number,closest to the end nearest the second input house number.

4

Placeholder. Used when the starting and ending points of the matched segmentcontain the same value and shape data is not available.

7

AXn - Intersection geocode,

where n =

Standard single-point intersection computed from the center lines of streetsegments.

3

Interpolated (divided-road) intersection geocode. Attempts to return a centroidfor the intersection.

8

Street centroid location codesStreet centroid location codes indicate the Census ID accuracy and the position of the geocode on thereturned street segment. A street centroid location code has the following characters.

DescriptionCharacter

Always 'C' indicating a location derived from a street segment.1st character

Census ID accuracy based on the search area used to obtain matching streetsegment.

2nd character

Location of geocode on the returned street segment.3rd character

The following table contains the values and descriptions for the street centroid location codes.

DescriptionCodeCharacter position

2nd Character

Block Group accuracy (most accurate). Based oninput ZIP Code.

B




Census Tract accuracy. Based on input ZIP Code.T

Unclassified Census accuracy. Normally accurate toat least the County level. Based on input ZIP Code.

C

Unknown Census accuracy. Based on Finance area.F

Unknown Census accuracy. Based on input City.P

3rd Character

Segment centroid.C

Segment low-range endpoint.L

Segment high-range endpoint.H

ZIP + 4 Location CodesZIP + 4

®centroid location codes indicate the quality of two location attributes: Census ID accuracy and

positional accuracy. A ZIP + 4 centroid location code has the following characters.


Always a 'Z' indicating a location derived from a ZIP centroid..1st character

Census ID accuracy.2nd character

Location type.3rd character

How the location and Census ID was defined. Provided for completeness, butmay not be useful for most applications.

4th character

The following table contains the values and descriptions for the ZIP + 4 location codes.


2nd Character

Block Group accuracy (most accurate).B

Census Tract accuracy.T

Unclassified Census accuracy. Normally accurate toat least the County level. Based on input ZIP Code.

C

3rd Character

Location of the Post Office that delivers mail to theaddress, a 5-digit ZIP Code centroid, or a location

5

based upon locale (city). See the 4th character for aprecise indication of locational accuracy.

Location based upon a ZIP + 2 centroid. Theselocations can represent a multiple block area in urbanlocations, or a slightly larger area in rural settings.

7

Location based upon a ZIP + 4 centroid. These arethe most accurate centroids and normally place the

9

location on the correct block face. For a small numberof records, the location may be themiddle of the entire




street on which the ZIP + 4 falls. See the 4th characterfor a precise indication of locational accuracy.

4th Character

Address matched to a single segment. Locationassigned in themiddle of thematched street segment,offset to the proper side of the street.

A

Address matched to a single segment, but the correctside of the street is unknown. Location assigned in

a

the middle of the matched street segment, offset tothe left side of the street, as address ranges increase.

Address matched to multiple segments, all segmentshave the same Block Group. Location assigned to

B

the middle of the matched street segment with themost house number ranges within this ZIP + 4.Location offset to the proper side of the street.

Same as methodology B except the correct side ofthe street is unknown. Location assigned in themiddle

b

of the matched street segment, offset to the left sideof the street, as address ranges increase.

Address matched to multiple segments, with allsegments having the same Census Tract. Returns

C

the Block Group representing the most householdsin this ZIP + 4. Location assigned to t he middle ofthe matched street segment with the most housenumber ranges within this ZIP + 4. Location offset tothe proper side of the street.

Same as methodology C except the correct side ofthe street is unknown. Location assigned in themiddle

c


Address matched to multiple segments, with allsegments having the same County. Returns the Block

D

Group representing the most households in this ZIP+ 4. Location assigned to the middle of the matchedstreet segment with the most house number rangeswithin this ZIP + 4. Location offset to the proper sideof the street.

Same as methodology D except the correct side ofthe street is unknown. Location assigned in themiddle

d


Street namematched; no house ranges available. Allmatched segments have the same Block Group.

E

Location placed on the segment closest to the centerof the matched segments. In most cases, this is onthe mid-point of the entire street.

Street namematched; no house ranges available. Allmatched segments have the same Census Tract.

F

Location placed on the segment closest to the center




of the matched segments. In most cases, this is onthe mid-point of the entire street.

Street name matched (no house ranges available).All matched segments have the same County.

G

Location placed on the segment closest to the centerof the matched segments. In most cases, this is onthe mid-point of the entire street.

Same as methodology G, but some segments are notin the same County. Used for less than .05% of thecentroids.

H

Created ZIP + 2 cluster centroid as defined bymethodologies A, a, B, and b. All centroids in this ZIP

I

+ 2 cluster have the same Block Group. Locationassigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined bymethodologies A, a, B, b, C, and c. All centroids in

J

this ZIP + 2 cluster have the same Census Tract.Location assigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined bymethodologies A, a, B, b, C, c, D, and d. Locationassigned to the ZIP + 2 centroid.

K

Created ZIP + 2 cluster centroid as defined bymethodology E. All centroids in this ZIP + 2 cluster

L

have the same Block Group. Location assigned tothe ZIP + 2 centroid.

Created ZIP+2 cluster centroid as defined bymethodology E and F. All centroids in this ZIP + 2

M

cluster have the same Census Tract. Locationassigned to the ZIP + 2 centroid.

Created ZIP + 2 cluster centroid as defined bymethodology E, F, G, and H. Location assigned tothe ZIP + 2 centroid.

N

ZIP Code is obsolete and not currently used by theUSPS. Historic location assigned.

O

Over 95% of addresses in this ZIP Code are in asingle Census Tract. Location assigned to the ZIPCode centroid.

V

Over 80% of addresses in this ZIP Code are in asingle Census Tract. Reasonable Census Tractaccuracy. Location assigned to the ZIP Code centroid.

W

Less than 80% of addresses in this ZIP Code are ina single Census Tract. Census ID is uncertain.Location assigned to the ZIP Code centroid.

X

Rural or sparsely populated area. Census code isuncertain. Location based upon the USGS places file.

Y

P.O. Box or General Delivery addresses. Censuscode is uncertain. Location based upon the PostOffice location that delivers the mail to that address.

Z



Geographic Centroid Location CodesGeographic centroid location codes indicate the quality of two location attributes: the geographic locationand area type.


Always 'G' indicating a location derived from a geographic centroid.1st character

Geographic area type.2nd character

The following table contains the values and descriptions for the geographic centroid location codes.


2nd Character

Municipality (city).M

County.C

State.S

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

http://server:port/soap/GeoConfidenceSurface

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


Length(bytes)

Response Element

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

13GeoConfidenceCode




Length(bytes)

Response Element

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.

1024StreetSegmentPoints

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

Note:

The latitude of the centroid of the geoconfidencepolygon.

11GeoConfidenceCentroidLatitude

The longitude of the centroid of the geoconfidencepolygon.

12GeoConfidenceCentroidLongitude

ResponseThe GeoConfidenceSurface output field contains the geoconfidence polygon.


A geoconfidence polygon that represents the returned geometry.Geometry


GeoConfidence Module

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, DataNormalization, 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

http://server:port/soap/GlobalSentry



Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:glob="http://www.pb.com/spectrum/services/GlobalSentry"><soapenv:Header/><soapenv:Body>

<glob:GlobalSentryRequest><glob:options/><glob:Input>

<glob:Row><glob:FirstName>Miguel</glob:FirstName><glob:LastName>Batista</glob:LastName>

</glob:Row></glob:Input>

</glob:GlobalSentryRequest></soapenv:Body>

</soapenv:Envelope>


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

Note:


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

<ns2:Output><ns2:Row>

<ns2:OverallRiskLevel>10</ns2:OverallRiskLevel>

<ns2:SanctionedCountryIdentified>No</ns2:SanctionedCountryIdentified><ns2:Status>S</ns2:Status><ns2:FirstName>Miguel</ns2:FirstName><ns2:LastName>Batista</ns2:LastName><ns2:PlaceOfBirth>San Sebastian (Guipuzcoa)

Spain</ns2:PlaceOfBirth><ns2:EntryID>315</ns2:EntryID>

<ns2:InputFilteredFirstName>Miguel</ns2:InputFilteredFirstName>

<ns2:InputFilteredLastName>Batista</ns2:InputFilteredLastName><ns2:InputFirstName>Miguel</ns2:InputFirstName><ns2:InputLastName>Batista</ns2:InputLastName><ns2:ListType>DFAT Consolidated List</ns2:ListType><ns2:MatchKey1>MGL</ns2:MatchKey1><ns2:MatchKey2>BTST</ns2:MatchKey2><ns2:NameMatchIdentified>Yes</ns2:NameMatchIdentified><ns2:NameProvided>Yes</ns2:NameProvided><ns2:AddressProvided>No</ns2:AddressProvided><ns2:IDNumberProvided>No</ns2:IDNumberProvided><ns2:AddressMatchIdentified>No</ns2:AddressMatchIdentified>

<ns2:IDNumberMatchIdentified>No</ns2:IDNumberMatchIdentified>

<ns2:CitizenshipScore>0</ns2:CitizenshipScore>

<ns2:CitizenshipMatchIdentified>No</ns2:CitizenshipMatchIdentified><ns2:DOBScore>0</ns2:DOBScore><ns2:DOBMatchIdentified>No</ns2:DOBMatchIdentified><ns2:NationalityScore>0</ns2:NationalityScore>

<ns2:NationalityMatchIdentified>No</ns2:NationalityMatchIdentified><ns2:PlaceOfBirthScore>0</ns2:PlaceOfBirthScore>

<ns2:PlaceOfBirthMatchIdentified>No</ns2:PlaceOfBirthMatchIdentified><ns2:CitizenshipProvided>No</ns2:CitizenshipProvided><ns2:DOBProvided>No</ns2:DOBProvided>



<ns2:NationalityProvided>No</ns2:NationalityProvided><ns2:PlaceOfBirthProvided>No</ns2:PlaceOfBirthProvided><ns2:WatchListFirstName>Miguel</ns2:WatchListFirstName>

<ns2:WatchListLastName>ALBISU IRIARTE</ns2:WatchListLastName>

<ns2:NameScore>100</ns2:NameScore><ns2:user_fields/>

</ns2:Row></ns2:Output>

</ns2:GlobalSentryResponse></soap:Body>

</soap:Envelope>

Request


Table 83: Global Sentry Input Fields


Full name.Name

Required if FirstName and LastName is not used.

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

Required if Name is not used.

Last name only.LastName

Required if Name is not used.

The first address line.AddressLine1

Recommended if provided.

The second address line.AddressLine2


The third address line.AddressLine3


Full country name.Country

Required if address lines are used.

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


Any place of birth data.PlaceOfBirth


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


Full country name.Citizenship


Full country name.Nationality





Response

Table 84: 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 184.

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 85: 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 the



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



http://support.pb.com/ekip/index?page=product_content&cat=SC_SPECTRUM_TECHNOLOGY_PLATFORM

Resource URL

http://server:port/soap/AutoCompleteLoqate

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:aut="http://www.pb.com/spectrum/services/AutoCompleteLoqate"xmlns:spec="http://spectrum.pb.com/">


<aut:AutoCompleteLoqateRequest><aut:input_port>

<aut:Address><aut:AddressLine1>1 Global</aut:AddressLine1>

</aut:Address></aut:input_port>

</aut:AutoCompleteLoqateRequest></soapenv:Body>

</soapenv:Envelope>


To make the example easier to read, empty response elements have been removed and onlythe first three address matches are shown.

Note:


<ns3:AutoCompleteLoqateResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/AutoCompleteLoqate">


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:HouseNumber>1</ns3:HouseNumber><ns3:AddressLine1>1 Global Vw</ns3:AddressLine1><ns3:FirmName>Map Info</ns3:FirmName><ns3:City>Troy</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>12180-8399</ns3:PostalCode><ns3:PostalCode.AddOn>8399</ns3:PostalCode.AddOn><ns3:Country>United States</ns3:Country>


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:HouseNumber>1</ns3:HouseNumber><ns3:AddressLine1>1 Global Pl</ns3:AddressLine1><ns3:City>Glendale</ns3:City><ns3:StateProvince>AZ</ns3:StateProvince><ns3:PostalCode>85306-3216</ns3:PostalCode><ns3:PostalCode.AddOn>3216</ns3:PostalCode.AddOn><ns3:Country>United States</ns3:Country>


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:HouseNumber>1</ns3:HouseNumber><ns3:AddressLine1>1 Global Dr</ns3:AddressLine1><ns3:City>Olive Hill</ns3:City><ns3:StateProvince>KY</ns3:StateProvince><ns3:PostalCode>41164-6739</ns3:PostalCode><ns3:PostalCode.AddOn>6739</ns3:PostalCode.AddOn><ns3:Country>United States</ns3:Country>


</ns3:AutoCompleteLoqateResponse></soap:Body>

</soap:Envelope>



Request

Parameters for Input DataThe following table lists the input for AutoCompleteLoqate.

Table 86: Input Format





The fourth address line.AddressLine4

The city name.City

The country code or name, in any of the following formats: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 322.

The company or firm name.FirmName

The postal code for the address.PostalCode

The state or province.StateProvince


Table 87: 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.

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

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 format to use for the country name returned in theCountryoutput field. For example, if you select English, the country name"Deutschland" would be returned as "Germany".

OutputCountryFormat

Use English country names (default).E

Use two-letter ISO abbreviation for the countries instead ofcountry names.

I

Use Universal Postal Union abbreviation for the countriesinstead of country names.

U




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.

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

Reduces input time by up to 80% for 240 countries by using data in theform of an index file. When you conduct a search, the Loqate Engine

isPowersearchEnable

will first look for the corresponding index. If present, the method willattempt to instantly return a list of candidate addresses. If the index isnot present, or if the index does not return any results, the original searchprocess will be triggered.

Powersearch can be performed when there are two and onlytwo fields in the input file: the Country field and any one of the

Note:

AddressLine fields. If you select this option and your input filecontains additional fields, the original search process willautomatically be triggered.

To conduct its search, Auto Complete indexes use up to the first 10characters for searches within the United States and up to the first 15characters for searches within all other eligible countries. Spaces andpunctuation are not factored into this count.

Powersearch cannot be used for the following countries: Botswana,Ethiopia, India, Kazakhstan, Malaysia, Mongolia, Saint Kitts and Nevis,and San Marino.

You must have a valid license for Powersearch processing. Ifyou select this option but are not licensed for Powersearch, orif your license has expired, you will receive an error.

Note:

The maximum number of addresses that AutoCompleteLoqate shouldreturn. The default is 10.

MaximumResults

Specifies how you want Spectrum Technology Platform to respond whena data license error occurs.

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 88: AutoCompleteLoqate Output






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

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

Reports the success or failure of the match attempt.Status

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

http://server:port/soap/GetCandidateAddresses

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetCandidateAddresses"xmlns:spec="http://spectrum.pb.com/">




<get:GetCandidateAddressesRequest><get:input_port>

<get:Address><get:AddressLine1>P.O. Box 1</get:AddressLine1><get:City>New York</get:City><get:StateProvince>NY</get:StateProvince>


</get:GetCandidateAddressesRequest></soapenv:Body>

</soapenv:Envelope>



Note:


<ns3:GetCandidateAddressesResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/GetCandidateAddresses">


<ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:RecordType>PostOfficeBox</ns3:RecordType><ns3:MatchLevel>A</ns3:MatchLevel><ns3:AddressLine1>PO Box 1</ns3:AddressLine1><ns3:HouseNumberLow>1</ns3:HouseNumberLow><ns3:HouseNumberHigh>60</ns3:HouseNumberHigh><ns3:HouseNumberParity>B</ns3:HouseNumberParity><ns3:City>New York</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>10002</ns3:PostalCode><ns3:PostalCode.AddOn>0001</ns3:PostalCode.AddOn><ns3:Country>USA</ns3:Country>


<ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:RecordType>PostOfficeBox</ns3:RecordType><ns3:MatchLevel>A</ns3:MatchLevel><ns3:AddressLine1>PO Box 1</ns3:AddressLine1><ns3:HouseNumberLow>1</ns3:HouseNumberLow><ns3:HouseNumberHigh>9</ns3:HouseNumberHigh><ns3:HouseNumberParity>B</ns3:HouseNumberParity><ns3:City>New York</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>10008</ns3:PostalCode><ns3:PostalCode.AddOn>0001</ns3:PostalCode.AddOn><ns3:Country>USA</ns3:Country>


</ns3:GetCandidateAddressesResponse></soap:Body>

</soap:Envelope>

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

Applies only to U.K. addresses. May contain street name, unit number,building number, and so on.

The city name.City


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:

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.

USUrbanName




Table 90: GetCandidateAddresses Options


Specifies whether or not to process U.S. addresses. If youenable U.S. address processing GetCandidateAddresses will

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

Database.US

US Database Resources panel in theManagement Consoleare available.

Specifies whether or not to process Canadian addresses. Ifyou enable Canadian address processing

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

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

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

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.

MaximumResults

For U.S. addresses, specifies whether or not to return theUSPS®-approved abbreviation for the city, if there is one. The

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

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

(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).

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).FirmMatchingStrictness

The input firm name must match the databaseexactly.

E



The matching algorithm is "loose."L

The strictness of the directional match.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

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.

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 91: 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

http://server:port/soap/GetCandidateAddressesLoqate

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetCandidateAddressesLoqate"



xmlns:spec="http://spectrum.pb.com/"><soapenv:Header/><soapenv:Body>

<get:GetCandidateAddressesLoqateRequest><get:input_port>

<get:Address><get:AddressLine1>PO Box 1</get:AddressLine1><get:City>New York</get:City><get:StateProvince>NY</get:StateProvince>


</get:GetCandidateAddressesLoqateRequest></soapenv:Body>

</soapenv:Envelope>



Note:


<ns3:GetCandidateAddressesLoqateResponsexmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/GetCandidateAddressesLoqate">


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:AddressLine1>PO Box 101</ns3:AddressLine1><ns3:City>New York Mls</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>13417-0101</ns3:PostalCode><ns3:PostalCode.AddOn>0101</ns3:PostalCode.AddOn><ns3:Country>USA</ns3:Country>


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:AddressLine1>PO Box 102</ns3:AddressLine1><ns3:City>New York Mls</ns3:City><ns3:StateProvince>NY</ns3:StateProvince><ns3:PostalCode>13417-0102</ns3:PostalCode><ns3:PostalCode.AddOn>0102</ns3:PostalCode.AddOn><ns3:Country>USA</ns3:Country>


</ns3:GetCandidateAddressesLoqateResponse></soap:Body>

</soap:Envelope>

Request

Parameters for Input DataThe following table lists the input for GetCandidateAddressesLoqate.










The city name.City




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:

PostalCode


For U.S. addresses only, you may put the state in the City field insteadof the StateProvince field.


Table 93: GetCandidateAddressesLoqate Options


Specifies the database to be used for address processing. Onlydatabases that have been defined in the Management Console areavailable.

Database.Loqate


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

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

Specifies the format to use for the country name returned in theCountryoutput field. For example, if you select English, the country name"Deutschland" would be returned as "Germany".

OutputCountryFormat


Use two-letter ISO abbreviation for the countries instead ofcountry names.

I

Use Universal Postal Union abbreviation for the countriesinstead of country names.

U


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


The maximum number of candidate addresses thatGetCandidateAddressesLoqate should return. The default is 10. Themaximum is 99.

MaximumResults

ResponseGetCandidateAddressesLoqate returns the following output.

Table 94: 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

http://server:port/soap/GetCityStateProvince

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetCityStateProvince"xmlns:spec="http://spectrum.pb.com/">


<get:GetCityStateProvinceRequest><get:input_port>

<get:Input><get:PostalCode>60510</get:PostalCode>

</get:Input></get:input_port>

</get:GetCityStateProvinceRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:GetCityStateProvinceResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/GetCityStateProvince">


<ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:PostalCode>60510</ns3:PostalCode><ns3:City>BATAVIA</ns3:City><ns3:City.Type>P</ns3:City.Type><ns3:StateProvince>IL</ns3:StateProvince><ns3:Country>USA</ns3:Country><ns3:user_fields/>


</ns3:GetCityStateProvinceResponse></soap:Body>

</soap:Envelope>



Request

Parameters for Input DataThe following table shows the input fields.

Table 95: GetCityStateProvince Input


A U.S. ZIP Code™ or Canadian postal code in one of the followingformats:

PostalCode

99999

99999-9999

A9A9A9

A9A 9A9


Table 96: 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

PerformUSProcessing

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


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.

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.



DescriptionParameter Name

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

Database.Canada

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.

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.

MaximumResults

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 97: 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

http://server:port/soap/GetCityStateProvinceLoqate

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetCityStateProvinceLoqate"xmlns:spec="http://spectrum.pb.com/">


<get:GetCityStateProvinceLoqateRequest><get:input_port>

<get:Input><get:PostalCode>60510</get:PostalCode><get:Country>USA</get:Country>


</get:GetCityStateProvinceLoqateRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:GetCityStateProvinceLoqateResponsexmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/GetCityStateProvinceLoqate">


<ns3:ProcessedBy>LOQATE</ns3:ProcessedBy>



<ns3:PostalCode>60510</ns3:PostalCode><ns3:City>Batavia</ns3:City><ns3:StateProvince>IL</ns3:StateProvince><ns3:Country>United States</ns3:Country><ns3:Status/><ns3:Status.Code/><ns3:Status.Description/><ns3:user_fields/>


</ns3:GetCityStateProvinceLoqateResponse></soap:Body>

</soap:Envelope>

Request

Parameters for Input DataThe following table shows the input fields.

Table 98: GetCityStateProvinceLoqate Input





The postal code for the address.PostalCode

Options

Table 99: 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.


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.



Description / Valid 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 100: 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

http://server:port/soap/GetPostalCodes

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:get="http://www.pb.com/spectrum/services/GetPostalCodes"xmlns:spec="http://spectrum.pb.com/">


<get:GetPostalCodesRequest><get:input_port>

<get:Input><get:City>Holland</get:City><get:StateProvince>MI</get:StateProvince>


</get:GetPostalCodesRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:GetPostalCodesResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/GetPostalCodes">


<ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:PostalCode>49422</ns3:PostalCode><ns3:City.Type></ns3:City.Type><ns3:Status/><ns3:Status.Code/><ns3:Status.Description/><ns3:user_fields/>

</ns3:Result><ns3:Result>


</ns3:Result><ns3:Result>



</ns3:GetPostalCodesResponse></soap:Body>

</soap:Envelope>



Request

Parameters for Input DataGetPostalCodes takes a city, state/province, and country as input.

Table 101: GetPostalCodes Input


The city whose postal codes you want to look up.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.

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.

Country


Table 102: 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.

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

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.

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 103: 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

http://server:port/soap/ValidateAddress

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:val="http://www.pb.com/spectrum/services/ValidateAddress"><soapenv:Header/><soapenv:Body>

<val:ValidateAddressRequest><val:input_port>

<val:Address><val:AddressLine1>1 N. State St.</val:AddressLine1><val:City>Chicago</val:City><val:StateProvince>IL</val:StateProvince>


</val:ValidateAddressRequest></soapenv:Body>

</soapenv:Envelope>



<ns3:ValidateAddressResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/ValidateAddress">


<ns3:Confidence>87</ns3:Confidence><ns3:RecordType>HighRise</ns3:RecordType><ns3:RecordType.Default>Y</ns3:RecordType.Default><ns3:CountryLevel>A</ns3:CountryLevel><ns3:ProcessedBy>USA</ns3:ProcessedBy><ns3:MatchScore>0</ns3:MatchScore><ns3:AddressLine1>1 N State St</ns3:AddressLine1><ns3:City>Chicago</ns3:City><ns3:StateProvince>IL</ns3:StateProvince><ns3:PostalCode>60602-3302</ns3:PostalCode><ns3:PostalCode.Base>60602</ns3:PostalCode.Base><ns3:PostalCode.AddOn>3302</ns3:PostalCode.AddOn><ns3:Country>United States Of America</ns3:Country><ns3:AdditionalInputData/><ns3:user_fields/>


</ns3:ValidateAddressResponse></soap:Body>

</soap:Envelope>

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 215 for important information abouthow address line data is processed for U.S. addresses.





The first address line.String[50]

AddressLine1

The second address line.String[50]

AddressLine2

The third address line.String[50]

AddressLine3

Does not apply to Canadian addresses.

The fourth address line.String[50]

AddressLine4

Does not apply to Canadian addresses.

The fifth address line.String[50]

AddressLine5

Applies only to U.K. addresses. May contain street name, unitnumber, building number, and so on.


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]

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]

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]

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




The company or firm name.String[50]

FirmName

The U.S. address urbanization name. This is used primarilyfor Puerto Rico addresses.

String[50]

USUrbanName

If this mailpiece uses a generic barcode, specify yourUSPS®-assigned customer ID in this field. The

String [9]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 option CanFrenchFormat=T isused.

StringCanLanguage

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

Table 105: Output Data Options


Type of output record. For more than one, provide a list.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 242. If




ValidateAddress 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 243. 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 245.

Postal data. Output addresses contain additional datafor each validated address. For more information, seePostal Data Output on page 246.

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

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

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

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

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 the




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

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 areOutputPreferredAlias and OutputAbbreviatedAlias.

If OutputAbbreviatedAlias is enabled, the abbreviatedalias will always appear in the output even if you haveOutputStreetNameAlias disabled.

Note:

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

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: LanhamStateProvince: 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 OutputCountryFormat does not affect the country name




in the address block, it only affects the name returned in theCountry 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, OutputRecordType must contain P. For more information onOutputRecordType, see Output Data Options on page 215.

Table 106: 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, OutputRecordType must contain P. For more information onOutputRecordType, see Output Data Options on page 215.

Table 107: 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, OutputRecordType must contain P. For more information onOutputRecordType, see Output Data Options on page 215.



http://www.census.gov

Table 108: FIPS County Number Output

Description

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, OutputRecordType must contain P. For more information onOutputRecordType, see Output Data Options on page 215.

Table 109: 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, OutputRecordType must contain P. For moreinformation on OutputRecordType, see Output Data Options on page 215.

Table 110: Delivery Point Barcode Output

Description

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

For example, if you have the following:

• PostalCode.Base = 49423• PostalCode.Addon = 4506• PostalBarcode = 29• USBCCheckDigit = 2

The assembled barcode would be:



http://www.usps.com

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

Table 111: 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).

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.

KeepMultimatch

Yes, return multiple matches (default).Y

No, do not return multiple matches.N

For more information, see Returning Multiple Matches onpage 225.

Specifies where to place secondary address information forU.S. addresses. Secondary address information refers to

StandardAddressFormat

apartment numbers, suite numbers, and similar designators.For example, in this address the secondary address




information 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 224.

Specifies how to format city names that have short city nameor non-mailing city name alternatives. Applies to U.S. andCanadian addresses.

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,

OutputCountryFormat

the country name "Deutschland" would be returned as"Germany".


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

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

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

About Dual Address Logic

For U.S. addresses only, the DualAddressLogic option controls whether ValidateAddress should returna street match or a PO Box/Rural Route/Highway Contract match when the address contains both streetand PO Box/Rural Route/Highway Contract information in the same address line.

The DualAddressLogic option has no effect if the street information is in a different address lineinput 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 DualAddressLogic is set to either N or P, ValidateAddress returns the following:

AddressLine1: PO Box 1City: KempStateProvince: TXPostalCode: 75143-0001

• If DualAddressLogic is set to S, ValidateAddress returns the following:

AddressLine1: 401 N Main St Apt 1City: Kemp



StateProvince: 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 StandardAddressFormat=D. For more information on this option,see Default Options on page 221. 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 StandardAddressFormat=D then the address informationnot used to standardize the address is returned in the AdditionalInputData field. For more informationon this option, see Default Options on page 221. For example, if you choose to return a street matchfor 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 StandardAddressFormat option toD. 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 112: Multiple Match Option


Indicates whether or not to return multiple address for those inputaddresses that have more than one possible match.

KeepMultimatch



A number between 1 and 10 that indicates the maximum number ofaddresses to return.

MaximumResults


The difference between Keepmultimatch=N andKeepMultimatch=Y/MaximumResults=1 is that a multiple match

Note:

will return a failure if KeepMultimatch=N, whereas a multiplematch will return one record if KeepMultimatch=Y andMaximumResults=1.




To identify which output addresses are candidate addresses, you mustspecify a value of Y for 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 215. 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 251.

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

PerformUSProcessing

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.

Database.US

Enhanced Line of Travel (eLOT) processing assigns a Line of Travelsequence code to your addresses. Note that ValidateAddress does not

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

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.

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

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

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

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

The USPS® Locatable Address Conversion System (LACS) allows youto correct addresses that have changed as a result of a rural route

PerformLACSLink

address converting to street-style address, a PO Box renumbering, ora street-style address changing. When enabled, LACSLink processingis 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 262

The EarlyWarning System (EWS) uses the USPS® EWSFile to validateaddresses that are not in the ZIP + 4® database.

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

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.

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 primaryaddress elements in AddressLine1, the secondary elements inAddressLine2, Urbanization in AddressLine3, and firm in AddressLine4,if possible. For example,





Specifies whether to perform SuiteLink™ processing.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

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

Specifies whether to use a street's preferred alias in the output.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 OutputStreetNameAlias andOutputAbbreviatedAlias.

In most cases, if you select both OutputPreferredAlias andOutputAbbreviatedAlias, and ValidateAddress finds both a preferredand an abbreviated alias in the postal database, the abbreviated aliaswill be used in the output. The exception to this rule is if the input streetname is a preferred alias. In this case, the preferred alias will be usedin 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.

OutputAbbreviatedAlias

This is one of three options that control how ValidateAddress handlesstreet name aliases. The other two are OutputStreetNameAlias andOutputPreferredAlias.

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

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 262

Determines if the location has been unoccupied for at least 90 days.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 262

Returns VeriMove detail data in output.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:

StreetMatchingStrictness

The input street name must match the database exactly.E





FirmMatchingStrictness

The input firm name must match the database exactly.E





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.

DPVSuccessfulStatusCondition

Full matchF

Partial matchP

Always. Default.A


Treat Commercial Mail Receiving Agency (CMRA)matches as failures?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.

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 StandardAddressFormat to either C or D.

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

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

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

CanEnglishApartmentLabel

apartment label in the input address. This settingis ignored if you specifyCanStandardAddressFormat=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

CanFrenchApartmentLabel

apartment label in the input address. This settingis ignored if you specifyCanStandardAddressFormat=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

Changes the civic and/or suite information to matchthe Large Volume Receiver (LVR) or single-single

ForceCorrectionLVR

record (used when there is only one record for thatpostal code/street name/street type).

Do not change the civic and/or suiteinformation to match the LVR or single-single

N

record. The LVR record will be marked as avalid but non-correctable record (VN). Thesingle-single record will be corrected, ifpossible, or processed as a non-correctablerecord..

Change the civic and/or suite information tomatch the LVR or single-single record.

Y

If you check this box, the Statementof Address Accuracy will not be

Note:

printed because this is not aSERP-recognized setting.




In cases where the house number and postal codeare both valid but in conflict, you can force the

CanPreferHouseNum

postal code to be corrected based on the housenumber by specifying CanPreferHouseNum=Y. Ifyou do not select this option the house number ischanged to match 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

CanOutputCityAlias

is disabled when you specifyCanOutputCityFormat=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.

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

Enable SERP options.Y

Do not enable SERP options. Default.N

Specifies where to place secondary addressinformation in the output address. Secondary

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,

CanOutputCityFormat

Long: BUFFALO HEAD PRAIRIEMedium: BUFFALO-HEAD-PRShort: BUFFALO-HD-PR

Use the default option specified by theOutputShortCityName option. Default. If

D

you specify OutputShortCityName=V, thecity is formatted as if you select for thisoption (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:

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

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

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 CanDualAddressLogic is set to S,ValidateAddress returns the following:

AddressLine1: 36 GRANT RDAddressLine2: RR 3City: ANTIGONISHStateProvince: NSPostalCode: B2G 2L1

• If 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 215.

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 OutputRecordType=P. For more information on OutputRecordType,see Output Data Options on page 215.

SERP return codes are provided in the following output field.

Table 113: 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

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 licensedfor 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

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

InternationalCityStreetSearching

performance. If you are willing to trade matchingaccuracy for faster performance, use theInternationalCityStreetSearching option to increaseprocessing speed. When you do this, someaccuracy 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,

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 increased




possibility 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 OutputRecordType=A. Standard address fields are always returned for addresses that couldnot be validated. For non-validated addresses, the standard address output fields contain the addressas it appeared in the input ("pass through" data). If you want ValidateAddress to standardize addressaccording to postal authority standards when validation fails, specify OutputFormattedOnFail=Y in yourrequest.

Table 114: Standard Address Output


Input data not used by ValidateAddress. For more information, seeAbout AdditionalInputData on page 266.

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 OutputRecordType=E. If youwant ValidateAddress to return formatted data in the Parsed Address format when validation fails (thatis, a normalized address), specify OutputFormattedOnFail=Y.

If you want ValidateAddress to always return parsed input data regardless of whether or notvalidation is successful, specify OutputRecordType=I. For more information, see Parsed Inputon page 245.

Note:

Table 115: Parsed Address Output


Input data not used by ValidateAddress. For moreinformation, see About AdditionalInputData onpage 266.

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


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 OutputRecordType=I.

Table 116: 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


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 OutputRecordType contains P then the following fields are returned in the output.

Table 117: Postal Data Output


Validation/correction return code (Canadian addresses only). For moreinformation, see Obtaining SERP Return Codes on page 239.

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

The two-digit delivery point portion of the delivery point barcode (U.S.addresses only) For more information, see Creating Delivery PointBarcodes on page 220.

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



http://www.laposte.fr/

http://www.insee.fr


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

USBCCheckDigit

Carrier route code (U.S. addresses only). For more information, seeObtaining Carrier Route Codes on page 220.

USCarrierRouteCode

Congressional district (U.S. addresses only). For more information, seeObtaining Congressional Districts on page 219.

USCongressionalDistrict

County name (U.S. addresses only). For more information, seeObtainingCounty Names on page 219.

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

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 248• Field-Level Result Indicators on page 251

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 118: 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

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 of

Confidence

confidence that the match results are correct. For multiple matches, theconfidence level is 0. For details about how this number is calculated, seeIntroduction to the Validate Address Confidence Algorithm on page 342.

If no match was found, which address component could not be validated:CouldNotValidate

• ApartmentNumber• HouseNumber• StreetName• PostalCode• City• Directional• StreetSuffix• Firm• POBoxNumber• RuralRoute

More than one component may be returned, in a comma-separatedlist.

Note:

The category of address matching available. This is always "A" for U.S. andCanadian addresses. One of the following:

CountryLevel

The address is in a country for which there is highly detailed postaldata available. Addresses in this match level can have the following

A

address elements validated and corrected, and added if missing fromthe input:

• Postal code• City name• State/county name• Street address elements




• Country name.

The address is in a country for which there is a medium level of postaldata available. Addresses in this match level can have the following

B

address elements validated and corrected, and added if missing fromthe input:

• Postal code• City name• State/county name• Country name

The address is in a country for which the postal data is least detailed.Addresses in this match level can have the following actions performedon them:

C

• Validate and correct country name (cannot supply missing countryname)

• Validate the format of the postal code (cannot supply missing postalcode or validate the code)

MatchScore provides an indication of the degree to which the output addressis correct. It is significantly different from Confidence in that Confidence is

MatchScore

indicates how much the input address changed to obtain a match, whereasthe meaning of Match Score varies between U.S. and non-U.S. addresses.

For U.S. addresses, MatchScore is a one-digit score on a scale of 0 to 9 thatreflects the closeness of the street-name match (after transformations byValidateAddress, if any). Zero indicates an exact match and 9 indicates theleast likely match. If no match was found, this field is blank.

For non-U.S. and non-Canadian addresses, MatchScore is a five-digit score,with a maximum value of 00999. Higher numbers indicates a closer match.

This field does not apply to Canadian addresses.

Note that you cannot equate match scores from U.S. addresses with thoseof non-U.S. addresses. For example, a match score of 4 for a U.S addressdoes not indicate the same level of match as a 00004 for a non-U.S. address.

The Validate Address and Advanced Matching Module componentsboth use the MatchScore field. The MatchScore field value in the

Note:

output of a dataflow is determined by the last stage to modify thevalue before it is sent to an output stage. If you have a dataflow thatcontains Validate Address and Advanced Matching Modulecomponents and you want to see the MatchScore field output foreach stage, use a Transformer stage to copy the MatchScore valueto another field. For example, Validate Address produces an outputfield called MatchScore and then a Transformer stage copies theMatchScore field from Validate Address to a field calledAddressMatchScore. When the matcher stage runs it populates theMatchScore field with the value from the matcher and passes throughthe AddressMatchScore value from Validate Address.

If multiple matches were found, indicates the number of records that arepossible matches.

MultimatchCount




Indicates which address component hadmultiple matches, if multiple matcheswere found:

MultipleMatches

• Firm• LeadingDirectional• PostalCode• StreetName• StreetSuffix• TrailingDirectional• Urbanization

More than one component may be returned, in a comma-separatedlist.

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 Canadian postal authorities(supported for 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

Reports the success or failure of the match attempt. For multiple matches,this field is "F" for all the possible matches.

Status

Successnull

FailureF

Reason for failure, if there is one. For multiple matches, all possible matchesis "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 215.

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 119: Field-Level Result Indicators


These result codes apply to international addressesonly.

AddressRecord.Result

Multiple. The input address matchedmultiple records in the postal database,

M

and each matching record has a differentvalue in this field.

Standardized. This option includes anystandard abbreviations.

S

Unmatched.U

Validated. The data was confirmed correctand remained unchanged from input.

V

ApartmentLabel.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A

Corrected. U.S. and Canadian addressesonly.

C

Dropped. The field provided on input wasremoved. U.S. and Canadian addresses

D

only. For more information, see AboutAdditionalInputData on page 266.

Formatted. The spacing and/or punctuationwas changed to conform to postal

F




standards. Does not apply to U.S. orCanadian addresses.

Pass-through. The data was not used in thevalidation process, but it was preserved in

P

the output. U.S. and Canadian addressesonly.

The apartment label is required but ismissing from the input address. U.S.addresses only.

R


S

Unmatched. Does not apply to Canadianaddresses.

U


V

ApartmentNumber.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A

Corrected. Canadian addresses only.C

Dropped. The field provided on input wasremoved. U.S. addresses only. For more

D

information, see AboutAdditionalInputData on page 266.


F



P

the output. U.S. addresses that are an EWSmatch will have a value of P. U.S. andCanadian addresses only.

The apartment number is required but ismissing from the input address. U.S.addresses only.

R

Standardized. This option includes anystandard abbreviations. Does not apply toU.S. addresses.

S

Unmatched.U


V

City.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A





C

Hyphens missing or punctuation errors.Canadian addresses only.

F

Multiple. The input address matchedmultiple records in the postal database, and

M

each matching record has a different valuein this field. Does not apply to U.S. orCanadian addresses.

Pass-through. The data was not used in thevalidation process, but it was preserved inthe output.

P

The city is required but is missing from theinput address. U.S. addresses only.

R


S


U


V

These result codes do not apply to U.S. orCanadian addresses.

Country.Result


M



S

Unmatched.U


V

FirmName.Result Corrected. U.S. addresses only.C

Pass-through. The data was not used inthe validation process, but it was preserved

P

in the output. U.S. and Canadian addressesonly.

Unmatched. U.S. and Canadian addressesonly.

U

Validated. The data was confirmed correctand remained unchanged from input. U.S.addresses only.

V

HouseNumber.Result Appended. The field was added to a blankinput field. Canadian addresses only.

A






D



F


Out of range. Does not apply to U.S. orCanadian addresses.

O

Pass-through. The data was not used in thevalidation process, but it was preserved inthe output. Canadian addresses only.

P

The house number is required but ismissing from the input address. Canadianaddresses only.

R

Standardized. This option includes anystandard abbreviations. Does not apply toU.S. or Canadian addresses.

S

Unmatched.U


V

LeadingDirectional.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A

Corrected. Non-blank input was correctedto a non-blank value. U.S. addresses only.

C


D



F



M

each matching record has a different valuein this field. U.S. addresses only.


P


S




Unmatched.U

Validated. The data was confirmed correctand remained unchanged from input. Doesnot apply to Canadian addresses.

V

POBox.Result Appended. The field was added to a blankinput field. Canadian addresses only.

A



D



F


Multiple matches. The input addressmatched multiple records in the postal

M

database, and each matching record has adifferent value in this field. U.S. addressesonly.


P

The P.O. Box number is required but ismissing from the input address. U.S.addresses only.

R


S

Unmatched.U


V

PostalCode.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A


C


F


Multiple. The input addressmatchedmultiplerecords in the postal database, and each

M

matching record has a different value in thisfield. Does not apply to Canadianaddresses.





P

the output. Does not apply to U.S.addresses.

The postal code is required but is missingfrom the input address. U.S. addresses only.

R

Standardized. This option includes anystandard abbreviations. Does not apply toU.S. or Canadian addresses.

S

Unmatched. For example, if the street namedoes not match the postal code, both

U

StreetName.Result and PostalCode.Resultwill contain U.


V


PostalCodeCity.Result


M

each matching record has a different valuein this field.

Pass-through. The data was not used inthe validation process, but it was preservedin the output.

P


S

Unmatched.U


V

These result codes apply to U.S. addresses only.PostalCode.Source

The ZIP Code™ in the input wasverified by using USPS®

Finance Number groupings.

FinanceNumber

The ZIP Code™ in the inputaddress was corrected because

ZIPMOVE

the USPS® redrew ZIP Code™

boundaries and the address isnow in a different ZIP Code™.

PostalCode.Type The ZIP Code™ contains only PO Boxaddresses. U.S. addresses only.

P

The ZIP Code™ is a unique ZIP Code™

assigned to a specific company orlocation. U.S. addresses only.

U




The ZIP Code™ is for military addresses.U.S. addresses only.

M

The ZIP Code™ is a standard ZIP Code™.null

RRHC.Result Corrected. Canadian addresses only.C


D


Multiple matches. The input addressmatched multiple records in the postal

M

database, and each matching record has adifferent value in this field. U.S. addressesonly.


P

The rural route/highway contract is requiredbut is missing from the input address. U.S.addresses only.

R

Standardized. This option includes anystandard abbreviations. U.S. and Canadianaddresses only.

S

Unmatched. U.S. and Canadian addressesonly.

U

Validated. The data was confirmed correctand remained unchanged 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 Contractaddress.

HC

The address is a Rural Route address.RR

StateProvince.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A

Corrected. U.S. addresses only.C


M

each matching record has a different valuein this field. Does not apply to U.S. orCanadian addresses.

Pass-through. The data was not used in thevalidation process, but it was preserved inthe output.

P




The state is required but is missing fromthe input address. U.S. addresses only.

R


S


U


V


Street.Result


M

each matching record has a different valuein this field.

Pass-through. The data was not used inthe validation process, but it was preservedin the output.

P

Street corrected. House number is out ofrange. Applies to UK and Japanese recordsonly.

R


S

Unmatched.U


V

Indicates the result of abbreviated alias processing.One of the following:

StreetName.AbbreviatedAlias.Result

No abbreviated alias processingattempted.

null

The StreetName field contains the basestreet name.

B

The standardized address length is lessthan 31 characters so the StreetNamefield contains the base name.

L

No abbreviated alias found.N

An abbreviated alias was found for inputaddress. The StreetName field containsthe abbreviated alias.

Y

This result code applies to U.S. addresses only.StreetName.Alias.Type

In previous releases this field was namedStreetName.AliasType with no "." between

Note:

"Alias" and "Type." This old name isobsolete. Please update your processes




to use the new nameStreetName.Alias.Type.

The alias is an abbreviation of thestreet name. For example,

Abbreviated

HARTS-NM RD is an abbreviatedalias for HARTSVILLE NEWMARLBORO RD.

There has been an official streetname change and the alias reflects

Changed

the new name. For example ifSHINGLE BROOK RD is changedto CANNING DR, then CANNINGDR would be a changed alias type.

The street alias is made up of othernames for the street or commonabbreviations of the street.

Other

The street alias is the locallypreferred alias. For example, a

Preferred

street is named "South Shore Dr."because it runs along the southernshore of a lake, not because it issouth of a municipal demarcationline. So, "South" is not apredirectional in this case andshould not be shorted to "S". So,"South Shore Dr." would be thepreferred 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 notattempted because the input address

A

matched to an alias. Preferred aliasprocessing is only attempted for baseaddresses.

No preferred alias found.N

A preferred alias was found for the inputaddress. The StreetName field containsthe preferred alias.

Y

StreetName.Result Appended. The field was added to a blankinput field. Canadian addresses only.

A


C


D






F



M



P

the output. Does not apply to U.S.addresses.

Standardized. This option includes anystandard abbreviations. U.S. and Canadianaddresses only.

S

Unmatched.U


V

StreetSuffix.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A


C


D



F



M



P


S

Unmatched. Does not apply to U.S.addresses.

U


V




TrailingDirectional.Result Appended. The field was added to a blankinput field. U.S. and Canadian addressesonly.

A


C


D



F



M



P


S


U


V

These result codes apply to U.S. addresses only.USUrbanName.Result

Appended. The field was added to a blankinput 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. Mail can be delivered to the address.Y

Mail cannot be delivered to the address.N

The building number was validated but the unit number couldnot be confirmed. A building number is the primary address

S

number for a building. A unit number is a number of a distinctmailing address within a building such as an apartment, suite,floor, and so on. For example, in this address 424 is the buildingnumber and 12 is the unit number:

424 Washington Blvd. Apt. 12Oak Park IL 60302USA

The building number was validated but the unit number wasmissing from input. A building number is the primary address

D

number for a building. A unit number is a number of a distinctmailing address within a building such as an apartment, suite,floor, and so on. For example, in this address 424 is the buildingnumber and 12 is the unit number:




424 Washington Blvd. Apt. 12Oak Park IL 60302USA

The address matches multiple valid delivery points.M

The address could not be confirmed because the address didnot 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 266• Extraneous Data on Its Own Address Line on page 267• Extraneous Data Within an Address Line on page 267• Dual Addresses on page 268

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 215 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 224.

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

http://server:port/soap/ValidateAddressGlobal

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:val="http://www.pb.com/spectrum/services/ValidateAddressGlobal">


<val:ValidateAddressGlobalRequest><val:input>

<val:Address><val:Country>USA</val:Country><val:AddressLine1>1 Global View</val:AddressLine1><val:City>Troy</val:City><val:StateProvince>NY</val:StateProvince><val:PostalCode></val:PostalCode>

</val:Address></val:input>

</val:ValidateAddressGlobalRequest></soapenv:Body>

</soapenv:Envelope>





<ns3:ValidateAddressGlobalResponse xmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/ValidateAddressGlobal"><ns3:output>

<ns3:Address><ns3:Country>UNITED STATES</ns3:Country><ns3:AddressLine1>1 GLOBAL VW</ns3:AddressLine1><ns3:HouseNumber>1</ns3:HouseNumber><ns3:StreetName>GLOBAL</ns3:StreetName><ns3:StreetSuffix>VW</ns3:StreetSuffix><ns3:City>TROY</ns3:City><ns3:PostalCode>12180-8371</ns3:PostalCode><ns3:PostalCode.Base>12180</ns3:PostalCode.Base><ns3:PostalCode.AddOn>8371</ns3:PostalCode.AddOn><ns3:StateProvince>NY</ns3:StateProvince><ns3:County>RENSSELAER</ns3:County><ns3:LastLine>TROY NY 12180-8371</ns3:LastLine><ns3:AddressBlock1>1 GLOBAL VW</ns3:AddressBlock1><ns3:AddressBlock2>TROY NY 12180-8371</ns3:AddressBlock2><ns3:ProcessStatus>C4</ns3:ProcessStatus><ns3:ProcessStatus.Description>

Corrected – all elements have been checked</ns3:ProcessStatus.Description><ns3:ModeUsed>BATCH</ns3:ModeUsed><ns3:CountOverflow>NO</ns3:CountOverflow><ns3:MailabilityScore>5</ns3:MailabilityScore><ns3:Confidence>85.09</ns3:Confidence>

<ns3:ElementResultStatus>88F0F8E0F000000000E0</ns3:ElementResultStatus>

<ns3:ElementInputStatus>00606050600000000060</ns3:ElementInputStatus>

<ns3:ElementRelevance>11101010100000000010</ns3:ElementRelevance><ns3:AddressType>S</ns3:AddressType><ns3:AMAS.Status>EAM0</ns3:AMAS.Status><ns3:user_fields/>

</ns3:Address></ns3:output>

</ns3:ValidateAddressGlobalResponse></soap:Body>

</soap:Envelope>

Request

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

Table 120: ValidateAddressGlobal Input


These fields contain address line data. AddressLine1 containsthe first address line, AddressLine2 contains the second

String[79]

AddressLine1 throughAddressLine6

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]

City


StateProvince

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

String[79]:

9999999999-9999

PostalCode

A9A9A9A9A 9A99999999

The name of the addressee. For example, "Mr. Jones".String[79]

Contact

The country name. If no value is specified in the or option,you must specify a country.

String[79]

Country


FirmName

StreetString[79]

Street

NumberBuilding[79]

Number

BuildingString[79]

Building

SubBuildingString[79]

SubBuilding

DeliveryServiceString[79]

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]

UnformattedLine1 throughUnformattedLine10

UnformattedLine1: 17413 Blodgett RoadUnformattedLine2: PO Box 123




UnformattedLine3: 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.


Table 121: 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

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.

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

Causes address records to be always treated as originating from the countryspecified here, overriding the country in the address record and the default

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

Enables you to use non-standard formatting for multi-line addresses in inputfiles. Acceptable values for this field include the following:

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)



Description/Valid ValuesParameter

The same value must be selected for both the input option and outputoption.

Note:

Output Options

Table 122: 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

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

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

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.

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

Specifies the language in which the output should be returned. Thealphabet in which the data is returned differs from country to country,

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

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



LatinDatabaseCountry

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 123: ValidateAddressGlobal Process Options


Use this option to set the appropriate balance between processing speedand quality. One of the following:

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:

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 isespecially 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:

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 124: 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:



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 125: 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 322.


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 126: 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 284.

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

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

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

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

http://server:port/soap/ValidateAddressLoqate

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:val="http://www.pb.com/spectrum/services/ValidateAddressLoqate"xmlns:spec="http://spectrum.pb.com/">


<val:ValidateAddressLoqateRequest><val:input_port>

<val:Address><val:AddressLine1>1825 Kramer Ln</val:AddressLine1><val:City>Austin</val:City>



<val:StateProvince>TX</val:StateProvince></val:Address>

</val:input_port></val:ValidateAddressLoqateRequest>




<ns3:ValidateAddressLoqateResponse xmlns:ns2="http://spectrum.pb.com/"

xmlns:ns3="http://www.pb.com/spectrum/services/ValidateAddressLoqate"><ns3:output_port>

<ns3:Address><ns3:Confidence>95</ns3:Confidence><ns3:CouldNotValidate/><ns3:ProcessedBy>LOQATE</ns3:ProcessedBy><ns3:MatchScore>100.0</ns3:MatchScore><ns3:AddressLine1>1825 Kramer Ln</ns3:AddressLine1><ns3:AddressLine2/><ns3:City>Austin</ns3:City><ns3:StateProvince>TX</ns3:StateProvince><ns3:PostalCode>78758-4260</ns3:PostalCode><ns3:PostalCode.Base>78758</ns3:PostalCode.Base><ns3:PostalCode.AddOn>4260</ns3:PostalCode.AddOn><ns3:Country>United States</ns3:Country><ns3:FirmName/><ns3:user_fields/>


</ns3:ValidateAddressLoqateResponse></soap:Body>

</soap:Envelope>

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 288 for importantinformation about how address line data is processed for U.S. addresses.



The first address line.StringAddressLine1

The second address line.StringAddressLine2

The third address line.StringAddressLine3

The fourth address line.StringAddressLine4

The city name.StringCity

The country code or name, in any of the following formats:StringCountry

• Two-character ISO 3116-1 Alpha-2 country code• Three-character ISO 3116-1 Alpha-3 country code• English country name




See Country ISO Codes and Module Support on page 322for a list of ISO codes.

The company or firm name.StringFirmName

The postal code for the address in one of the followingformats:

StringPostalCode

9999999999-9999A9A9A9A9A 9A99999 999

The state or province.StringStateProvince

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 128: Output Data Options


Specifies which database you want to use for validatinginternational addresses. To specify a database for

Database.Loqate

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




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

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




Specifies whether to return a formatted version of the addressas it would be printed on a physical mailpiece. Each line of

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.





M



U

Specifies the default country. You should specify the countrywhere most of your addresses reside. For example, if most

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, HolySee, 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, NetherlandsAntilles, New Caledonia, New Zealand, Nicaragua, Niger,Nigeria, Niue, Norway, Oman, Pakistan, Palau, Panama,Papua New Guinea, Paraguay, Peru, Philippines, PitcairnIslands, Poland, Portugal, Puerto Rico, Qatar, Republic OfGeorgia, Republic Of Korea, Republic Of Singapore, Reunion,Romania, Russia, Rwanda, Saint Helena, Saint Kitts AndNevis, Saint Lucia, Saint Pierre And Miquelon, Saint VincentAnd The Grenadines, Samoa, San Marino, Sao Tome AndPrincipe, 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, Trinidad AndTobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan,Turks And Caicos Islands, Tuvalu, Uganda, Ukraine, UnitedArab Emirates, United Kingdom, United States, Uruguay,Uzbekistan, Vanuatu, Venezuela, Vietnam, Virgin Islands(US), Wallis And 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,

OutputCountryFormat

the country name "Deutschland" would be returned as"Germany".


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.

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


Indicates whether or not to return multiple address for thoseinput addresses that have more than one possible match.

KeepMultimatch



For more information, see Returning Multiple Matches onpage 292.

Fails multiple addresses for those input addresses that havemore than one possible match.

Fail Multiple Matches

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 129: 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 288. To identify which recordsare the candidate addresses, look for multiple "M" values in the field-level result indicators. For moreinformationResult Indicators on page 297, 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



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

Note:

Table 131: 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 132: 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

Table 134: City/Street/Postal Code Centroid Match Codes

Match CodeElement

P4Address Point

I4Address Point Interpolated

A4/P3Street Centroid




Match CodeElement

A3/P2/A2Postal Code/City Centroid

Geocode.Match.Code does not return two coordinates for astreet segment (such as the beginning and ending of a portion

Note:

of a street). Instead, with input resulting in return codes of I3(interpolated to thoroughfare or street level, where no inputpremise number was provided), the complete street is used inthe computation.

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 135: 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 342.

If no match was found, which address component could not be validated:CouldNotValidate

• ApartmentNumber• HouseNumber• StreetName




• PostalCode• City• Directional• StreetSuffix• Firm• POBoxNumber

More than one component may be returned, in acomma-separated list.

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 136: Field-Level Result Indicators


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 AboutAdditional Input Data.

D

Formatted. The spacing and/or punctuation was changed toconform to postal standards.

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

Validated. The data was confirmed correct and remainedunchanged from input.

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

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

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


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

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

Standardized. This option includes any standard abbreviations.Does not apply to U.S. or Canadian addresses.

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

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. U.S. and Canadianaddresses only.

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

Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field.

M

Pass-through. The data was not used in the validationprocess, but it was preserved in the output.

P

Street corrected. House number is out of range. Applies toUK and Japanese records only.

R

Standardized. This option includes any standardabbreviations.

S

Unmatched.U


V

StreetName.Result Appended. The field was added to a blank input field. Canadianaddresses only.

A



D


F





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

Standardized. This option includes any standard abbreviations.U.S. and Canadian addresses only.

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

http://server:port/soap/OpenNameParser

Example


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:open="http://www.pb.com/spectrum/services/OpenNameParser"xmlns:spec="http://spectrum.pb.com/">


<open:OpenNameParserRequest><open:input_port>

<open:Input><open:Name>John Williams Smith</open:Name>

</open:Input></open:input_port>

</open:OpenNameParserRequest>






<ns3:OpenNameParserResponse xmlns:ns2="http://spectrum.pb.com/"xmlns:ns3="http://www.pb.com/spectrum/services/OpenNameParser">


<ns3:Name>John Williams Smith</ns3:Name><ns3:CultureCodeUsedToParse/><ns3:FirstName>John</ns3:FirstName><ns3:LastName>Smith</ns3:LastName><ns3:MiddleName>Williams</ns3:MiddleName><ns3:Names/><ns3:IsParsed>true</ns3:IsParsed><ns3:IsPersonal>true</ns3:IsPersonal><ns3:IsConjoined>false</ns3:IsConjoined><ns3:IsReverseOrder>false</ns3:IsReverseOrder><ns3:IsFirm>false</ns3:IsFirm><ns3:NameScore>100</ns3:NameScore><ns3:user_fields/>


</ns3:OpenNameParserResponse></soap:Body>

</soap:Envelope>

Request


Table 137: Open Name Parser Input


The culture of the input name data. The options are listed below.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.Name

OptionsParameters for Parsing Options

The following table lists the options that control the parsing of names.



Table 138: Open Name Parser Parsing Options


Specifies whether to parse names where the is inthe order Title, First Name, Middle Name, LastName, and Suffix.

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.

ParseReverseOrderPersonalNames

Parse personal names that are inreverse order.

true

Do not parse names that are inreverse order.

false

Specifies whether to parse conjoined names.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.

SplitConjoinedNames

Split conjoined names.true

Do not split conjoined names.false

Specifies whether to parse business names.ParseBusinessNames

Parse business names.true

Do not parse business names.false

Specifies whether to return the parsed nameelements in a list form.

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

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 139: Open Name Parser Cultures Options


Specifies which culture(s) you want to include inthe parsing grammar. Global Culture is the defaultselection.

DefaultCulture

Specify cultures by specifying the two-characterculture code in a comma-separated list in priorityorder. For example, to attempt to parse the nameusing the Spanish culture first then Japanese, youwould specify:

es,ja,,

Parameters for Advanced Options

The following table lists the advanced options for name parsing.

Table 140: Open Name Parser Advanced Options

DescriptionOption

Specifies the domain to use when parsing naturalorder personal names. The valid values are the

NaturalOrderPersonalNamesDomain

domain names defined in the Open Parser DomainEditor too in Enterprise Designer.

Specify a number between 1 and 5 that indicatesthe priority of the natural order personal names

NaturalOrderPersonalNamesPriority

domain relative to the other domains that you areusing. This determines the order in which you wantthe parsers to run.

Results will be returned for the first domain thatscores higher than the number set in the shortcutthreshold option. If no domain reaches thatthreshold, results for the domain with the highestscore are returned. If multiple domains reach thethreshold at the same time, priority goes to thedomain that was run first (determined by the orderset here) and its results will be returned.

Specifies the domain to use when parsing reverseorder personal names. The valid values are the

ReverseOrderPersonalNamesDomain

domain names defined in the Open Parser DomainEditor too in Enterprise Designer.

Specify a number between 1 and 5 that indicatesthe priority of the reverse order personal names

ReverseOrderPersonalNamesPriority

domain relative to the other domains that you areusing. This determines the order in which you wantthe parsers to run.

Results will be returned for the first domain thatscores higher than the number set in the shortcutthreshold option. If no domain reaches that



DescriptionOption

threshold, results for the domain with the highestscore are returned. If multiple domains reach thethreshold at the same time, priority goes to thedomain that was run first (determined by the orderset here) and its results will be returned.

Specifies the domain to use when parsing naturalorder conjoined personal names. The valid values

NaturalOrderConjoinedPersonalNamesDomain

are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.

Specify a number between 1 and 5 that indicatesthe priority of the natural order conjoined personal

NaturalOrderConjoinedPersonalNamesPriority

names domain relative to the other domains thatyou are using. This determines the order in whichyou want the parsers to run.


Specifies the domain to use when parsing reverseorder conjoined personal names. The valid values

ReverseOrderConjoinedPersonalNamesDomain

are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.

Specify a number between 1 and 5 that indicatesthe priority of the reverse order conjoined personal

ReverseOrderConjoinedPersonalNamesPriority

names domain relative to the other domains thatyou are using. This determines the order in whichyou want the parsers to run.


Specifies the domain to use when parsing businessnames. The valid values are the domain names

BusinessNamesDomain

defined in the Open Parser Domain Editor too inEnterprise Designer.

Specify a number between 1 and 5 that indicatesthe priority of the business names domain relative

BusinessNamesPriority

to the other domains that you are using. Thisdetermines the order in which you want the parsersto run.



DescriptionOption


Response

Table 141: 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315• Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319• Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321• ValidateAddress Confidence Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341

AThe ACR Code

In this section:

• The ACR Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

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

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

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.

Note that the Enterprise Geocoding Module includes databases for Africa (30 countries), Middle East (8countries) and Latin America (20 countries). These databases cover the smaller countries in thoseregions that do not have their own country-specific geocoding databases. The Supported Modules columnindicates which countries are covered by these Africa, Middle East, and Latin America databases.

Also, the Geocode Address World database provides geographic and limited postal geocoding (but notstreet-level geocoding) for all countries.

Supported ModulesISO 3116-1Alpha-3

ISO 3116-1Alpha-2

ISO Country Name

Address Now ModuleUniversal Addressing Module

AFGAFAfghanistan


ALAAXAland Islands


ALBALAlbania


DZADZAlgeria


ASMASAmerican Samoa

Address Now ModuleEnterprise Geocoding Module1

ANDADAndorra

Universal Addressing ModuleGeoComplete Module

Address Now ModuleEnterprise Geocoding Module (Africa)Universal Addressing Module

AGOAOAngola


AIAAIAnguilla


ATAAQAntarctica


ATGAGAntigua And Barbuda

Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module

ARGARArgentina


ARMAMArmenia

1 Andorra is covered by the Spain geocoder



ISO 3116-1Alpha-2

ISO Country Name

Address Now ModuleEnterprise Geocoding Module (Latin

ABWAWAruba

America)Universal Addressing Module

Address Now ModuleEnterprise Geocoding Module

AUSAUAustralia

Enterprise Routing ModuleUniversal Addressing Module


AUTATAustria

Enterprise Routing ModuleUniversal Addressing ModuleGeoComplete Module


AZEAZAzerbaijan


BHSBSBahamas

Address Now ModuleEnterprise Geocoding Module (Middle

BHRBHBahrain

East)Enterprise Routing ModuleUniversal Addressing Module


BGDBDBangladesh


BRBBBBarbados



BLRBYBelarus


BELBEBelgium



BLZBZBelize



BENBJBenin


Appendix C: Country Codes


ISO 3116-1Alpha-2

ISO Country Name


BMUBMBermuda


BTNBTBhutan


BOLBOBolivia, Plurinational State Of



BESBQBonaire, Saint Eustatius AndSaba


BIHBABosnia And Herzegovina


BWABWBotswana


BVTBVBouvet Island


BRABRBrazil



IOTIOBritish Indian Ocean Territory


BRNBNBrunei Darussalam


BGRBGBulgaria


BFABFBurkina Faso


BDIBIBurundi


KHMKHCambodia


CMRCMCameroon



ISO 3116-1Alpha-2

ISO Country Name


CANCACanada



CPVCVCape Verde


CYMKYCayman Islands


CAFCFCentral African Republic


TCDTDChad


CHLCLChile



CHNCNChina


CXRCXChristmas Island


CCKCCCocos (Keeling) Islands


COLCOColombia


COMKMComoros


COGCGCongo


CODCDCongo, The DemocraticRepublic Of The


COKCKCook Islands


CRICRCosta Rica





ISO 3116-1Alpha-2

ISO Country Name


CIVCICôte d'Ivoire


HRVHRCroatia



CUBCUCuba



CUWCWCuracao


CYPCYCyprus


CZECZCzech Republic



DNKDKDenmark



DJIDJDjibouti


DMADMDominica


DOMDODominican Republic



ECUECEcuador



EGYEGEgypt



SLVSVEl Salvador



ISO 3116-1Alpha-2

ISO Country Name



GNQGQEquatorial Guinea


ERIEREritrea


ESTEEEstonia



ETHETEthiopia


FLKFKFalkland Islands (Malvinas)


FROFOFaroe Islands


FJIFJFiji


FINFIFinland



FRAFRFrance


Address Now ModuleEnterprise Geocoding Module 2


GUFGFFrench Guiana


PYFPFFrench Polynesia


ATFTFFrench Southern Territories


GABGAGabon

2 French Guiana is covered by the France geocoder




ISO 3116-1Alpha-2

ISO Country Name


GMBGMGambia


GEOGEGeorgia


DEUDEGermany



GHAGHGhana

Address Now ModuleEnterprise GeocodingModule 3UniversalAddressing Module

GIBGIGibraltar


GRCGRGreece


GRLGLGreenland


GRDGDGrenada



GLPGPGuadeloupe


GUMGUGuam


GTMGTGuatemala



GGYGGGuernsey


GINGNGuinea


GNBGWGuinea-Bissau

3 Gibraltar is covered by the Spain geocoder4 Guadeloupe is covered by the France geocode



ISO 3116-1Alpha-2

ISO Country Name


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

ISO Country Name


IMNIMIsle Of Man


ISRILIsrael


ITAITItaly



JAMJMJamaica



JPNJPJapan



JEYJEJersey


JORJOJordan


KAZKZKazakhstan


KENKEKenya


KIRKIKiribati


PRKKPKorea, Democratic People'sRepublic Of


KORKRKorea, Republic Of

Address Now ModuleUniversal Addressing ModuleGeoComplete Module

KOSKSKosovo


KWTKWKuwait




ISO 3116-1Alpha-2

ISO Country Name


KGZKGKyrgyzstan


LAOLALao People's DemocraticRepublic


LVALVLatvia



LBNLBLebanon

East)Universal Addressing Module


LSOLSLesotho


LBRLRLiberia


LBYLYLibyan Arab Jamahiriya


LIELILiechtenstein



LTULTLithuania



LUXLULuxembourg



MACMOMacao


MKDMKMacedonia, Former YugoslavRepublic Of


MDGMGMadagascar

6 Liechtenstein is covered by the Switzerland geocoder7 Luxembourg is covered by the Belgium geocoder




ISO 3116-1Alpha-2

ISO Country Name


MWIMWMalawi


MYSMYMalaysia



MDVMVMaldives


MLIMLMali

Enterprise Routing ModuleAddress Now ModuleUniversal Addressing Module

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

8 Martinique is covered by the France geocoder.9 Mayotte is covered by the France geocoder.



ISO 3116-1Alpha-2

ISO Country Name

Address Now ModuleEnterprise Geocoding Module10Universal Addressing Module

MCOMCMonaco


MNGMNMongolia


MNEMEMontenegro


MSRMSMontserrat

Address Now ModuleEnterprise Geocoding Module (Africa)

MARMAMorocco



MOZMZMozambique


MMRMMMyanmar


NAMNANamibia


NRUNRNauru


NPLNPNepal


NLDNLNetherlands



NCLNCNew Caledonia


NZLNZNew Zealand



NICNINicaragua


10 Monaco is covered by the France geocoder




ISO 3116-1Alpha-2

ISO Country Name


NERNENiger

Address Now ModuleEnterprise Geocoding Module (Africa)

NGANGNigeria



NIUNUNiue


NFKNFNorfolk Island


MNPMPNorthern Mariana Islands


NORNONorway



OMNOMOman



PAKPKPakistan


PLWPWPalau


PSEPSPalestinian Territory,Occupied


PANPAPanama



PNGPGPapua New Guinea


PRYPYParaguay



PERPEPeru



ISO 3116-1Alpha-2

ISO Country Name



PHLPHPhilippines


PCNPNPitcairn


POLPLPoland



PRTPTPortugal



PRIPRPuerto Rico


QATQAQatar


Address Now ModuleEnterprise Geocoding Module11Universal Addressing Module

REUREReunion

Address Now ModuleROURORomania

Universal Addressing ModuleEnterprise Routing Module


RUSRURussian Federation



RWARWRwanda


BLMBLSaint Barthelemy

11 Reunion is covered by the France geocoder




ISO 3116-1Alpha-2

ISO Country Name


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

East)Universal Addressing Module


SENSNSenegal


SRBRSSerbia


SYCSCSeychelles


SLESLSierra Leone


SGPSGSingapore


12 San Marino is covered by the Italy geocoder



ISO 3116-1Alpha-2

ISO Country Name

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

ISO Country Name


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



ISO 3116-1Alpha-2

ISO Country Name



TKMTMTurkmenistan


TCATCTurks And Caicos Islands


TUVTVTuvalu


UGAUGUganda


UKRUAUkraine



AREAEUnited Arab Emirates



GBRGBUnited Kingdom



USAUSUnited States



UMIUMUnited States Minor OutlyingIslands


URYUYUruguay


UZBUZUzbekistan


VUTVUVanuatu


VENVEVenezuela, BolivarianRepublic Of




ISO 3116-1Alpha-2

ISO Country Name


VNMVNViet Nam


VGBVGVirgin Islands, British


VIRVIVirgin Islands, U.S.


WLFWFWallis and Futuna


ESHEHWestern Sahara


YEMYEYemen


ZMBZMZambia


ZWEZWZimbabwe


DValidateAddress ConfidenceAlgorithm

In this section:

• Introduction to the Validate Address ConfidenceAlgorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342

• Confidence Algorithm for U.S. and Canadian Addresses .342• Confidence Algorithm for International Addresses . . .343

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 142: 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 143: 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 144: 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 145: 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

© 2014 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.

© 2014 TomTom. All rights reserved. TomTom and the TomTom logo are registered trademarks ofTomTom N.V.

© Copyright NAVTEQ. All rights reserved

Data © 2014 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 Second Decimal, LLC

© 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 the


http://www.geonames.org

http://creativecommons.org/licenses/by/3.0/legalcode

Software, and to permit persons to whom the Software is furnished to do so, provided that the abovecopyright 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

Date post:	11-Apr-2018
Category:	Documents
Upload:	trinhdang
View:	234 times
Download:	3 times

SOAP Web Services Guide - Pitney Bowes Support |...

Documents