Upload
dangtruc
View
245
Download
5
Embed Size (px)
Citation preview
Spectrum Technology PlatformVersion 9.0
REST Web Services Guide
Contents
Chapter 1: Getting Started..................................................................................5The REST Interface...............................................................................................6Exposing a Service as a Web Service.................................................................7Sample Web Application.......................................................................................8
Chapter 2: Web Services....................................................................................9Address Now Module..........................................................................................10
BuildGlobalAddress....................................................................................10GetGlobalCandidateAddresses..................................................................21ValidateGlobalAddress...............................................................................28
Enterprise Routing Module................................................................................49GetTravelBoundary.....................................................................................49GetTravelCostMatrix...................................................................................59GetTravelDirections....................................................................................59
Enterprise Tax Module........................................................................................60AssignGeoTAXInfo.....................................................................................60CalculateDistance.......................................................................................86
GeoConfidence Module......................................................................................89GeoConfidenceSurface..............................................................................89
Global Sentry Module.........................................................................................90GlobalSentry...............................................................................................90
Location Intelligence Module.............................................................................97Where to Find Documentation?..................................................................97
Universal Addressing Module............................................................................98AutoCompleteLoqate..................................................................................98GetCandidateAddresses..........................................................................103GetCandidateAddressesLoqate...............................................................112GetCityStateProvince...............................................................................117GetCityStateProvinceLoqate....................................................................120GetPostalCodes.......................................................................................123ValidateAddress........................................................................................126ValidateAddressGlobal.............................................................................180ValidateAddressLoqate.............................................................................198
Universal Name Module....................................................................................217OpenNameParser.....................................................................................217
Appendix..........................................................................................................225
Appendix A: The ACR Code.................................................................227The ACR Code.........................................................................................228
Appendix B: Buffering..........................................................................231Buffering...................................................................................................232
Appendix C: Country Codes.................................................................233Country ISO Codes and Module Support.................................................234
Appendix D: ValidateAddress Confidence Algorithm........................251Introduction to the Validate Address Confidence Algorithm.....................252Confidence Algorithm for U.S. and Canadian Addresses........................252Confidence Algorithm for International Addresses...................................253
Spectrum Technology Platform 9.04
1Getting Started
In this section:
• The REST Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6• Exposing a Service as a Web Service . . . . . . . . . . . . . . . . .7• Sample Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . .8
The REST InterfaceThe REST interface can return results in XML and JSON format. To view the RESTweb services availableon your Spectrum™ Technology Platform server, go to:
http://server:port/rest
By default Spectrum™ Technology Platform uses port 8080 for HTTP communication. Youradministrator may have configured a different port.
Note:
REST services are bound to one of the following:
http://server:port/rest/service_name/results.xml
http://server:port/rest/service_name/results.json
Note the following limitations on REST web services:
• Only the GET method is supported. As a result, you can include only one record at a time in a request.In addition, hierarchical data is not supported.
• We recommend that you limit parameters to 2,048 characters due to URL length limits.
WADL URL
The WADL for Spectrum™ Technology Platform web services is in the form:
http://server:port/rest/service_name?_wadl
For example:
http://myserver:8080/rest/ValidateAddress?_wadl
User Fields
You can pass extra fields through the web service even if the web service does not use them. Thesefields are returned, unmodified, in the user_fields section of the response. For example, if you wantedto pass a field called "customID", the following text would be added to the request URL:
Data.customID=xxx
User field names may not contain characters that are invalid in XML or JSON element names.For example, spaces are not valid.
Note:
Sample REST Request with XML Response
The following REST request calls the ValidateAddress service.
http://localhost:8080/rest/ValidateAddress/results.xml?Option.Database.US=USA&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759
The sample request would result in this response since an XML response was requested:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xml.ValidateAddressResponsexmlns="http://www.pb.com/spectrum/services/ValidateAddress">
<output_port><Address>
<Confidence>82</Confidence><RecordType>Normal</RecordType><CountryLevel>A</CountryLevel><ProcessedBy>USA</ProcessedBy><MatchScore>0</MatchScore><AddressLine1>1825 Kramer Ln</AddressLine1>
Spectrum Technology Platform 9.06
The REST Interface
<City>Austin</City><StateProvince>TX</StateProvince><PostalCode>78758-4260</PostalCode><PostalCode.Base>78758</PostalCode.Base><PostalCode.AddOn>4260</PostalCode.AddOn><Country>United States Of America</Country><user_fields/>
</Address></output_port>
</xml.ValidateAddressResponse>
Sample REST Request with JSON Response
Below is a sample JSON request.
http://localhost:8080/rest/ValidateAddress/results.json?Option.Database.US=USA&Data.AddressLine1=1825+Kramer+Lane&Data.PostalCode=78759
The sample request wold result in this response since a JSON response was requested:
{"ns1.json.ValidateAddressResponse" :{"ns1.output_port" :{"ns1.Confidence" : 82,"ns1.RecordType" : "Normal","ns1.CountryLevel" : "A","ns1.ProcessedBy" : "USA","ns1.MatchScore" : 0,"ns1.AddressLine1" : "1825 Kramer Ln","ns1.City" : "Austin","ns1.StateProvince" : "TX","ns1.PostalCode" : "78758-4260","ns1.PostalCode.Base" : 78758,"ns1.PostalCode.AddOn" : 4260,"ns1.Country" : "United States Of America"}}}
Exposing a Service as a Web ServiceSpectrum™ Technology Platform services can be made available as REST and/or SOAP web services.To make a service available on your server as a web service:
1. Open Enterprise Designer.2. Open the service that you want to expose as a web service.3. Go to Edit > Web Service Options.4. Select one of the following options:
Expose the service via enhanced SOAP, which provides more options,including faults, basic authentication, and more.
SOAP
Expose the service via REST.REST
5. Click OK.
To verify that the service is now exposed as a web service, go to one of the following URLs:
• For REST: http://server:port/rest• For SOAP: http://server:port/soap
7REST Web Services Guide
Chapter 1: Getting Started
Where server is the name or IP address of your Spectrum™ Technology Platform server and port is theport used for HTTP communication.
Sample Web ApplicationThe following sample class for .NET is written in C# on Visual Studio 2010. Proxy class implementationsfor the web service data types ValidateAddressClient, requestRow, context , options and responseRowwere generated using Visual Studio .NET's "Add Web Reference" command. This example uses theValidateAddress web service. It is important to note that in this example, the appropriate credentialsmust be provided or the call will fail.
namespace Test{
class Program{
static void Main(string[] args){
var validateClient = new ValidateAddress {Credentials = newNetworkCredential("admin", "admin")};
var address1 = new input_portAddress{
AddressLine1 = "1825B Kramer Lane",AddressLine2 = "Suite 100",PostalCode = "78758",City = "Austin",StateProvince = "Texas"
};
var address2 = new input_portAddress{
AddressLine1 = "100 Congress",PostalCode = "78701",City = "Austin",StateProvince = "Texas"
};
var addresses = new input_portAddress[2];addresses[0] = address1;addresses[1] = address2;
var options = new options {OutputCasing = OutputCasing.M};output_portAddress[] results =
validateClient.CallValidateAddress(options, addresses);
for (int i = 0; i < results.Length; i++){
System.Console.WriteLine("Record " + (i+1) + ":");System.Console.WriteLine("AddressLine1=" +
results[i].AddressLine1);System.Console.WriteLine("City=" + results[i].City);System.Console.WriteLine("StateProvince=" +
results[i].StateProvince);System.Console.WriteLine("PostalCode=" +
results[i].PostalCode + "\n");}
System.Console.Write("Press any key to continue...");System.Console.ReadKey();
}}
}
Spectrum Technology Platform 9.08
Sample Web Application
2Web Services
In this section:
• Address Now Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10• Enterprise Routing Module . . . . . . . . . . . . . . . . . . . . . . . .49• Enterprise Tax Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .60• GeoConfidence Module . . . . . . . . . . . . . . . . . . . . . . . . . . .89• Global Sentry Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90• Location Intelligence Module . . . . . . . . . . . . . . . . . . . . . . .97• Universal Addressing Module . . . . . . . . . . . . . . . . . . . . . .98• Universal Name Module . . . . . . . . . . . . . . . . . . . . . . . . . .217
Address Now Module
BuildGlobalAddressBuildGlobalAddress allows you to build a valid address starting with just a single address element or afew address elements. BuildGlobalAddress is part of the Address Now Module.
Resource URL
JSON endpoint:
http://server:port/rest/BuildGlobalAddress/results.json
XML endpoint:
http://server:port/rest/BuildGlobalAddress/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/BuildGlobalAddress/results.json?Data.Action=init&Data.Country=USA
The JSON returned by this request would be:
{"output_port": [{"Action": "init","Country": "USA","SessionId": "n5hiliawx0","SearchFieldIndex": "-1","Field.0.Name": "Zip","Field.0.Index": "0","Field.0.Value": "","Field.0.CommitFlag": "N","Field.1.Name": "City","Field.1.Index": "1","Field.1.Value": "","Field.1.CommitFlag": "N","Field.2.Name": "State","Field.2.Index": "2","Field.2.Value": "","Field.2.CommitFlag": "N","Field.3.Name": "County","Field.3.Index": "3","Field.3.Value": "","Field.3.CommitFlag": "N","Field.4.Name": "Street","Field.4.Index": "4","Field.4.Value": "","Field.4.CommitFlag": "N","Field.5.Name": "Company","Field.5.Index": "5","Field.5.Value": "","Field.5.CommitFlag": "N","Field.6.Name": "Building","Field.6.Index": "6","Field.6.Value": "","Field.6.CommitFlag": "N","Field.7.Name": "Premise-No","Field.7.Index": "7",
Spectrum Technology Platform 9.010
Address Now Module
"Field.7.Value": "","Field.7.CommitFlag": "N","Field.8.Name": "Sub-Building","Field.8.Index": "8","Field.8.Value": "","Field.8.CommitFlag": "N","Field.9.Name": "PO-Box","Field.9.Index": "9","Field.9.Value": "","Field.9.CommitFlag": "N","Field.10.Name": "+4","Field.10.Index": "10","Field.10.Value": "","Field.10.CommitFlag": "N","Alternatives.InContext": "","Alternatives.InContext.Count": "0","Alternatives.OutContext": "","Alternatives.OutContext.Count": "0","user_fields": []
}]}
Example with XML Response
The following example requests an XML response. This request performs the initialization (init) actionto obtain a session ID from BuildGlobalAddress.
http://myserver:8080/rest/BuildGlobalAddress/results.xml?Data.Action=init&Data.Country=USA
The XML returned by this request would be:
<ns2:xml.BuildGlobalAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/BuildGlobalAddress">
<ns2:output_port><ns2:Result>
<ns2:Action>init</ns2:Action><ns2:Country>USA</ns2:Country><ns2:SessionId>qbximydxf0</ns2:SessionId><ns2:Field.0.Name>Zip</ns2:Field.0.Name><ns2:Field.0.Index>0</ns2:Field.0.Index><ns2:Field.0.Value/><ns2:Field.0.CommitFlag>N</ns2:Field.0.CommitFlag><ns2:Field.1.Name>City</ns2:Field.1.Name><ns2:Field.1.Index>1</ns2:Field.1.Index><ns2:Field.1.Value/><ns2:Field.1.CommitFlag>N</ns2:Field.1.CommitFlag><ns2:Field.2.Name>State</ns2:Field.2.Name><ns2:Field.2.Index>2</ns2:Field.2.Index><ns2:Field.2.Value/><ns2:Field.2.CommitFlag>N</ns2:Field.2.CommitFlag><ns2:Field.3.Name>County</ns2:Field.3.Name><ns2:Field.3.Index>3</ns2:Field.3.Index><ns2:Field.3.Value/><ns2:Field.3.CommitFlag>N</ns2:Field.3.CommitFlag><ns2:Field.4.Name>Street</ns2:Field.4.Name><ns2:Field.4.Index>4</ns2:Field.4.Index><ns2:Field.4.Value/><ns2:Field.4.CommitFlag>N</ns2:Field.4.CommitFlag><ns2:Field.5.Name>Company</ns2:Field.5.Name><ns2:Field.5.Index>5</ns2:Field.5.Index><ns2:Field.5.Value/><ns2:Field.5.CommitFlag>N</ns2:Field.5.CommitFlag><ns2:Field.6.Name>Building</ns2:Field.6.Name><ns2:Field.6.Index>6</ns2:Field.6.Index><ns2:Field.6.Value/><ns2:Field.6.CommitFlag>N</ns2:Field.6.CommitFlag><ns2:Field.7.Name>Premise-No</ns2:Field.7.Name><ns2:Field.7.Index>7</ns2:Field.7.Index>
11REST Web Services Guide
Chapter 2: Web Services
<ns2:Field.7.Value/><ns2:Field.7.CommitFlag>N</ns2:Field.7.CommitFlag><ns2:Field.8.Name>Sub-Building</ns2:Field.8.Name><ns2:Field.8.Index>8</ns2:Field.8.Index><ns2:Field.8.Value/><ns2:Field.8.CommitFlag>N</ns2:Field.8.CommitFlag><ns2:Field.9.Name>PO-Box</ns2:Field.9.Name><ns2:Field.9.Index>9</ns2:Field.9.Index><ns2:Field.9.Value/><ns2:Field.9.CommitFlag>N</ns2:Field.9.CommitFlag><ns2:Field.10.Name>+4</ns2:Field.10.Name><ns2:Field.10.Index>10</ns2:Field.10.Index><ns2:Field.10.Value/><ns2:Field.10.CommitFlag>N</ns2:Field.10.CommitFlag><ns2:SearchFieldIndex>-1</ns2:SearchFieldIndex><ns2:Alternatives.InContext/><ns2:Alternatives.InContext.Count>
0</ns2:Alternatives.InContext.Count><ns2:Alternatives.OutContext/><ns2:Alternatives.OutContext.Count>
0</ns2:Alternatives.OutContext.Count><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.BuildGlobalAddressResponse>
Using BuildGlobalAddressBuilding an address is an interactive process that requires you to select address elements at each stepof the address building process. This means that building an address requires a sequence of calls toBuildGlobalAddress, not a single call. To start, you make an initialization call to BuildGlobalAddress.This call returns a session ID. You then use this session ID in subsequent calls. With each call,BuildGlobalAddress presents a list of alternative values for an address element. You select the valueyou want, then move on to the next address element until the complete address is built. With someexceptions, you need to make a separate call for each address element.
The overall process works like this:
• First, you make an initialization call to open a session and receive a system-assigned session ID.• Make a search call to find possible values for a given address element.• When you have selected the value you want, you make a commit call to indicate the value you wantfor the given address element.
• Continue to make search/commit calls until all address elements are committed.• Finally, you make a close call to end the session.
To familiarize yourself with how the process works, use the Management Console's Preview tab to stepthrough the following procedure.
1. Open the Management Console.2. Under the Services node, select Build Global Address.3. On the Options tab, specify the options you want. For information on the options, see Parameters
for Options on page 16.4. Click the Preview tab.5. In the Action field type init.6. In the Country field enter the country of the address you want to build.7. Click Run Preview.8. Under Preview Output, find the SessionId field, right-click the value, and select Copy from the pop-up
menu.
Spectrum Technology Platform 9.012
Address Now Module
9. Under Preview Input, right-click the SessionId field and select Paste.
10. Enter the following values in the input fields:
• Action—Type search.• Country—Keep this field the same.• FieldIndex—Type the index value of the first field you want to search. For example, if you knowyou want to search for an address in Chicago, you would type "1" because for U.S. addresses,field index 1 corresponds to the City field.
• SearchValue—Type the value you want to search for. For example, if you want to build an addressin Chicago, you would type "chicago".
• SessionId—Keep the same value.
13REST Web Services Guide
Chapter 2: Web Services
The values in the other input fields are ignored.Note:
11. Click Run Preview again.12. The results of the search are placed in up to two output fields: Alternatives.InContext and
AlternativesOutContext. For an explanation of the difference between in context results and out ofcontext results, see What Is Context? on page 21.
13. When you have found the value you want, enter the following values in the input fields:
• Action—Type commit.• AlternativeIndex—Type the index number for the alternative you choose. Index values start with0, not 1. For example, if you search for Chicago the alternatives returned by BuildGlobalAddresswould be indexed as follows. If you want to commit the value "CHICAGO" you would type "0" inthe AlternativeIndex field.
• 0—CHICAGO• 1—CHICAGO HTS• 2—CHICAGO PARK• 3—CHICAGO RIDGE• 4—EAST CHICAGO• 5—NORTH CHICAGO• 6—WEST CHICAGO
• AlternativeContext—Type in or out to indicate whether the index value you specified inAlternativeIndex is for the list of alternatives in the Alternatives.InContext field or theAlternatives.OutContext field.
• SessionId—Keep this value the same.
The values in the other input fields are ignored.Note:
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.
The values in the other input fields are ignored.Note:
Request
Parameters for Input Data
Table 1: BuildGlobalAddress Input
DescriptionFormatParameter
Specifies the action to take. One of the following:StringData.Action
Initialization. This action opens a session andreturns a session ID which is required for all other
init
actions. The init action requires the Country inputfield.
Searches for values for a specific addresselement and returns a list of alternative values for
search
you to choose. The search action requires thefollowing input fields:
Spectrum Technology Platform 9.014
Address Now Module
DescriptionFormatParameter
• FieldIndex• SearchValue• SessionId
Assigns one of the values returned by the searchaction to the field. The commit action requires thefollowing input fields:
commit
• AlternativeIndex• AlternativeContext• SessionId
Un-commits the field specified in the FieldIndexfield. The clear action requires the following inputfields:
clear
• FieldIndex• SessionID
Ends a session. The close action requires theSessionId input field.
close
For the commit action, indicates whether you are choosing avalue from the Alternatives.InContext field or the
StringData.AlternativeContext
Alternatives.OutContext field. This field is ignored for otheractions. One of the following:
You are committing a value from theAlternatives.InContext field. This means that the
in
value you specify in the AlternativeIndex input fieldcorresponds to a value in theAlternatives.InContextoutput field.
You are committing a value from theAlternatives.OutContext field. This means that the
out
value you specify in the AlternativeIndex input fieldcorresponds to a value in theAlternatives.OutContext output field.
For the commit action, specifies the value you want to use inthe address you are building. For example, if you searched
String[79]
Data.AlternativeIndex
for a city and BuildGlobalAddress returns a list of three cities,you would indicate the city you want by specifying the indexvalue for your choice. Index values for the alternativespresented by BuildGlobalAddress are zero-based, meaningthat the first alternative has an index of 0, the secondalternative has a value of 1, and so on.
The input field is ignored for actions other than commit.
For the init action, specifies the country in which you want tobuild an address. Specify the country using the format you
String[79]
Data.Country
chose for input country format (English name two-characterISO 3116-1 Alpha-2 code, or three-character ISO 3116-1Alpha-3 code). For a list of ISO codes, see Country ISOCodes and Module Support on page 234.
15REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatParameter
This input field is ignored for actions other than init.
For the search action, specifies the address element that youwant to search on. For the clear action, specifies the addresselement you want to un-commit. One of the following:
String[79]
Data.FieldIndex
performs the "clear" action on all addresselements. This option applies to the "clear"action only.
all
Performs the action on a specific addresselement. To determine the index of an
<IndexNumber>
address element, first look at theField.n.Name fields and locate the fieldyou want. The value n indicates the field'sindex. For example, you want to look upZIP Codes for U.S. addresses. After theinit call you see that Field.0.Name is "Zip"indicating that the ZIP Code has a fieldindex of "0".
This input field is ignored for actions other than search andclear.
For the search action, specifies the value you want to searchfor. This value must be appropriate for the field you specified
String[79]
Data.SearchValue
in FieldIndex. For example, if you specified the ZIP Code fieldin FieldIndex, then you would enter a ZIP Code or partial ZIPCode in this field. Likewise if you chose the city field inFieldIndex you would specify a city name or partial city namein this field. if you leave the field blank the search will returnall values that are in context. For more information about incontext and out of context values, see What Is Context? onpage 21.
This input field is ignored for actions other than search.
Specifies the session ID you want to use for this call. To obtaina session ID use the init action. If a session is inactive for 5
String[79]
Data.SessionId
minutes it will expire and you will need to perform a new initcall to start a new session.
This field is required for all actions except init.
Parameters for Options
Table 2: BuildGlobalAddress Options
DescriptionParameter
Specifies the default country. You should specify the country wheremost of the addresses in your data are located. For example, if most of
Option.HomeCountry
your addresses are in Canada, specify Canada. BuildGlobalAddressuses the country you specify to attempt validation when it cannotdetermine the country from the StateProvince, PostalCode, and Countryaddress fields.
Spectrum Technology Platform 9.016
Address Now Module
DescriptionParameter
Specifies the format to use for the country name in the output. One ofthe following:
Option.OutputCountryFormat
The country in the output in English (default).E
The country in the output as the two-character ISO code.I
The country in the output as the three-character UPU code.U
Specifies whether or not to use separators (spaces or hyphens) in ZIPCodes or Canadian postal codes.
Option.OutputPostalCodeSeparator
For example, a ZIP + 4® Code with the separator would be 20706-1844and without the separator it would be 207061844. A Canadian postalcode with the separator would be P5E"1S7 and without the separatorit would be P5E1S7.
Yes, use separator (default).Y
No, do not use separator.N
Spaces are used in Canadian postal codes and hyphens inU.S. ZIP + 4® Codes.
Note:
Specifies whether or not to include the city, state/province, and postalcode in one of the AddressLine output fields. Regardless of what you
Option.ShowExtraAddressLine
specify with this option, the output fields City, State/Province, andPostalCode will always contain the city, state/province, and postal code.
Yes, include city, state/province, and postal code in anAddressLine output field (default).
Y
No, do not include city, state/province, and postal code in anAddressLine output field.
N
Allows you to set the default value for this option to any value from 1 to10000; it has a default value of 50 records. Note that values set inEnterprise Designer override those set in Management Console
Option.MaximumResults
Response
Address Data
Table 3: BuildGlobalAddress Output
DescriptionFormatResponse Element
Shows the value specified in the Action input fieldfor this call. For more information on this input fieldsee Parameters for Input Data on page 14.
String [79]Action
The formatted first address line.String [79]AddressLine1
The formatted second address line.String [79]AddressLine2
The formatted third address line.String [79]AddressLine3
The formatted fourth address line.String [79]AddressLine4
The formatted fifth address line.String [79]AddressLine5
The formatted sixth address line.String [79]AddressLine6
17REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponse Element
The formatted seventh address line.String [79]AddressLine7
The formatted eighth address line.String [79]AddressLine8
Shows the value specified in the AlternativeContextinput field for this call. For more information, seeParameters for Input Data on page 14.
String [79]AlternativeContext
Shows the value specified in the AlternativeIndexinput field for this call. For more information on this
String [79]AlternativeIndex
input field see Parameters for Input Data on page14.
A comma-delimited list of the possible values forthe field you searched on which fit the context of
String [79]Alternatives.InContext
fields you have already committed. For informationon context see What Is Context? on page 21.
The number of "in context" results returned by yoursearch. For information on context see What IsContext? on page 21.
String [79]Alternatives.InContext.Count
A comma-delimited list of the possible values forthe field you searched on which do not fit the
String [79]Alternatives.OutContext
context of fields you have already committed. Forinformation on context see What Is Context? onpage 21.
The number of "out of context" results returned byyour search. For information about context, seeWhat Is Context? on page 21.
String [79]Alternatives.OutContext.Count
Apartment designator (such as STE or APT). Forexample:
String [79]ApartmentLabel
123 E Main St. APT 3
Apartment number. For example:String [79]ApartmentNumber
123 E Main St. APT 3
The name of a building.String [79]Building
The city name.String [79]City
Shows the value specified in the Country input fieldfor this call. For more information about this inputfield, see Parameters for Input Data on page 14.
String [79]Country
The two- or three-character ISO code, or Englishname of the country. For a list of ISO codes, see
String [79]Country
Country ISO Codes and Module Support on page234.
The name of a distinct part of anything arrangedinto divisions. For example, the FinanceDepartment in a corporation.
String [79]Department
Indicates whether you have chosen a value for fieldn (i.e. "committed" a value). One of the following:
String [79]Field.n.CommitFlag
Yes, the value of this field has beencommitted.
Y
Spectrum Technology Platform 9.018
Address Now Module
DescriptionFormatResponse Element
No, the value of this field has not beencommitted.
N
An index value used to refer to field n, where n is0 though 10. For example, for U.S. addresses theindex value of the ZIP field is "0".
String [79]Field.n.Index
The name of the address element contained in fieldn, where n is 0 through 10. For example, for U.S.addresses Field.0.Name is ZIP.
String [79]Field.n.Name
The value that has been committed to field n, wheren is 0 through 10.
String [79]Field.n.Value
This field is blank on the init call.
Shows the value specified in the FieldIndex inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.
String [79]FieldIndex
The name of a company. For example:String [79]FirmName
Pitney Bowes Software4200 PARLIAMENT PL STE 600LANHAM MD 20706-1844USA
House number. For example:String [79]HouseNumber
123 E Main St. Apt 3
The post office box number. If the address is a ruralroute address, the rural route box number willappear here.
String [79]POBox
The postal code. In the U.S. this is the ZIP Code™.String [79]PostalCode
The 4-digit add-on part of the ZIP + 4® Code. Forexample, in the ZIP Code™ 60655-1844, 1844 isthe 4-digit add-on. (U.S. addresses only.)
String [79]PostalCode.AddOn
The 5-digit ZIP Code™. For example 20706 (U.S.addresses only.)
String [79]PostalCode.Base
An area within a country. For example, England,Scotland, and Wales are principalities. This fieldwill normally be blank.
String [79]Principality
The index value of the field searched in theprevious search action.
String [79]SearchFieldIndex
Shows the value specified in the SearchValue inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.
String [79]SearchValue
Shows the value specified in the SessionId inputfield for this call. For more information on this inputfield see Parameters for Input Data on page 14.
String [79]SessionId
The state or province abbreviation.String [79]StateProvince
Street name. For example:String [79]StreetName
123 E Main St. Apt 3
19REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponse Element
Street suffix. For example:String [79]StreetSuffix
123 E Main St. Apt 3
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
DescriptionFormatResponse Element
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
This value will appear ifStatus.Code=SessionError.
Null or emptyaction
This value will appear ifStatus.Code=SessionError.
Unknownaction
Spectrum Technology Platform 9.020
Address Now Module
DescriptionFormatResponse Element
This value will appear ifStatus.Code=SessionError.
Invalid session
This value will appear ifStatus.Code=SessionError.
Invalid value for
This value will appear ifStatus.Code=SessionError.
Cannot SearchCommittedField
This value will appear ifStatus.Code=ServerError.
Module notlicensed
This value will appear ifStatus.Code=CountryNotFound
Could NotIdentify Country
What Is Context?When you perform a search for an address element, BuildGlobalAddress looks at the address elementsthat you have already committed and splits up the values it returns based on whether or not the returnedvalues exist within the context of the address elements you have already committed. For example, inthe U.S. the following cities exist:
In Illinois:
• CHICAGO• CHICAGO HTS• CHICAGO RIDGE• NORTH CHICAGO• WEST CHICAGO
In Indiana:
• EAST CHICAGO
In Nevada:
• CHICAGO PARK
If you have already committed a value of "IN" (Indiana) for the state and then searched for the city"chicago", BuildGlobalAddress would return EAST CHICAGO as an "in context" result because it existsin Indiana, and it would return all the other matches for "chicago" as out-of-context results. Likewise, ifyou committed a value of "IL" (Illinois) for the state, BuildGlobalAddress would return EAST CHICAGOand CHICAGO PARK as out of context, and CHICAGO, CHICAGO HTS, CHICAGO RIDGE, NORTHCHICAGO, and WEST CHICAGO as "in context."
GetGlobalCandidateAddressesGetGlobalCandidateAddresses returns a list of addresses that are considered matches for a given inputaddress. If the input address matches multiple addresses in the Address Now database, the possiblematches are returned. If the input address matches only one address in the Address Now database, noaddress data is returned.
GetGlobalCandidateAddresses is part of the Address Now Module.
21REST Web Services Guide
Chapter 2: Web Services
Resource URL
JSON endpoint:
http://server:port/rest/GetGlobalCandidateAddresses/results.json
XML endpoint:
http://server:port/rest/GetGlobalCandidateAddresses/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetGlobalCandidateAddresses/results.json?Data.AddressLine1=1070+Maple&Data.City=Batavia&Data.StateProvince=NY
The JSON returned by this request would be:
Empty response elements have been removed from this example. Only the first two candidateaddress are shown.
Note:
{"output_port": [{"Confidence": "80","AddressLine1": "1 Maple St","AddressLine2": "Batavia NY 14020-3116","HouseNumber": "1","StreetName": "Maple","StreetSuffix": "St","City": "Batavia","USCountyName": "Genesee","StateProvince": "NY","PostalCode": "14020-3116","Country": "United States","ACRCode": "L5-P5S5A0T4R4Z6C4-080","PostalCode.Base": "14020","PostalCode.AddOn": "3116","user_fields": []
},{"Confidence": "80","AddressLine1": "3 Maple St","AddressLine2": "Batavia NY 14020-3116","HouseNumber": "3","StreetName": "Maple","StreetSuffix": "St","City": "Batavia","USCountyName": "Genesee","StateProvince": "NY","PostalCode": "14020-3116","Country": "United States","ACRCode": "L5-P5S5A0T4R4Z6C4-080","PostalCode.Base": "14020","PostalCode.AddOn": "3116","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetGlobalCandidateAddresses/results.xml?Data.AddressLine1=1070+Maple&Data.City=Batavia&Data.StateProvince=NY
Spectrum Technology Platform 9.022
Address Now Module
The XML returned by this request would be:
Empty response elements have been removed from this example. Only the first two candidateaddress are shown.
Note:
<ns2:xml.GetGlobalCandidateAddressesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetGlobalCandidateAddresses">
<ns2:output_port><ns2:Address>
<ns2:Confidence>80</ns2:Confidence><ns2:AddressLine1>1 Maple St</ns2:AddressLine1><ns2:AddressLine2>Batavia NY 14020-3116</ns2:AddressLine2><ns2:HouseNumber>1</ns2:HouseNumber><ns2:StreetName>Maple</ns2:StreetName><ns2:StreetSuffix>St</ns2:StreetSuffix><ns2:City>Batavia</ns2:City><ns2:USCountyName>Genesee</ns2:USCountyName><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>14020-3116</ns2:PostalCode><ns2:PostalCode.Base>14020</ns2:PostalCode.Base><ns2:PostalCode.AddOn>3116</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:ACRCode>L5-P5S5A0T4R4Z6C4-080</ns2:ACRCode>
</ns2:Address><ns2:Address>
<ns2:Confidence>80</ns2:Confidence><ns2:AddressLine1>3 Maple St</ns2:AddressLine1><ns2:AddressLine2>Batavia NY 14020-3116</ns2:AddressLine2><ns2:HouseNumber>3</ns2:HouseNumber><ns2:StreetName>Maple</ns2:StreetName><ns2:StreetSuffix>St</ns2:StreetSuffix><ns2:City>Batavia</ns2:City><ns2:USCountyName>Genesee</ns2:USCountyName><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>14020-3116</ns2:PostalCode><ns2:PostalCode.Base>14020</ns2:PostalCode.Base><ns2:PostalCode.AddOn>3116</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:ACRCode>L5-P5S5A0T4R4Z6C4-080</ns2:ACRCode>
</ns2:Address></ns2:output_port>
</ns2:xml.GetGlobalCandidateAddressesResponse>
Request
Parameters for Input DataGetGlobalCandidateAddresses takes a standard address as input. All addresses use this format nomatter what country the address is from. AddressLine1 and Country are required input fields. The otherfields are optional.
Table 5: GetGlobalCandidateAddresses Input
DescriptionFormatParameter
First address line. This is a required field.String[79]
Data.AddressLine1
Second address lineString[79]
Data.AddressLine2
Third address lineString[79]
Data.AddressLine3
23REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatParameter
Fourth address lineString[79]
Data.AddressLine4
Fifth address lineString[79]
Data.AddressLine5
Sixth address lineString[79]
Data.AddressLine6
Seventh address lineString[79]
Data.AddressLine7
Eighth address lineString[79]
Data.AddressLine8
City nameString[79]
Data.City
State or province.String[79]
Data.StateProvince
The postal code for the address in one of these formats:String[10]
Data.PostalCode
9999999999-9999A9A9A9A9A 9A99999 999
The country. Specify the country using the format you chose for inputcountry format (English name or ISO code). For a list of ISO codes, seeCountry ISO Codes and Module Support on page 234.
StringData.County
Company or firm nameString[79]
Data.FirmName
Parameters for Options
Table 6: GetGlobalCandidateAddresses Options
DescriptionParameter
Specifies the default country. Specify the country that is the destinationof most of your mailpieces. For example, if most of your mailpieces are
Option.HomeCountry
going to Canada, specify Canada. GetGlobalCandidateAddresses usesthe country you specify to attempt validation when it cannot determinethe country from the StateProvince, PostalCode, and Country addressfields.
Specifies the format to use for the country name in the output. One ofthe following:
Option.OutputCountryFormat
The country in the output in English (default).E
The country in the output in the two-character ISO code.I
The country in the output in the three-character UPU code.U
Spectrum Technology Platform 9.024
Address Now Module
DescriptionParameter
Specifies the casing of the output data. One of the following:Option.OutputCasing
The output in mixed case (default). For example: 123 MainSt Mytown FL 12345
M
The output in upper case. For example: 123 MAIN STMYTOWN FL 12345
U
Specifies whether or not to use separators (spaces or hyphens) in ZIP™
Codes or Canadian postal codes.Option.OutputPostalCodeSeparator
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 separatorN
Spaces are used in Canadian postal codes and hyphens inU.S. ZIP + 4® Codes.
Note:
Specifies whether or not to include the city, state/province, and postalcode in one of the AddressLine output fields. Regardless of what you
Option.ShowExtraAddressLine
specify with this option, the output fields City, State/Province, andPostalCode will always contain the city, state/province, and postal code.
Yes, include city, state/province, and postal code in anAddressLine output field (default).
Y
No, do not include city, state/province, and postal code in anAddressLine output field.
N
The maximum number of candidate addresses to output. The default is50. The maximum value is 100.
Option.MaximumResults
Specifies whether or not to include in the output data from the inputaddress that could not be validated.
Option.ReturnUserData
Yes, include input data that could not be validated.Y
No, do not include input data that could not be validated(default).
N
Response
Address Data
Table 7: GetGlobalCandidateAddresses Address Data Output
DescriptionFormatResponseElement
The formatted first address line.String[79]
AddressLine1
The formatted second address line.String[79]
AddressLine2
The formatted third address line.String[79]
AddressLine3
25REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponseElement
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
123 E Main St. APT 3
Apartment number. For example:String[79]
ApartmentNumber
123 E Main St. APT 3
The name of a building.String[79]
Building
The city name.String[79]
City
The ISO code or English name of the country. For a list of ISO codes,see Country ISO Codes and Module Support on page 234.
String[79]
Country
The name of a distinct part of anything arranged into divisions. Forexample, the Finance Department in a corporation.
String[79]
Department
The name of a company. For example:String[79]
FirmName
Pitney Bowes Software4200 PARLIAMENT PLSTE 600LANHAM MD 20706-1844USA
House number. For example:String[79]
HouseNumber
123 E Main St. Apt 3
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
Spectrum Technology Platform 9.026
Address Now Module
DescriptionFormatResponseElement
Street name. For example:String[79]
StreetName
123 E Main St. Apt 3
Street suffix. For example:String[79]
StreetSuffix
123 E Main St. Apt 3
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
27 Crystal WayBradley StokeBristol BS32 8GA
In this case, "Bradley Stoke" is the 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
12 The MewsHigh Street
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
DescriptionFormatResponseElement
The Address Correction Result (ACR) code describes whatdata has been changed in each record. For information onwhat this code means, see The ACR Code on page 228.
String [79]ACRCode
The level of confidence assigned to the address beingreturned. Range is from zero (0) to 100; zero indicates failure,
String [79]Confidence
100 indicates a very high level of confidence that the matchresults are correct.
Reports the success or failure of the match attempt.String [79]Status
SuccessNull
FailureF
Reason for failure, if there is one.String [79]Status.Code
• RequestFailed• ServerError• CountryNotFound
27REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponseElement
Description of the problem, if there is one.String [79]Status.Description
This value will appear ifStatus.Code=RequestFailed.
Maximum recordscannot be set to 0.Minimum value shouldbe 1
This value will appear ifStatus.Code=RequestFailed.
Address Not Found
This value will appear ifStatus.Code=ServerError.
Module not licensed
This value will appear ifStatus.Code=CountryNotFound.
Could Not IdentifyCountry
ValidateGlobalAddressValidateGlobalAddress provides enhanced address standardization and validation for addresses outsidethe U.S. and Canada. ValidateGlobalAddress can also validate addresses in the U.S. and Canada butits strength is validation of addresses in other countries. If you need to validate addresses outside theU.S. and Canada, you should consider using ValidateGlobalAddress.
ValidateGlobalAddress is part of the Address Now Module.
Resource URL
JSON endpoint:
http://server:port/rest/ValidateGlobalAddress/results.json
XML endpoint:
http://server:port/rest/ValidateGlobalAddress/results.xml
Resource URL
JSON endpoint:
http://server:port/rest/ValidateAddressGlobal/results.json
XML endpoint:
http://server:port/rest/ValidateAddressGlobal/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/ValidateGlobalAddress/results.json?Data.AddressLine1=1825+Kramer+Ln&Data.City=Austin&Data.StateProvince=TX
The JSON returned by this request would be:
{"output_port": [{"Confidence": "100","AddressLine1": "1825 Kramer Ln","AddressLine2": "Austin TX 78758",
Spectrum Technology Platform 9.028
Address Now Module
"AddressLine3": "","AddressLine4": "","AddressLine5": "","AddressLine6": "","AddressLine7": "","AddressLine8": "","Department": "","Building": "","SubStreet": "","SubCity": "","Principality": "","City": "Austin","StateProvince": "TX","PostalCode": "78758","Country": "United States","FirmName": "","HouseNumber": "1825","StreetName": "Kramer","StreetSuffix": "Ln","ApartmentLabel": "","POBox": "","USCountyName": "Travis","WCRCode": "","URL1": "","URL2": "","Email1": "","Email2": "","ACRCode": "L5-P4S4A0T4R4Z6C4-100","OuterMatchScore": "40","Latitude": "","Longitude": "","ECRCode": "CoBoPeSeXoCeRoPo","PostalCode.Base": "78758","PostalCode.AddOn": "","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/ValidateGlobalAddress/results.xml?Data.AddressLine1=1825+Kramer+Ln&Data.City=Austin&Data.StateProvince=TX
The XML returned by this request would be:
Empty response elements have been removed from this example.Note:
<ns2:xml.ValidateGlobalAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateGlobalAddress">
<ns2:output_port><ns2:Address>
<ns2:Confidence>100</ns2:Confidence><ns2:AddressLine1>1825 Kramer Ln</ns2:AddressLine1><ns2:AddressLine2>Austin TX 78758</ns2:AddressLine2><ns2:City>Austin</ns2:City><ns2:StateProvince>TX</ns2:StateProvince><ns2:PostalCode>78758</ns2:PostalCode><ns2:PostalCode.Base>78758</ns2:PostalCode.Base><ns2:PostalCode.AddOn/><ns2:Country>United States</ns2:Country><ns2:HouseNumber>1825</ns2:HouseNumber><ns2:StreetName>Kramer</ns2:StreetName><ns2:StreetSuffix>Ln</ns2:StreetSuffix><ns2:USCountyName>Travis</ns2:USCountyName><ns2:ACRCode>L5-P4S4A0T4R4Z6C4-100</ns2:ACRCode><ns2:OuterMatchScore>40</ns2:OuterMatchScore><ns2:ECRCode>CoBoPeSeXoCeRoPo</ns2:ECRCode>
29REST Web Services Guide
Chapter 2: Web Services
</ns2:Address></ns2:output_port>
</ns2:xml.ValidateGlobalAddressResponse>
Request
Parameters for Input DataValidateGlobalAddress takes a standard address as input. All addresses use this format no matter whatcountry the address is from.
Table 9: ValidateGlobalAddress Input
DescriptionFormatParameter
First address lineString[79]
Data.AddressLine1
Second address lineString[79]
Data.AddressLine2
Third address lineString[79]
Data.AddressLine3
Fourth address lineString[79]
Data.AddressLine4
Fifth address lineString[79]
Data.AddressLine5
Sixth address lineString[79]
Data.AddressLine5
Seventh address lineString[79]
Data.AddressLine7
Eighth address lineString[79]
Data.AddressLine7
City nameString[79]
Data.City
State or province.String[79]
Data.StateProvince
The postal code for the address. In the U.S. this is the ZIPCode™.
String[79]:
9999999999-9999
Data.PostalCode
A9A9A9A9A 9A99999999
Specify the country using the format you chose for inputcountry format (English name or ISO code). For a list of ISO
String[79]
Data.Country
codes, see Country ISO Codes and Module Support onpage 234.
Spectrum Technology Platform 9.030
Address Now Module
DescriptionFormatParameter
Company or firm nameString[79]
Data.FirmName
Parameters for OptionsInput Data Options
Table 10: ValidateGlobalAddress Input Data Options
DescriptionParameter
Specifies the default country. You should specify the country wheremost of the addresses are located. For example, if most of the addresses
Option.HomeCountry
you process are in Canada, specify Canada. ValidateGlobalAddressuses the home country to attempt validation when it cannot determinethe country from the StateProvince, PostalCode, and Country addressfields. For a list of valid values, see Country ISO Codes and ModuleSupport on page 234.
Output Data Options
Table 11: ValidateGlobalAddress Output Data Options
DescriptionParameter
Specifies the format to use for the country name in the output. One ofthe following:
Option.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
Specifies the casing of the output data. One of the following:Option.OutputCasing
The output in mixed case (default). For example: 123 MainSt Mytown FL 12345
M
The output in upper case. For example: 123 MAIN STMYTOWN FL 12345
U
Specifies whether to use a separator (spaces or hyphens) in ZIP™ Codesor Canadian postal codes.
Option.OutputPostalCodeSeparator
For example, a ZIP + 4® Code with the separator would be 20706-1844and without the separator it would be 207061844. A Canadian postalcode with the separator would be P5E"1S7 and without the separatorit would be P5E1S7.
Yes, use separator (default)Y
No, do not use separatorN
Spaces are used in Canadian postal codes and hyphens inU.S. ZIP + 4® Codes.
Note:
Specifies whether to include the city, state/province, and postal code inone of the AddressLine output fields. Regardless of what you specify
Option.ShowExtraAddressLine
31REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
with this option, the output fields City, State/Province, and PostalCodewill always contain the city, state/province, and postal code.
Yes, include city, state/province, and postal code in anAddressLine output field (default).
Y
No, do not include city, state/province, and postal code in anAddressLine output field.
N
Specifies whether to return a standardized address when an addresscannot be validated. The address is formatted using the preferred
Option.StandardizeAddressOnFail
address format for the address's country. If this option is not selected,the output address component fields (StreetName, HouseNumber, etc.)are blank when address validation fails.
No, do not format failed addresses (default).N
Yes, standardize failed addresses.Y
Specifies whether to return a formatted address when an address cannotbe validated. The address is formatted using the preferred addressformat for the address's country.
Option.FormatOnFail
Yes, return a formatted address when an address cannot bevalidated.
Y
No, do not return a formatted address when an addresscannot be validated (default).
N
Enables address validation. Address validation does the following:Option.ValidateAddress
• Matches components to the relevant country's reference data• Corrects spelling errors• Adds missing components• Corrects or adds postal codes
Yes, validate addresses (default).Y
No, do not validate addresses.N
Formats the address components into the statutory postal or customformats.
Option.FormatAddress
Yes, format addresses (default).Y
No, do not format addresses.N
Standardization Options
Table 12: ValidateGlobalAddress Standardization Options
DescriptionParameter
Specifies whether or not to populate the Department field whenstandardizing an address.
Option.StandardizeComponent.Department
Yes (default)Y
NoN
Specifies whether or not to populate the FirmName field whenstandardizing an address.
Option.StandardizeComponent.FirmName
Yes (default)Y
Spectrum Technology Platform 9.032
Address Now Module
DescriptionParameter
NoN
Specifies whether or not to populate the Building field when standardizingan address.
Option.StandardizeComponent.Building
Yes (default)Y
NoN
Specifies whether or not to populate the SubBuilding field whenstandardizing an address.
Option.StandardizeComponent.SubBuilding
Yes (default)Y
NoN
Specifies whether or not to populate the HouseNumber field whenstandardizing an address.
Option.StandardizeComponent.HouseNumber
Yes (default)Y
NoN
Specifies whether or not to populate the SubStreet field whenstandardizing an address.
Option.StandardizeComponent.SubStreet
Yes (default)Y
NoN
Specifies whether or not to populate the StreetName field whenstandardizing an address.
Option.StandardizeComponent.StreetName
Yes (default)Y
NoN
Specifies whether or not to populate the POBox field when standardizingan address.
Option.StandardizeComponent.POBox
Yes (default)Y
NoN
Specifies whether or not to populate the SubCity field when standardizingan address.
Option.StandardizeComponent.SubCity
Yes (default)Y
NoN
Specifies whether or not to populate the City field when standardizingan address.
Option.StandardizeComponent.City
Yes (default)Y
NoN
Specifies whether or not to populate the USCountyName field whenstandardizing an address.
Option.StandardizeComponent.USCountyName
Yes (default)Y
NoN
Specifies whether or not to populate the StateProvince field whenstandardizing an address.
Option.StandardizeComponent.StateProvince
Yes (default)Y
33REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
NoN
Specifies whether or not to populate the Principality field whenstandardizing an address.
Option.StandardizeComponent.Principality
Yes (default)Y
NoN
Specifies whether or not to populate the PostalCode field whenstandardizing an address.
Option.StandardizeComponent.PostalCode
Yes (default)Y
NoN
Specifies whether or not to populate the +4 field when standardizing anaddress.
Option.StandardizeComponent.Plus4
Yes (default)Y
NoN
Specifies whether or not to populate the Country field when standardizingan address.
Option.StandardizeComponent.Country
Yes (default)Y
NoN
Specifies whether or not to look for vulgar words. If this option is enabled,ValidateGlobalAddress returns a value in the WCRCode output field toindicate the results.
Option.ReportVulgarWords
YesY
No (default)N
Specifies whether or not to mark vulgar words in the output using theformat ">VulgarWord<".
Option.FlagVulgarWords
YesY
No (default)N
This option controls whether or not to include troubleshooting informationin the output fields Email1, Email2, URL1, and URL2.
Option.DebugOutput
YesY
No (default)N
Validation Options
Table 13: ValidateGlobalAddress Validation Options
DescriptionParameter
Specifies whether or not to include the Department field when validatingan address.
Option.ValidateComponent.Department
YesY
No (default)N
Spectrum Technology Platform 9.034
Address Now Module
DescriptionParameter
Specifies whether or not to include the FirmName field when validatingan address.
Option.ValidateComponent.FirmName
YesY
No (default)N
Specifies whether or not to include the Building field when validating anaddress.
Option.ValidateComponent.Building
Yes (default)Y
NoN
Specifies whether or not to include the SubBuilding field when validatingan address.
Option.ValidateComponent.SubBuilding
Yes (default)Y
NoN
Specifies whether or not to include the HouseNumber field whenvalidating an address.
Option.ValidateComponent.HouseNumber
Yes (default)Y
NoN
Specifies whether or not to include the SubStreet field when validatingan address.
Option.ValidateComponent.SubStreet
Yes (default)Y
NoN
Specifies whether or not to include the StreetName field when validatingan address.
Option.ValidateComponent.StreetName
Yes (default)Y
NoN
Specifies whether or not to include the POBox field when validating anaddress.
Option.ValidateComponent.POBox
Yes (default)Y
NoN
Specifies whether or not to include the SubCity field when validating anaddress.
Option.ValidateComponent.SubCity
Yes (default)Y
NoN
Specifies whether or not to include the City field when validating anaddress.
Option.ValidateComponent.City
Yes (default)Y
NoN
35REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Specifies whether or not to include the USCountyName field whenvalidating an address.
Option.ValidateComponent.USCountyName
Yes (default)Y
NoN
Specifies whether or not to include the StateProvince field whenvalidating an address.
Option.ValidateComponent.StateProvince
Yes (default)Y
NoN
Specifies whether or not to include the Principality field when validatingan address.
Option.ValidateComponent.Principality
Yes (default)Y
NoN
Specifies whether or not to include the PostalCode field when validatingan address.
Option.ValidateComponent.PostalCode
Yes (default)Y
NoN
Specifies whether or not to include the +4 field when validating anaddress.
Option.ValidateComponent.Plus4
Yes (default)Y
NoN
Specifies whether or not to include the Country field when validating anaddress.
Option.ValidateComponent.Country
Yes (default)Y
NoN
Specifies whether or not to correct the Country field when validating anaddress.
Option.ForceUpdate.Department
Yes (default)Y
NoN
Specifies whether or not to correct the FirmName field when validatingan address.
Option.ForceUpdate.FirmName
Yes (default)Y
NoN
Specifies whether or not to correct the Building field when validating anaddress.
Option.ForceUpdate.Building
Yes (default)Y
NoN
Spectrum Technology Platform 9.036
Address Now Module
DescriptionParameter
Specifies whether or not to correct the SubBuilding field when validatingan address.
Option.ForceUpdate.SubBuilding
Yes (default)Y
NoN
Specifies whether or not to correct the HouseNumber field whenvalidating an address.
Option.ForceUpdate.HouseNumber
Yes (default)Y
NoN
Specifies whether or not to correct the SubStreet field when validatingan address.
Option.ForceUpdate.SubStreet
Yes (default)Y
NoN
Specifies whether or not to correct the StreetName field when validatingan address.
Option.ForceUpdate.StreetName
Yes (default)Y
NoN
Specifies whether or not to correct the POBox field when validating anaddress.
Option.ForceUpdate.POBox
Yes (default)Y
NoN
Specifies whether or not to correct the SubCity field when validating anaddress.
Option.ForceUpdate.SubCity
Yes (default)Y
NoN
Specifies whether or not to correct the City field when validating anaddress.
Option.ForceUpdate.City
Yes (default)Y
NoN
Specifies whether or not to correct the USCountyName field whenvalidating an address.
Option.ForceUpdate.USCountyName
Yes (default)Y
NoN
Specifies whether or not to correct the StateProvince field whenvalidating an address.
Option.ForceUpdate.StateProvince
Yes (default)Y
NoN
37REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Specifies whether or not to correct the Principality field when validatingan address.
Option.ForceUpdate.Principality
Yes (default)Y
NoN
Specifies whether or not to correct the PostalCode field when validatingan address.
Option.ForceUpdate.PostalCode
Yes (default)Y
NoN
Specifies whether or not to correct the +4 field when validating anaddress.
Option.ForceUpdate.Plus4
Yes (default)Y
NoN
Specifies whether or not to correct the Country field when validating anaddress.
Option.ForceUpdate.Country
Yes (default)Y
NoN
Specifies whether or not to overwrite the Department field if an alias isfound in the Address Now database.
Option.ReplaceAlias.Department
YesY
No (default)N
Specifies whether or not to overwrite the FirmName field if an alias isfound in the Address Now database.
Option.ReplaceAlias.FirmName
YesY
No (default)N
Specifies whether or not to overwrite the Building field if an alias is foundin the Address Now database.
Option.ReplaceAlias.Building
YesY
No (default)N
Specifies whether or not to overwrite the SubBuilding field if an alias isfound in the Address Now database.
Option.ReplaceAlias.SubBuilding
YesY
No (default)N
Specifies whether or not to overwrite the HouseNumber field if an aliasis found in the Address Now database.
Option.ReplaceAlias.HouseNumber
YesY
No (default)N
Spectrum Technology Platform 9.038
Address Now Module
DescriptionParameter
Specifies whether or not to overwrite the SubStreet field if an alias isfound in the Address Now database.
Option.ReplaceAlias.SubStreet
YesY
No (default)N
Specifies whether or not to overwrite the StreetName field if an alias isfound in the Address Now database.
Option.ReplaceAlias.StreetName
YesY
No (default)N
Specifies whether or not to overwrite the POBox field if an alias is foundin the Address Now database.
Option.ReplaceAlias.POBox
YesY
No (default)N
Specifies whether or not to overwrite the Subcity field if an alias is foundin the Address Now database.
Option.ReplaceAlias.SubCity
YesY
No (default)N
Specifies whether or not to overwrite the City field if an alias is found inthe Address Now database.
Option.ReplaceAlias.City
YesY
No (default)N
Specifies whether or not to overwrite the USCountyName field if an aliasis found in the Address Now database.
Option.ReplaceAlias.USCountyName
YesY
No (default)N
Specifies whether or not to overwrite the StateProvince field if an aliasis found in the Address Now database.
Option.ReplaceAlias.StateProvince
YesY
No (default)N
Specifies whether or not to overwrite the Principality field if an alias isfound in the Address Now database.
Option.ReplaceAlias.Principality
YesY
No (default)N
Specifies whether or not to overwrite the PostalCode field if an alias isfound in the Address Now database.
Option.ReplaceAlias.PostalCode
Yes (default)Y
NoN
39REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Specifies whether or not to overwrite the +4 field if an alias is found inthe Address Now database.
Option.ReplaceAlias.Plus4
YesY
No (default)N
Specifies whether or not to overwrite the Country field if an alias is foundin the Address Now database.
Option.ReplaceAlias.Country
YesY
No (default)N
This option, used in conjunction with the "Force Update", ensures thatno major changes are made to the data during processing.
Option.CautiousUpdate
YesY
No (default)N
Specifies whether or not to correct common address standardizationand validation errors by performing cross-component matching.
Option.CrossComponentMatch
Cross-component matching checks for matches between data found inone field in the input data and another field in the Address Now database.
YesY
No (default)N
Specifies whether or not ValidateGlobalAddress modifies the addressto match the diacritics (accents, umlauts, etc.) in the postal database
Option.UseReferenceDiacritics
when the only changes to the address are the diacritics . One of thefollowing:
Yes (default)Y
NoN
For example, ifUseReferenceDiacritics is enabled, the following wouldoccur:
Input City: Chalon-Sur-SaôneCity in the postal database: CHALON SUR SAONEOutput City: CHALON SUR SAONE
Input City: ARTEMIVS'KCity in the postal database: ARTEMIVSKOutput City: ARTEMIVSK
If UseReferenceDiacritics is not enabled, the following would occur:
Input City: Chalon-Sur-SaôneReference City: CHALON SUR SAONEOutput City: Chalon-Sur-Saône
Input City: ARTEMIVS'KReference City: ARTEMIVSKOutput City: ARTEMIVS'K
Note that this option has no effect on the Transliteration option.
Spectrum Technology Platform 9.040
Address Now Module
DescriptionParameter
Specifies whether or not standardization changes such as changing"ROAD" to "RD" should be reported in the ACR code.
Option.KeepStandardizationChanges
YesY
No (default)N
The Acceptance Level setting specifies the minimum number of addresscomponents that must be validated in order for the whole address to be
Option.AcceptanceLevel
considered validated. The value specified for AcceptanceLevelcorresponds to the second character of the ACR code. For moreinformation, see The ACR Code on page 228.
The acceptance level differs from the InnerMatchScore option in thatacceptance level measures how many components Validate GlobalAddress validated, regardless of how well the validated componentsmatched to address components in the postal databases, whereasInnerMatchScore indicates the probability that the output address is thecorrect, validated version of the input address.
One of the following:
The acceptance level is automatically set to an appropriatelevel based on the address's country. For example, U.S.addresses are processed with an acceptance level of 4.
-1
No components validated (default)0
Country only validated1
City and country validated2
City, postal code and country validated3
Street, city, postal code and country validated4
Premise number, building name, sub-building, PO box,company, street, city, postal code, and country validated
5
Specifies the minimum confidence level for address validation.Addresses with a value in the Confidence output field greater than or
Option.InnerMatchScore
equal to this value is validated, and those that have a lower value willnot be validated (the output field Status will contain F.)
Specify any value between 0 and 100. The higher the value, the higherthe degree of confidence necessary for effective address validation.The default is 60.
A whole number from 0 to 10, indicating the relative importance of theFirmName field compared to the data in the Address Now database.
Option.CompanyWeight
This affects the confidence value, and can be used to tailor theconfidence to distinguish correct and incorrect updates. For moreinformation, see The ACR Code on page 228.
The default value is 1.
A whole number from 0 to 10, indicating the relative importance of theStreetName field compared to the data in the Address Now database.
Option.StreetWeight
A whole number from 0 to 10, indicating the relative importance of thisfield compared to the others. For more information, see The ACR Codeon page 228.
41REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
The default value is 10.
A whole number from 0 to 10, indicating the relative importance of theCity field compared to the data in the Address Now database. A whole
Option.CityWeight
number from 0 to 10, indicating the relative importance of this fieldcompared to the others. For more information, see The ACR Code onpage 228.
The default value is 8.
A whole number from 0 to 10, indicating the relative importance of thePostalCode field compared to the data in the Address Now database.
Option.PostcodeWeight
A whole number from 0 to 10, indicating the relative importance of thisfield compared to the others. For more information, see The ACR Codeon page 228.
The default value is 8
A value from 0 to 8 indicating the number of address lines to use whencalculating the outer match score. The default is 8. For more informationon the outer match score, see The Outer Match Score on page 48.
Option.OuterMatchScoreLines
Output Format Options
Table 14: ValidateGlobalAddress Output Format Options
DescriptionParameter
Specifies whether or not the Department field should be included in theoutput of a formatted address.
Option.FormatComponent.Department
Yes (default)Y
NoN
Specifies whether or not the FirmName field should be included in theoutput of a formatted address.
Option.FormatComponent.FirmName
Yes (default)Y
NoN
Specifies whether or not the Building field should be included in theoutput of a formatted address.
Option.FormatComponent.Building
Yes (default)Y
NoN
Specifies whether or not the SubBuilding field should be included in theoutput of a formatted address.
Option.FormatComponent.SubBuilding
Yes (default)Y
NoN
Specifies whether or not the HouseNumber field should be included inthe output of a formatted address.
Option.FormatComponent.HouseNumber
Yes (default)Y
NoN
Spectrum Technology Platform 9.042
Address Now Module
DescriptionParameter
Specifies whether or not the SubStreet field should be included in theoutput of a formatted address.
Option.FormatComponent.SubStreet
Yes (default)Y
NoN
Specifies whether or not the StreetName field should be included in theoutput of a formatted address.
Option.FormatComponent.StreetName
Yes (default)Y
NoN
Specifies whether or not the POBox field should be included in the outputof a formatted address.
Option.FormatComponent.POBox
Yes (default)Y
NoN
Specifies whether or not the SubCity field should be included in theoutput of a formatted address.
Option.FormatComponent.SubCity
Yes (default)Y
NoN
Specifies whether or not the City field should be included in the outputof a formatted address.
Option.FormatComponent.City
Yes (default)Y
NoN
Specifies whether or not the USCountyName field should be includedin the output of a formatted address.
Option.FormatComponent.USCountyName
Yes (default)Y
NoN
Specifies whether or not the StateProvince field should be included inthe output of a formatted address.
Option.FormatComponent.StateProvince
Yes (default)Y
NoN
Specifies whether or not the Principality field should be included in theoutput of a formatted address.
Option.FormatComponent.Principality
Yes (default)Y
NoN
Specifies whether or not the PostalCode field should be included in theoutput of a formatted address.
Option.FormatComponent.PostalCode
Yes (default)Y
NoN
Specifies whether or not the +4 field should be included in the outputof a formatted address.
Option.FormatComponent.Plus4
Yes (default)Y
NoN
43REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Specifies whether or not the Country field should be included in theoutput of a formatted address.
Option.FormatComponent.Country
YesY
No (default)N
Specifies how to format diacritics in the output address. One of thefollowing:
Option.Transliteration
No transliteration is performed. Diacritic characters are left asspecified in the input and/or postal database. Default.
0
Diacritic characters are removed and replaced with theequivalent unadorned character.
1
Diacritic characters are transliterated to an equivalent unadornedcharacter or character sequence using language-specifictransliteration rules.
2
For example, the following shows the effect of each of the threetransliteration options on a Swedish address. Note the differences in"Västra Frölunda".
0
Gustaf Wernersgata 12 S-42132 Västra Frölunda
1
Gustaf Wernersgata 12 S-42132 Vastra Frolunda
2
Gustaf Wernersgata 12 S-42132 Vaestra Froelunda
Response
Address Data Output
Table 15: ValidateGlobalAddress Address Data Output
DescriptionFormatResponse Element
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
Spectrum Technology Platform 9.044
Address Now Module
DescriptionFormatResponse Element
The formatted eighth address line.String[79]
AddressLine8
Apartment designator (such as STE or APT). For example:String[79]
ApartmentLabel
123 E Main St. APT 3
Apartment number. For example:String[79]
ApartmentNumber
123 E Main St. APT 3
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 ofISO codes, see Country ISO Codes and Module Supporton page 234.
String[79]
Country
A subdivision of a country used in French and Spanishspeaking countries. For example, France is divided into 100departments.
String[79]
Department
The name of a company. For example:String[79]
FirmName
Pitney Bowes Software4200 PARLIAMENT PLSTE 600LANHAM MD 20706-1844USA
House number. For example:String[79]
HouseNumber
123 E Main St. Apt 3
The most precise latitude that could be determined for theaddress. This could be a point level location or a centroid.
String[79]
Latitude
The level of precision can be determined by looking at theECRCode output field. For more information, see The ECRCode on page 47.
The most precise longitude that could be determined for theaddress. This could be a point level location or a centroid.
String[79]
Longitude
The level of precision can be determined by looking at theECRCode output field. For more information, see The ECRCode on page 47.
The post office box number. If the address is a rural routeaddress, the rural route box number will appear here.
String[79]
POBox
The postal code. In the U.S. this is the ZIP Code™.String[79]
PostalCode
The 4-digit add-on part of the ZIP + 4® Code. For example,in the ZIP Code™ 60655-1844, 1844 is the 4-digit add-on.(U.S. addresses only.)
String[79]
PostalCode.AddOn
The 5-digit ZIP Code™. For example 20706 (U.S. addressesonly.)
String[79]
PostalCode.Base
An area within a country. For example, England, Scotland,and Wales are principalities. This field will normally be blank.
String[79]
Principality
45REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponse Element
The state or province abbreviation.String[79]
StateProvince
Street name. For example:String[79]
StreetName
123 E Main St. Apt 3
Street suffix. For example:String[79]
StreetSuffix
123 E Main St. Apt 3
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
27 Crystal WayBradley StokeBristol BS32 8GA
In this case, "Bradley Stoke" is the 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
12 The MewsHigh Street
In this example, "High Street" is the substreet. Substreets canbe used to precisely identify the delivery location. In theexample, "The Mews" may be a small street that needsanother street identification to properly locate the address,so "High Street" is included. In this case, "High Street" is themain or known street.
For U.S. addresses, the name of the county where theaddress is located.
String[79]
USCountyName
Return Codes
Table 16: ValidateGlobalAddress Return Codes
DescriptionFormatResponse Element
The Address Correction Result (ACR) code describes whatdata has been changed in each record. For information onwhat this code means, see The ACR Code on page 228.
String[79]
ACRCode
The level of confidence assigned to the address beingreturned. Range is from zero (0) to 100; zero indicates failure,
String[79]
Confidence
100 indicates a very high level of confidence that the matchresults are correct. This value is the same as the last threedigits of the ACR code, referred to as the validation matchscore. For more information, see The ACR Code on page228.
The Enhanced Correction Result (ECR) code describes thelevel of precision of the latitude and longitude returned for the
String[79]
ECRCode
address. For mroe information, see The ECR Code on page47.
Spectrum Technology Platform 9.046
Address Now Module
DescriptionFormatResponse Element
Extra standardization information.String[79]
Email1
Extra standardization information.String[79]
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.
Extra standardization information.String[79]
URL1
Extra standardization information.String[79]
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
47REST Web Services Guide
Chapter 2: Web Services
• 2—City centroid• 1—Region centroid
The body of the code identifies the components that were used to match the address to a geocode. Notethat the body consists of letters and numerals. Here's what they mean:
• P—Premise/house number, building or PO box• S—Street• T—City• R—Region/state• Z—Postal code• C—Country
There are only two numeric options in the body: 4 or 0
• 4—The component data was available to make the geocode-address match.• 0—The component date was not available.
For example: EL4-P0S4T4R4Z4C4
In this example, the 0 following the P tells us that premise/house number data was not available to makethis address match; everything from street to country, however, was used in the assignment.
The Outer Match ScoreThe outer match score indicates howmuch ValidateGlobalAddress changed each address line to validatethe address. The score compares the address lines before standardization and after validation andformatting. This score is only generated if you set the option to a value greater than 0.
The outer match score is similar to the validation match score, which is part of the ACR code (see TheACR Code on page 228). The difference is that the outer match scoremeasures any change to an addressline, including formatting, whereas the validation match score measures only whether or not the datacould be validated,
For example, take the following input address lines before processing:
Address Line 1: 5 camden cresAddress Line 2: bathAddress Line 3: uk
After processing the address lines are:
Address Line 1: 5 Camden CrescentAddress Line 2: BathAddress Line 3: BA1 5HYAddress Line 4: United Kingdom
This has a validation match score of 84% and in outer match score of 23%.
The validationmatch score is high because the address components were fairly accurate before validation.The street name was valid except for casing and use of an abbreviation. The city and country were bothvalid. The only thing not correct was the postal code (in this case it was missing). Hence the relativelyhigh validation match score of 84%.
The outer match score is low because after formatting, the address lines are considerably different fromthe input. In this case, Address Line 3 contained "uk" on input, and contains "BA1 5HY" on output. Line4 was empty on input, and in populated on output. Address line 1 has also changed. The outer score istherefore quite low.
Spectrum Technology Platform 9.048
Address Now Module
Enterprise Routing Module
GetTravelBoundaryGetTravelBoundary determines a drive or walk time or distance boundary from a location. This featureobtains polygons corresponding to an isochrone or isodistance calculation. An isochrone is a polygonor set of points representing an area that can be traversed in a network from a starting point in a givenamount of time. An isodistance is a polygon or set of points representing the area that is a certain distancefrom the starting point. The Get Travel Boundary operation (also known as an iso definition) takes astarting point, a unit (linear or time), one or more costs and their associated tags as input and returnsthe resulting travel boundary. Cost refers to the amount of time or distance to use in calculating an iso.A tag is a string that identifies the cost and is used to match the corresponding result.
GetTravelBoundary is part of the Enterprise Routing Module.
GetTravelBoundary is only available as a web service. The Get Travel Boundary is not availablethrough the Java, C++, C, .NET, or COM APIs.
Note:
Resource URL
JSON endpoint:
http://server:port/rest/GetTravelBoundary/results.json
XML endpoint:
http://server:port/rest/GetTravelBoundary/results.xml
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
},
49REST Web Services Guide
Chapter 2: Web Services
{"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:
Some of the points have been removed from this example to shorten it.Note:
<ns3:xml.GetTravelBoundaryResponsexmlns:ns2="http://www.mapinfo.com/midev/service/geometries/v1"xmlns:ns3="http://www.pb.com/spectrum/services/GetTravelBoundary">
<ns3:output_port><ns3:IsoRouteResponse>
<ns3:IsoNodeResponse/><ns3:IsoPolygonResponse
xsi:type="ns2:MultiPolygon"srsName="epsg:4326"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:Polygon srsName="epsg:4326"><ns2:Exterior>
<ns2:LineString><ns2:Pos>
Spectrum Technology Platform 9.050
Enterprise Routing Module
<ns2:X>-84.34868168466456</ns2:X><ns2:Y>33.68373169496257</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.36945064055561</ns2:X><ns2:Y>33.69293307108579</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.3694506405556</ns2:X><ns2:Y>33.69293307108579</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.3694506405556</ns2:X><ns2:Y>33.69303002973829</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.37104825254721</ns2:X><ns2:Y>33.69391558543121</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.37104825254721</ns2:X><ns2:Y>33.6936408692491</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.42163929894845</ns2:X><ns2:Y>33.716054477754355</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.4440058668311</ns2:X><ns2:Y>33.710741143596806</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.43921303085625</ns2:X><ns2:Y>33.72800947960886</ns2:Y>
</ns2:Pos><ns2:Pos>
<ns2:X>-84.45678676276404</ns2:X><ns2:Y>33.73376559161287</ns2:Y>
</ns2:Pos>...
</ns2:LineString></ns2:Exterior>
</ns2:Polygon></ns3:IsoPolygonResponse><ns3:user_fields/>
</ns3:IsoRouteResponse></ns3:output_port>
</ns3:xml.GetTravelBoundaryResponse>
Request
Parameters for Input DataGetTravelBoundary takes cost, cost unit, point latitude, and point longitude as input. The following tableprovides information on the format and layout of the input.
Table 17: GetTravelBoundary Input Data
DescriptionFormatParameter
Latitude of the point. Specify latitude in the formatchosen in the Option.CoordinateFormat parameter.
StringData.Latitude
51REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatParameter
Longitude of the point. Specify longitude in theformat chosen in the Option.CoordinateFormatparameter.
StringData.Longitude
(Optional) The cost distance or time, in the unitsspecified by either the
StringData.TravelBoundaryCost
Data.TravelBoundaryCostUnits parameter or theOption.DefaultTravelBoundaryCostUnits parameter.For example, if the unit specified is miles and youspecify 10 in this field, the cost would be 10 miles.
Use this field to override the default travel boundarycost on a record-by-record basis.
(Optional) The type of metric used to calculate thetravel boundary. One of the following:
StringData.TravelBoundaryCostUnits
• Feet• Hours• Kilometers• Meters• Miles• Minutes• Seconds• Yards
Use this field to override the default travel boundarycost units on a record-by-record basis.
Parameters for OptionsInput Options
Table 18: GetTravelBoundary Input Options
DescriptionParameter
The name of the database that contains the data to use in the search process.Use the database name specified in the Enterprise Routing Module Routing
Option.DataSetResourceName
Database Resource tool. For more information, see the Spectrum™
Technology Platform Administration Guide.
The coordinate system of the input coordinates. The format must be theEuropean Petroleum Survey Group (EPSG) code, the SRID code, or the
Option.CoordinateSystem
MAPINFO code. Specify the coordinate reference system in the formatcodespace:code. For example, a geometry in Latitude/Longitude (WGS84) would be EPSG:4326. The default value is EPSG:4326, which is alsoknown as Latitude/Longitude (WGS 84). This is a worldwide system and isthe terrestrial reference frame associated with the NAVSTAR GlobalPositioning System (GPS) used extensively for navigation and surveying.This datum is earth-centered ("geocentric") and defined with satellite andterrestrial data.
The following table lists some of the more widely used EPSG codes:
Spectrum Technology Platform 9.052
Enterprise Routing Module
DescriptionParameter
EPSG CodeCoordinate System
4322Longitude/Latitude (WGS 72)
4326Longitude/Latitude (WGS 84)
4269Longitude/Latitude (NAD 83)
4277Longitude/Latitude (OSGB 36)
27700British National Grid
Specifies the format of latitude/longitude coordinates in the input.Option.CoordinateFormat
Use this option only if you specify a Latitude/Longitude coordinatesystem. If the coordinate system is not a Latitude/Longitudecoordinate system, set the coordinate format to Decimal.
Note:
One of the following:
(90.000000, 180.000000)Decimal
(90000000, 180000000). Default.DecimalAssumed
(90 00 00N, 180 00 00W)DegreesMinutesSeconds
(090000000N, 180000000W)PreZero
(090.000000N, 180.000000W)PreZeroDecimal
Number of cost units. The default is 10.Option.DefaultTravelBoundaryCost
Type of metric you want to use to calculate the travel boundary. One of thefollowing:
Option.DefaultTravelBoundaryCostUnits
• Feet• Hours• Kilometers• Meters• Miles• Minutes• Seconds• Yards
Output Options
Table 19: GetTravelBoundary Output Options
DescriptionParameter
Specifies the type of result you want returned. One of the following:Option.ResultType
Returns the entire isoChrone.AccessibleNodes
Returns all of the points along the road networkthat can be reached for the isoChronecalculation.
Geometry
53REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Returns the location specified by the enteredaddress.
StartNodes
Specifies what percentage of the original points should be returned orupon which the resulting polygon should be based.
Option.SimplificationFactor
Specifies the style of banding to be used in the result. Banding stylesare the types of multiple isoChrone or distance bands that can bedisplayed based on multiple costs.
Option.BandingStyle
Each boundary is determined by subtractingout the next smallest boundary.
Donut
Each boundary is determined independentof all others.
EncompassingEncompassing
Specifies whether you want to return holes, which are areas within thelarger boundary that cannot be reached within the desired time ordistance, based on the road network.
Option.ReturnHoles
Yes, return holes.Y
Do not return holes. Default.N
Specifies whether you want to return islands, which are small areasoutside the main boundary that can be reached within the desired timeor distance.
Option.ReturnIslands
Yes, return islands.Y
Do not return islands. Default.N
Travel Options
Travel options specify assumptions to make about travel speed off network roads and whether to useonly major roads when calculating the travel boundary. Most travel options have to do with ambientspeed.
Table 20: GetTravelBoundary Travel Options
DescriptionParameter
Specifies the maximum distance to allow travel off the roadnetwork. Examples of off-network roads include driveways
Option.MaximumOffRoadDistance
and access roads. For example, if you specify a maximumoff road distance of 1 mile the travel boundary will extend nofurther than one mile from the network road. If you specify avalue of 0 the travel boundary will not extend beyond the roaditself. Use the ambient speed options to specify the speed oftravel along non-network roads.
The units of measure in which you want the data returned.One of the following:
Option.Units
• Kilometer (default)• Meter• Mile
Spectrum Technology Platform 9.054
Enterprise Routing Module
DescriptionParameter
Specifies whether to include all roads in the calculation or justmajor roads. If you choose to include only major roads,performance will improve but accuracy may decrease.
Option.MajorRoads
This map represents a travel boundary with travel allowed onall roads:
This map represents a travel boundary with travel restrictedto major roads only:
One of the following:
Include only major roads in the calculation. Default.Y
Include all roads in the calculation.N
55REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Specifies the speed to travel when going off a network roadto find the travel boundary. Examples of off-network travelinclude driveways and access roads.
Option.DefaultAmbientSpeed
This option is available only when you specify a time valuein the Option.DefaultCostUnits parameter or theData.TravelBoundaryCostUnits parameter. The default is 15.Specify the speed units in the Option.AmbientSpeedUnitparameter.
To control how off-network travel is used in the travelboundary calculation, you need to specify the speed of traveloff the road network (the ambient speed). Ambient speed canaffect the size and shape of the travel boundary polygon. Ingeneral, the faster the ambient speed, the larger the polygon.For example, if you were at a point with 5 minutes left, and ifthe ambient speed were 15 miles per hour, boundary pointswould be put at a distance of 1.25 miles. If the ambient speedwere reduced to 10 miles per hour, boundary points wouldbe put at a distance of 0.83 miles. Note that you can limit thedistance allowed off a network road by using the theOption.MaximumOffRoadDistance parameter.
If you are calculating pedestrian travel boundarieswe recommend that you change the default ambientspeed to 3 MPH (5 KPH).
Note:
The unit of measure to use with the value specified in theOption.DefaultAmbientSpeed parameter.
Option.AmbientSpeedUnit
Kilometers per hour.KPH
MILES per hour. Default.MPH
Meters per second.MTPS
Specifies the ambient speed to use for off-network travelbased on the road type. If you do not specify an ambient
Option.AmbientSpeed.RoadType.<Type>
speed for a road type, the default ambient speed will be used,as specified in the Option.DefaultAmbientSpeed parameter.
The following map shows an example of a travel boundarywithout ambient speed overrides:
Spectrum Technology Platform 9.056
Enterprise Routing Module
DescriptionParameter
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
57REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
• 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
DescriptionFormatResponse Element
Reports the success or failure of the match attempt.StringStatus
Spectrum Technology Platform 9.058
Enterprise Routing Module
DescriptionFormatResponse Element
Successnull
FailureF
Reason for failure, if there is one. One of the following:StringStatus.Code
• InsufficientInputData (missing lat/lon)• MalformedInputData (wrong input format)• InputOutOfRange (input is out of range)• EngineError (engine-generated error)
Description of failure indicated in Status.Code.StringStatus.Description
GetTravelCostMatrixGetTravelCostMatrix calculates the travel time and distances between an array of start and end locations.You can use GetTravelCostMatrix to find the shortest or fastest paths between a number of start pointsand a number of end points, and determine the total time and distance of the individual routes (the routecosts). For example if you input four start points (S1 through S4) and four end points (E1 through E4),a total of 16 routes will be returned as illustrated in the following diagram:
Matrix routing is often used to determine service response time and coverages for specific services suchas a fire house or police station. You may require these calculations to ensure they can provide adequatecoverage for service level agreements such as having one or more people who can respond to an incidentwithin 20 minutes of first notification. The calculation can be used an analysis tool to determine the riskof an insured property or person based on the probability that ambulance, public safety, or fire personnelcan reach the property/person in a reasonable amount of time.
Get Travel Cost Matrix is only available as a SOAP web service. Get Travel Cost Matrix is notavailable through REST. It is also not available through the Java, C++, C, .NET, or COM APIs.
Note:
GetTravelCostMatrix is part of the Enterprise Routing Module.
GetTravelDirectionsGetTravelDirections returns routing information for a set of two distinct points or for multiple points. Ittakes a starting latitude and longitude point and an ending latitude and longitude point as input andreturns the route that is either fastest or shortest, depending on how you configure the stage.
Each country has its own database, named in this format: Enterprise Routing Module - <Country>. Eachdatabase also has its own country code. For example, the name of the Austrian database is "EnterpriseRouting Module - Austria," and the Austrian batch country code is "A1T." Each database requires aseparate license.
Get Travel Directions is only available as a SOAP web service. Get Travel Directions is notavailable through REST. It is also not available through the Java, C++, C, .NET, or COM APIs.
Note:
GetTravelDirections is part of the Enterprise Routing Module.
59REST Web Services Guide
Chapter 2: Web Services
Enterprise Tax Module
AssignGeoTAXInfoAssignGeoTAXInfo identifies the tax districts that apply to a given address. Specifically, AssignGeoTAXInforeturns this information about an address:
• Latitude/longitude• FIPS state codes and county codes• County names• MCD/CCD codes and names• Place codes and names• Incorporated or unincorporated status codes• Cross-reference tax keys• Result indicators• Optionally, the relationship of an address to user-defined polygons
AssignGeoTAXInfo optionally includes enhanced tax jurisdiction information for an address, including:
• Insurance premium districts—Areas designated for the collection of taxes imposed on insurancepolicy premiums, based on the policy holder's address. Insurance premium districts are created bystate governments.
• Payroll tax districts—Areas designated for the collection of taxes imposed on employers to supportstate or local government facilities and services, based on the employee's and/or employer's address.Examples include taxes collected for districts to pay for schools, police, or other services. Payroll taxdistricts are created by state or local governments.
• Payroll system tax codes—Codes that represent specific jurisdictions that collect payroll tax. Usingpayroll system tax codes has advantages over using the payroll tax district information returned byAssign GeoTAX Info:
• AssignGeoTAXInfo uses an additional database to determine payroll tax codes, resulting in moreaccurate payroll tax determination.
• Many payroll systems use specific codes to determine withholding amounts. Since you can customizethe payroll tax codes returned by AssignGeoTAXInfo, you can set up a process whereAssignGeoTAXInfo returns the exact payroll tax codes required by your payroll system, instead ofreturning jurisdictional IDs that must then be translated into the codes used by your system.
• Property tax districts—Areas designated for the collection of taxes imposed on property owners tosupport local government facilities and services, based on the property's location. Examples includetaxes collected for districts to pay for schools, police, or other services. Property tax districts are createdby local governments.
• Special purpose tax districts—Areas designated for the collection of taxes imposed on residents tosupport specialized services for residents of the district, based on the resident's address. Examplesinclude services such as sewer service, transit service, or water resources. Special purpose tax districtsare created by legislative action, court action, or public referendums. This optional information requiresthe use of boundary files which require an additional license. Contact your Pitney Bowes Softwaresales representative for more information.
AssignGeoTAXInfo is part of the Enterprise Tax Module.
Resource URL
JSON endpoint:
http://server:port/rest/AssignGeoTaxInfo/results.json
Spectrum Technology Platform 9.060
Enterprise Tax Module
XML endpoint:
http://server:port/rest/AssignGeoTaxInfo/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/AssignGeoTAXInfo/results.json?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY&Data.PostalCode=12180
The JSON returned by this request would be:
{"output_port": [{"Confidence": "100.0","ProcessedBy": "GTX","Census.MatchCode": "S","Census.MatchLevel": "Street","Census.BlockCode": "1","Census.Tract": "052301","County.Code": "083","County.Name": "Rensselaer","StateCode": "36","MCD.Code": "52100","MCD.Name": "North Greenbush","MSA.Code": "0160","MSA.Name": "Albany-Schenectady-Troy Ny","LatLong": "042.683028N073.702969W","LatLong.MatchCode": "R","LatLong.MatchLevel": "Rooftop","LatLong.StreetMatchCode": " ","LatLong.StreetMatchLevel": "","Latitude": "042.683028","Latitude.Directional": "N","Longitude": "073.702969","Longitude.Directional": "W","GeoTAXKey.MatchCode": " ","GeoTAXKey.MatchLevel": "NoMatch","GeoTAXKey": "","State.Abbreviation": "NY","Place.ClassCode": "","Place.Code": "00000","Place.IncorporatedFlag": "Unknown","Place.Name": "","Place.LastAnnexedDate": "","Place.LastUpdatedDate": "","Place.LastVerifiedDate": "","AuxiliaryData.AuxiliaryFile": "","AuxiliaryData.StateFile": "","AddressLine1": "1 Global View","City": "Troy","StateProvince": "NY","PostalCode": "12180","Place.PostalCodeConfidence": " ","County.PostalCodeConfidence": " ","GNISCode": "000000000","NumberUserBoundariesFound": "00","PTC.MatchCode": " ","NumberPTCsFound": "0","StateCounty": "","GTX.ErrorCode": "","GTX.ErrorDescription": "","GTX.WarnCode": "","GTX.WarnDescription": "","user_fields": []
}]}
61REST Web Services Guide
Chapter 2: Web Services
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/AssignGeoTAXInfo/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY&Data.PostalCode=12180
The XML returned by this request would be:
<ns2:xml.AssignGeoTAXInfoResponsexmlns:ns2="http://www.pb.com/spectrum/services/AssignGeoTAXInfo">
<ns2:output_port><ns2:Address>
<ns2:Confidence>100.0</ns2:Confidence><ns2:ProcessedBy>GTX</ns2:ProcessedBy><ns2:Census.MatchCode>S</ns2:Census.MatchCode><ns2:Census.MatchLevel>Street</ns2:Census.MatchLevel><ns2:Census.BlockCode>1</ns2:Census.BlockCode><ns2:Census.Tract>052301</ns2:Census.Tract><ns2:County.Code>083</ns2:County.Code><ns2:County.Name>Rensselaer</ns2:County.Name><ns2:StateCode>36</ns2:StateCode><ns2:MCD.Code>52100</ns2:MCD.Code><ns2:MCD.Name>North Greenbush</ns2:MCD.Name><ns2:MSA.Code>0160</ns2:MSA.Code><ns2:MSA.Name>Albany-Schenectady-Troy Ny</ns2:MSA.Name><ns2:LatLong>042.683028N073.702969W</ns2:LatLong><ns2:LatLong.MatchCode>R</ns2:LatLong.MatchCode><ns2:LatLong.MatchLevel>Rooftop</ns2:LatLong.MatchLevel><ns2:LatLong.StreetMatchCode/><ns2:LatLong.StreetMatchLevel/><ns2:Latitude>042.683028</ns2:Latitude><ns2:Latitude.Directional>N</ns2:Latitude.Directional><ns2:Longitude>073.702969</ns2:Longitude><ns2:Longitude.Directional>W</ns2:Longitude.Directional>
</ns2:Address></ns2:output_port>
</ns2:xml.AssignGeoTAXInfoResponse>
Request
Parameters for Input DataThe following table provides information on the format of AssignGeoTAXInfo input.
Table 22: AssignGeoTAXInfo Input Data
DescriptionFormatParameter
First address lineString[100]
Data.AddressLine1
Second address lineString[100]
Data.AddressLine2
Third address lineString[100]
Data.AddressLine2
Fourth address lineString[100]
Data.AddressLine4
Specifies the width of the polygon buffers to use for BoundaryFile processing. The buffer width is used to determine if a
String[10]
Data.BufferWidth
Spectrum Technology Platform 9.062
Enterprise Tax Module
DescriptionFormatParameter
point is close to the edge of a polygon. The output fieldBufferRelation indicates whether or not the point is within thepolygon's buffer area. For more information, see Bufferingon page 232.
This field overrides the value specified in theOption.DefaultBufferWidth parameter. Specify the borderwidth in the units specified by the Option.DistanceUnitsparameter.
If you do not specify a buffer width in this input field, thedefault is used.
City nameString[50]
Data.City
The country where the address resides. The data you enterin this field has no impact on processing. It is simply passedthrough to output.
String[var]
Data.Country
AssignGeoTAXInfo only supports US addresses.Note:
Company or firm nameString[var]
Data.FirmName
Nine-digit ZIP CodeString [9]Data.PostalCode
The state where the address resides. The data you enter inthis field has no impact on processing. It is simply passedthrough to output.
String[50]
Data.StateProvince
Specifies the width of the polygon buffers to use forUser-Defined Boundary File processing. The buffer width is
Long[10]
Data.UseBufferWidth
used to determine if a point is close to the edge of a polygon.The output field BufferRelation indicates whether or not thepoint is within the polygon's buffer area. For more information,see Buffering on page 232.
This field overrides the value specified in theOption.DefaultBufferWidth parameter. Specify the borderwidth in the units specified by the Option.DistanceUnitsparameter.
If you do not specify a buffer width in this input field, thedefault is used.
Parameters for OptionsData
Data options control the data returned by AssignGeoTAXInfo. Table 23: AssignGeoTAXInfo DataOptions on page 64 lists the output data options.
63REST Web Services Guide
Chapter 2: Web Services
Table 23: AssignGeoTAXInfo Data Options
DescriptionParameter
The name of the database resource that contains the data to use in thesearch process. Use the database name specified in the Management
Option.Database.GTX
Console's Database Resources tool. For more information, see theSpectrum™ Technology Platform Administration Guide.
Specifies whether or not AssignGeoTAXInfo should attempt a match tothe street level data.
Option.UseStreetLevelMatching
Yes, use the street matcher (default).Y
No, do not use the street matcher.N
Specifies whether or not AssignGeoTAXInfo should attempt a match tothe GeoTAX Auxiliary file. The GeoTAX Auxiliary file contains newaddresses that have not yet been added to the Master File.
Option.UseGeoTaxAuxiliaryFile
Because matching to the GeoTAX Auxiliary file involves street-levelmatching, you must specify Option.UseStreetLevelMatching=Y in orderfor this option to work.
Yes, attempt to match to GeoTAX Auxiliary file (default).Y
No, do not use the GeoTAX Auxiliary file.N
Specifies whether or not AssignGeoTAXInfo should attempt a match toa User Auxiliary file. User Auxiliary files are user-defined files that the
Option.UseAuxiliaryFile
Enterprise Tax Module uses to override results from the master files instreet-level matching.
Because matching to the User Auxiliary file involves street-levelmatching, you must specify Option.UseStreetLevelMatching=Y in orderfor this option to work.
Yes, attempt to match to User Auxiliary file.Y
No, do not use the User Auxiliary file (default).N
Specifies whether or not AssignGeoTAXInfo should attempt a match tothe state-supplied file. Use this option in combination withFileSearchOrder to specify a state-supplied file to use.
Option.UseStateProvidedFile
State-supplied files are provided by individual state governments. Bymatching to the state-supplied files, you can remain compliant with taxjurisdiction assignment requirements mandated by new federal andstate laws, such as the Mobile Telecommunications Sourcing Act andthe Florida state Communications Services Tax Simplification Law.
There are two supported file formats: the Florida-native format and thenational TS-158 format (ANSI Transaction Set No. 158). The state ofFlorida provides address files in both the TS-158 and its own nativeformat. The state of Washington provides address data in the TS-158format.
Assign GeoTAX Info attempts to match to the state supplied file first. Ifa state match cannot be found, it attempts a match to the master files.
You must install the appropriate state-supplied file to use these options.For instructions, see the Spectrum™ Technology Platform InstallationGuide.
Spectrum Technology Platform 9.064
Enterprise Tax Module
DescriptionParameter
One of the following:
Yes, attempt to match to state-supplied file.Y
Do not use the state-supplied file (default).N
Specifies which state-supplied file to use. This option only takes effectif you specify Option.UseStateProvidedFile=Y. One of the following:
Option.FileSearchOrder
Use only the Florida-native formatted file.FLOnly
Use only the TS-158 formatted file.TSOnly
Specifies whether or not AssignGeoTAXInfo matches input addresseswith secondary information to records without secondary information.This option applies only to Florida-native files. One of the following:
Option.UseRelaxedSecondaryMatching
Yes, use relaxed matching.Y
No, do not use relaxed matching (default).N
Select one or more of the following to obtain the type of data you wantreturned. AssignGeoTAXInfo groups the output fields into record types.
Option.GeoTAXOutputRecordType
If you do not want all of the fields in a record type returned, do not selectthe check box, and list only those fields you want returned in ExtraOutput Fields.
• C—Census• L—Latitude/Longitude• T—Tax Jurisdiction• U—User-defined boundary file• W—Payroll System Tax Codes• X—Auxiliary File
You can also specify one, and only one, of the following:
Insurance Premium Tax District (IPD)I
Property Tax District (PTD)P
Payroll Tax District (PAY)R
Special Purpose Tax District (SPD)S
For a description of the fields in each output group, see Response onpage 68.
If you specify W, to obtain the best payroll system tax codematch possible.
Note:
If you integrate AssignGeoTAXInfo with third-party tax compliancesoftware from Vertex or ADP/Taxware, select which vendor you use.
Option.TaxKey
This controls the value returned in the GeoTAXKey output field. One ofthe following:
Return the Taxware jurisdiction code for the address.T
Return the Vertex jurisdiction code for the address. Select thisoption if you obtained a MatchMaster file from Vertex.
Y
65REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Return the Vertex jurisdiction code for the address. Select thisoption if you obtained a Vertex file from Pitney BowesSoftware.
V
Do not return either the Taxware or Vertex jurisdiction codes(default).
N
Indicates the individual output fields you want returned. You can usethis field instead of the Output Record Type to limit the output to thosefields that are important to your current data needs.
Option.OutputFields
For a list of the fields included in each data type, see Response onpage 68.
Specifying Default State-Supplied File Options
If you use the Spectrum™ Technology Platform API, note that the value you specify in the ManagementConsole for the State supplied file field controls the default settings for three AssignGeoTAXInfo APIoptions: UseStateProvidedFile, UseRelaxedSecondary, and FileSearchOrder. The following table showhow each value in the State supplied file field affects these three options.
UseRelaxedSecondaryFileSearchOrderUseStateProvidedFile"State supplied file" value
NN/ANNone
NFSOnlyYFlorida-native
YFSOnlyYFlorida-native with relaxedsecondary matching
NTSOnlyYTS-158
Geocoding
Geocoding is the process of determining the latitude/longitude coordinates of a given address. Addresscoordinates are used as the basis for determining the tax jurisdictions for an address. Geocoding optionscontrol how AssignGeoTAXInfo determines address latitude and longitude.
Table 24: AssignGeoTAXInfo Geocoding Options
DescriptionParameter
Indicates the offset distance in feet from the street center line.Option.LatLongOffset
The offset distance is used in street-level geocoding to prevent thegeocode from being in the middle of a street. It compensates for thefact that street-level geocoding returns a latitude and longitude point inthe center of the street where the address is located. Since the buildingrepresented by an address is not on the street itself, you do not wantthe geocode for an address to be a point on the street. Instead, youwant the geocode to represent the location of the building which sitsnext to the street. For example, an offset of 50 feet means that thegeocode will represent a point 50 feet back from the center of the street.The distance is calculated perpendicular to the portion of the streetsegment for the address. Offset is also used to prevent addresses across
Spectrum Technology Platform 9.066
Enterprise Tax Module
DescriptionParameter
the street from each other from being given the same point. The followingdiagram shows an offset point in relation to the original point.
No offset (default).0
Twenty feet offset from street center line20
Forty feet offset from street center line40
Sixty feet offset from street center line60
Specifies if AssignGeoTAXInfo should squeeze the street end pointswhen determining the geocode of an address in street-level matching.
Option.Squeeze
The squeeze value is 5% (2.5% from each endpoint). The followingdiagram compares the end points of a street segment to the squeezedend points of a street segment.
No, do not apply squeeze.N
Apply squeeze (default).Y
Indicates the desired format for returned latitude/longitude. Optionsinclude:
Option.LatLongFormat
Latitude/longitude in the following format:090000000N180000000W. (Default)
PreZero
Latitude/longitude in the following format:090.000000N180.000000W.
PreZeroDecimal
Latitude/longitude in the following format:90.000000-180.000000.
Decimal
Latitude/longitude in the following format:90000000-180000000.
DecimalAssumed
Latitude/longitude in the following format: 90 0000N180 00 00W.
DegMinSec
Specifies the units in which to measure distance. One of the following:Option.DistanceUnits
67REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Distances are measured in miles.Miles
Distances are measured in kilometers.Km
Distances are measured in feet. (Default)Feet
Distances are measured in meters.Meters
Specifies the buffer width to use for tax district boundary files. The taxdistrict boundary files are the Special Purpose District (SPD) file, the
Option.DefaultBufferWidth
Insurance Premium District (IPD) file, the Payroll Tax District (PAY) fileand the Personal Property Tax District (PTD) file.
Specify the distance in the units of measurement specified in theDistanceUnits option.
The default buffer width that you specify here can be overridden on arecord-by-record basis using the BufferWidth input field.
For more information on buffers, see Buffering on page 232.
Specifies the buffer width to use for user-defined boundary files. Specifythe distance in the units of measurement specified in theDistanceUnits
Option.DefaultUserBufferWidth
option. For information on buffers, see Buffering on page 232. Thedefault buffer width that you specify here can be overridden on arecord-by-record basis using the BufferWidth input field.
To use buffers, the user-defined boundary file must supportbuffers.
Note:
Output Format
Output format options control how AssignGeoTAXInfo formats output data. The following table lists theoutput format options.
Table 25: AssignGeoTAXInfo Output Format Options
DescriptionParameter
Specifies the casing of these output fields: County.Name, MSA.Name,MCD.Name, Place.Name, IPDn.DistrictName, PAYn.DistrictName,SPDn.DistrictName, and PTCn.PayrollDescription.
Option.OutputCasing
One of the following:
The output in mixed case (default). For example:Rensselaer.
M
The output in upper case. For example: RENSSELAER.U
Response
Auxiliary FileThe following table lists the output fields that contain auxiliary file data. To include auxiliary file data inthe output, set GeoTAXOutputRecordType = X. The following table lists the output fields that containtax jurisdiction data.
Spectrum Technology Platform 9.068
Enterprise Tax Module
Table 26: Auxiliary File Output Fields
DescriptionResponse Element
Data retrieved as a result of an auxiliary match from the user-definedarea of the auxiliary file.
AuxiliaryData.AuxiliaryFile
Data retrieved as a result of a state match. Data content and formatvary depending on the state file used.
AuxiliaryData.StateFile
CensusThe census output fields contains census information from the U.S. Census, including Minor Civil Divisions(MCDs) and Census County Division (CCD) names and codes. MCDs are the primary political oradministrative divisions of a county, representing many kinds of legal entities with a variety of governmentaland administrative functions. CCDs are established in states where there are no legally establishedMCDs. The Census Bureau recognizes MCDs in 28 states and has established CCDs in 21 states. TheDistrict of Columbia has no primary divisions, and the city of Washington, DC is considered equivalentto an MCD for data presentation purposes.
Census data also contains the Federal Information Processing Standards (FIPS) codes for each stateand county. The FIPS State Code and the FIPS County Code are both used by the Census Bureau toidentify these geographic units.
The following table lists the output fields that contain census data. To include census data in the output,set GeoTAXOutputRecordType = C.
Table 27: Census Data Output Fields
DescriptionResponse Element
Census Block Group code.Census.BlockCode
The level of match obtained against the databases.Census.MatchCode
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Auxiliary street matchA
State file address matchG
Street address matchS
GeoTAX Auxiliary file matchU
ZIP + 4 Code level match9
ZIP Code level match5
Unsuccessful matchnull
The level of match obtained against the databases.Census.MatchLevel
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Auxiliary street matchAuxiliary
GeoTAX Auxiliary file matchAux2
69REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Street address matchStreet
State file address matchGov
ZIP + 4 Code level matchZIP+4
ZIP Code level matchZIP
No matchnull
Six-digit tract number extracted from the Census.BlockCode.Census.Tract
Three-digit Federal Information Processing Standards (FIPS) countycode extracted from the Census.BlockCode.
County.Code
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Name of the county.County.Name
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Unique nine-digit Geographic Names Information System (GNIS) code.GNISCode
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Minor Civil Division/Census County Division (MCD/CCD) Code.MCD.Code
Minor Civil Division/Census County Division (MCD/CCD) name.MCD.Name
Metropolitan Statistical area (MSA) code.MSA.Code
Metropolitan Statistical area (MSA) name.MSA.Name
Two-character state abbreviation.State.Abbreviation
This field is always included in the output regardless of whetheror not you choose to include census data in the output
Note:
Two-digit Federal Information Processing Standards (FIPS) state codeextracted from the Census.BlockCode.
StateCode
This field is always included in the output regardless of whetheror not you choose to include census data in the output.
Note:
Input AddressAssignGeoTAXInfo always returns the input address as part of the output. The input address fields arereturned as input from the data. AssignGeoTAXInfo does not change these input values.
Table 28: Input Address Output Fields
DescriptionResponse Element
Input address line 1.AddressLine1
Spectrum Technology Platform 9.070
Enterprise Tax Module
DescriptionResponse Element
Input address line 2.AddressLine2
Input address line 3.AddressLine3
Input address line 4.AddressLine4
Input address city.City
Input address country.Country
Input address firm name.FirmName
Input address postal codePostalCode
Input address state.StateProvince
Insurance Premium Tax DistrictThe following table lists the output fields that contain Insurance Premium Tax District (IPD) data. Formore information on insurance premium tax districts, see AssignGeoTAXInfo on page 60. To includecensus data in the output, set GeoTAXOutputRecordType = I.
AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.Note:
Table 29: Insurance Premium Tax District Output Fields
DescriptionResponse Element
Indicates where in the district the address residesin relation to the edge of the district.
IPDn.BoundaryBuffer.BufferRelation
One of the following:
The address is inside the district at a distancefrom the edge that is greater than the
P
specified buffer width. Buffer width is specifiedeither by the option or by the input fieldBufferWidth.
The address is inside the district but is closeto the edge. This indicates that the address
I
is in the buffer area specified either by theoption or by the input field BufferWidth.
The address is outside the district but is closeto the edge. This indicates that the address
B
is in the buffer area specified either by theoption or by the input field BufferWidth.
For more information, see Buffering on page 232.
Indicates the distance from the address to theborder of the district. The distance is in the unitsspecified by the option .
IPDn.BoundaryBuffer.DistanceToBorder
IPD ID.IPDn.DistrictID
IPD name.IPDn.DistrictName
71REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
IPD district type.IPDn.DistrictType
IPD update date.IPDn.UpdateDate
IPD compiled date.IPDn.VersionDate
Tax code descriptions.IPDn.Notes
Field Length: 20
Possible Values: 01, 33, A, B
IPD change date.IPDn.ChangeDate
MMDDYY - Identifies when district becomes active- State supplied
IPDn.EffectiveDate
Field Length: 6
Possible Values: 010108
MMDDYY - Identifies when district becomesinactive - State supplied
IPDn.ExpirationDate
Field Length: 6
Possible Values: 063009
Format is dependent on associated flagIPDn.FireRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.FireFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semi colon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.CasualtyRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.CasualtyFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.VehicleRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.VehicleFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.MarineRate
Spectrum Technology Platform 9.072
Enterprise Tax Module
DescriptionResponse Element
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.MarineFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.HealthRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.HealthFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.LifeRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.LifeFlag
P - Percentage; .1 = 10%, .0575 = 5.75%
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.OtherRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.OtherFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Format is dependent on associated flagIPDn.MinimumRate
Field Length: 20
Possible Values: .13, 15.00 or 3;7
P - Percentage; .1 = 10%, .0575 = 5.75%IPDn.MinimumFlag
F - Flat Fee dollar amount
M - Multiple Percentages has a semicolon as adelimiter. 3;7 = "3% or 7%"
Number of IPDs returned.NumberIPDsFound
73REST Web Services Guide
Chapter 2: Web Services
Latitude/LongitudeThe following table lists the output fields that contain latitude and longitude data. Latitude/Longitude datacontains the coordinates for the address and additional information about how AssignGeoTAXInfodetermined the latitude and longitude. To include latitude/longitude data in the output, setGeoTAXOutputRecordType = L.
Table 30: Latitude/Longitude Output Fields
DescriptionResponse Element
Seven-digit number in degrees and calculated to four decimal places(in the format you specified).
Latitude
Latitude directional.Latitude.Directional
NorthN
SouthS
Returned latitude/longitude, in the format you specified (up to 22alphanumeric characters).
LatLong
Level of match for the latitude/longitude.LatLong.MatchCode
ZIP + 2 centroid2
ZIP + 4 Code centroid4
ZIP Code centroid based on a ZIP + 4 code.5
Block group centroidB
Address-level based on street addressR
Census tract centroidT
Address-level match using the GeoTAX AuxiliaryDatabase
U
ZIP Code centroid based on a five-digit ZIP codeZ
No latitude/longitude determinednull
Level of match for the latitude/longitude.LatLong.MatchLevel
Block group centroidBlock
Exact address matchRooftop
Census tract centroidTract
ZIP Code centroidZIP
ZIP + 2 centroidZIP+2
ZIP + 4 centroidZIP+4
Address-level match using the GeoTAXAuxiliary Database
Auxiliary
Output street address return code.LatLong.StreetMatchCode
House number not found on streetH
Latitude/longitude not determined on auxiliary matchL
Spectrum Technology Platform 9.074
Enterprise Tax Module
DescriptionResponse Element
Street not found in ZIP CodeS
ZIP Code not found in street address databaseZ
Street-level matching option not selectedN
The street was successfully matchednull
Street level match used to determine the latitude/longitude.LatLong.StreetMatchLevel
Successful matchFullMatch
House number not found on streetHouseNotFound
Latitude/longitude not determined onauxiliary match
LatLongNotFound
Street not found in ZIP CodeStreetNotFound
ZIP Code not found in street addressdatabase
ZipNotFound
Street-level matching option not selectedNotUsed
Seven-digit number in degrees and calculated to four decimal places(in the format specified).
Longitude
Longitude directional.Longitude.Directional
EastE
WestW
Payroll System Tax CodeThe following table lists the output fields that contain Payroll System Tax Code (PTC) data. For moreinformation on payroll tax districts, see AssignGeoTAXInfo on page 60. To include this data in theoutput, set GeoTAXOutputRecordType = W.
AssignGeoTAXInfo returns up to six payroll tax codes per address.Note:
Table 31: Payroll System Tax Code Output Fields
DescriptionResponse Element
Number of payroll system tax codes found for this address.NumberPTCsFound
Indicates the level of match obtained for the address. In order frommostspecific match to least, the possible match codes are:
PTC.MatchCode
The address was matched to a specific Payroll District ID.This is the most specific match.
P
The address was matched to a GNIS Code.G
The address was matched to a county's FIPS code.F
The address was matched to a state's FIPS code. This is theleast specific match.
S
75REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
A code that represents a taxing authority in a payroll application. Thisis a user-defined code. The specific codes are determined by the payrollapplication that utilizes the data returned by AssignGeoTAXInfo.
PTCn.PayrollCode
A description of the purpose of this payroll code.PTCn.PayrollDescription
A user-defined flag from the PTC database.PTCn.PayrollFlag
The state abbreviation and county name.StateCounty
Payroll Tax DistrictThe following table lists the output fields that contain Payroll Tax District (PAY) data. For more informationon payroll tax districts, see AssignGeoTAXInfo on page 60. To include this data in the output, setGeoTAXOutputRecordType = R.
AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.Note:
Table 32: Payroll Tax District Output Fields
DescriptionResponse Element
Number of PAYs returned.NumberPAYsFound
Indicates where in the district the address resides in relationto the edge of the district.
PAYn.BoundaryBuffer.BufferRelation
One of the following:
The address is inside the district at a distance from theedge that is greater than the specified buffer width.
P
Buffer width is specified either by the option or by theinput field BufferWidth.
The address is inside the district but is close to theedge. This indicates that the address is in the buffer
I
area specified either by the option or by the input fieldBufferWidth.
The address is outside the district but is close to theedge. This indicates that the address is in the buffer
B
area specified either by the option or by the input fieldBufferWidth.
For more information, see Buffering on page 232.
Indicates the distance from the address to the border of thedistrict. The distance is in the units specified by the option.
PAYn.BoundaryBuffer.DistanceToBorder
PAY district ID.PAYn.DistrictID
PAY district name.PAYn.DistrictName
PAY district type.PAYn.DistrictType
PAY ID.PAYn.ID
PAY municipality emergency municipal services tax.PAYn.MunicipalEMSTax
Spectrum Technology Platform 9.076
Enterprise Tax Module
DescriptionResponse Element
The values for Pennsylvania are:
Levies the taxY
Does not levy the taxN
All other states are null.
PAY municipality income tax.PAYn.MunicipalIncomeTax
The values for Pennsylvania are:
ResidentR
Non-residentN
BothB
NoneX
All other states are null.
PAY school district emergency municipal services tax.PAYn.SchoolDistrictEMSTax
The Values for Pennsylvania are:
Levies the taxY
Does not levy the taxN
All other states are null.
PAY school district income tax.PAYn.SchoolDistrictIncomeTax
The values for Pennsylvania are:
ResidentR
Non-residentN
BothB
NX
The values for Ohio are:
ResidentR
NoneX
All other states are null.
Property Tax DistrictThe following table lists the output fields that contain Property Tax District (PTD) data. For more informationon property tax districts, see AssignGeoTAXInfo on page 60. To include this data in the output, setGeoTAXOutputRecordType = P.
AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.Note:
77REST Web Services Guide
Chapter 2: Web Services
Table 33: Property Tax District Output Fields
DescriptionResponse Element
Number of PTDs returned.NumberPTDsFound
Indicates where in the district the address resides in relationto the edge of the district.
PTDn.BoundaryBuffer.BufferRelation
One of the following:
The address is inside the district at a distance from theedge that is greater than the specified buffer width.
P
Buffer width is specified either by the option or by theinput field BufferWidth.
The address is inside the district but is close to theedge. This indicates that the address is in the buffer
I
area specified either by the option or by the input fieldBufferWidth.
The address is outside the district but is close to theedge. This indicates that the address is in the buffer
B
area specified either by the option or by the input fieldBufferWidth.
For more information, see Buffering on page 232.
Indicates the distance from the address to the border of thedistrict. The distance is in the units specified by the option.
PTDn.BoundaryBuffer.DistanceToBorder
PTD district ID.PTDn.DistrictID
PTD district name.PTDn.DistrictName
PTD district type. Only returned for Indiana.PTDn.DistrictType
Reporting districtR
Billing districtB
PTD jurisdiction ID.PTDn.JurisdictionID
PTD update date.PTDn.UpdateDate
Result IndicatorsThe following table lists the output fields that contain results data. Result indicators describe how wellAssignGeoTAXInfo matched the input address to a known address and assigned a location. These fieldsare always included in output from AssignGeoTAXInfo.
Table 34: Result Indicator Output Fields
DescriptionResponse Element
Indicates the confidence in the output provided; from 0 to 100. Thehigher the score, the higher the confidence in the match. Calculated
Confidence
based on the match results for individual output fields, using the followingalgorithm:
Spectrum Technology Platform 9.078
Enterprise Tax Module
DescriptionResponse Element
Census.MatchCode + Latlong.StreetMatchCode + LatLong.MatchCode
The maximum confidence score is 100, so if this calculation results ina value greater than 100, the Confidence score is returned as 100.
AssignGeoTAXInfo uses the following values:
• Census.MatchCode
• A = 85• G = 85• S = 85• U = 85• 9 = 65• 5 = 45• null = 0
• LatLong.StreetMatchCode
• H = 5• S = 0• L = 0• Z = -10• null = 10
• LatLong.MatchCode
• 2 = 0• 4 = 5• 5 = -5• B = 2• R = 10• T = -2• U = 10• Z = -5• null = -10
This field contains a return code if the GeoTAX engine experiences anabnormal termination.
GTX.ErrorCode
This field contains the same set of codes returned by thestandalone GeoTAX software and is intended for users who
Note:
have migrated from GeoTAX to Spectrum™ TechnologyPlatform.
The first character indicates the file (or set of files affected).
Auxiliary fileA
Base fileB
Boundary fileD
User defined boundary fileF
Street fileG
Logical I/O program abendL
79REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
State supplied filesS
GeoTAX Auxiliary fileU
Street and state filesX
The second position is one of the following:
Both Florida and TS158 state files are problematicE
Expired databaseF
InformationalI
If the GeoTAX engine experiences an abnormal termination, this fieldcontains a text description of the reason. It is blank if GeoTAX terminatednormally. The maximum length is 80.
GTX.ErrorDescription
This field contains the same set of descriptions returned by thestandalone GeoTAX software and is intended for users who
Note:
have migrated from GeoTAX to Spectrum™ TechnologyPlatform.
SI-"TS158 FILES NOT FOUND"SI-"TS158 FILES VINTAGE OR INCOMPLETE DB ERROR"SI-"STATE FILES NOT FOUND"SE-"STATE AND TS158 FILES NOT FOUND"SE-"STATE NOT FOUND AND TS158 VINTAGE ERROR"SI-"STATE FILES VINTAGE OR INCOMPLETE DB ERROR"SE-"STATE VINTAGE ERROR AND TS158 NOT FOUND"SE-"STATE AND TS158 FILES VINTAGE OR INCOMPLETE DBERROR"GI-"STREET FILES NOT FOUND"XI-"STREET AND TS158 FILES NOT FOUND"XI-"STREET NOT FOUND AND TS158 FILES VINTAGE ERROR"XI-"STREET AND STATE FILES NOT FOUND"XE-"STREET STATE AND TS158 FILES NOT FOUND"XE-"STREET AND STATE NOT FOUND AND TS158 VINTAGEERROR"XI-"STREET NOT FOUND AND STATE VINTAGE ERROR"XE-"STREET AND TS158 NOT FOUND AND STATE VINTAGEERROR"XE-"STREET NOT FOUND AND STATE AND TS158 VINTAGEERROR"GI-"STREET FILES VINTAGE OR INCOMPLETE DB ERROR"XI-"STREET VINTAGE ERROR AND TS158 NOT FOUND"XI-"STREET AND TS158 FILES VINTAGE OR INCOMPLETE DBERROR"XI-"STREET VINTAGE ERROR AND STATE NOT FOUND"XE-"STREET VINTAGE ERROR AND STATE AND TS158 NOTFOUND"XE-"STREET AND TS158 VINTAGE ERROR AND STATE NOTFOUND"XI-"STREET AND STATE FILES VINTAGE OR INCOMPLETE DBERROR"XE-"STREET AND STATE VINTAGE ERROR AND TS158 NOTFOUND"
Spectrum Technology Platform 9.080
Enterprise Tax Module
DescriptionResponse Element
XE-"STREET STATE AND TS158 VINTAGE ERROR"LF-"INVALID FUNCTION PASSED TO GTDBLIO : "AI-"GENIO ERROR: FILE = G1GTAUX , FUNC = , ST = "UI-"GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST = "XF-"The (DB Vintage) database has expired!"XF-"The (SPD file Vintage) SPD File has expired!"DI- "UNABLE TO VALIDATE BOUNDARY LICENSE"DI- "UNABLE TO OPEN BOUNDARY FILE"DI- "BOUNDARY FILE NOT FOUND"FI- "UNABLE TO VALIDATE USER BOUNDARY LICENSE"FI- "UNABLE TO OPEN USER BND FILE"FI- "USER BND FILE NOT FOUND"
This field contains warning codes returned by the GeoTAX engine. It isblank if no warnings were issued. A value of WN indicates a databasewill expire next month.
GTX.WarnCode
This field contains the same set of codes returned by thestandalone GeoTAX software and is intended for users who
Note:
have migrated from GeoTAX to Spectrum™ TechnologyPlatform.
A text description of any warnings returned by the GeoTAX engine.GTX.WarnDescription
This field contains the same set of descriptions returned by thestandalone GeoTAX software and is intended for users who
Note:
have migrated from GeoTAX to Spectrum™ TechnologyPlatform.
Reports the success or failure of the match attempt.Status
Successnull
Failure. Some examples of failures are your license expiredor you did not select any output record types and fields forAssignGeoTAXInfo to return.
F
If AssignGeoTAXInfo could not process the address, this field will showthe reason. Currently there is one possible value for this field: InvalidAddress.
Status.Code
If AssignGeoTAXInfo could not process the address, this field will showa description of the failure. One of the following:
Status.Description
TS158 FILES NOT FOUNDTS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTATE FILES NOT FOUNDSTATE AND TS158 FILES NOT FOUNDSTATE NOT FOUND AND TS158 VINTAGE ERRORSTATE FILES VINTAGE OR INCOMPLETE DB ERRORSTATE VINTAGE ERROR AND TS158 NOT FOUNDSTATE AND TS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTREET FILES NOT FOUNDSTREET AND TS158 FILES NOT FOUNDSTREET NOT FOUND AND TS158 FILES VINTAGE ERRORSTREET AND STATE FILES NOT FOUNDSTREET STATE AND TS158 FILES NOT FOUND
81REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
STREET AND STATE NOT FOUND AND TS158 VINTAGE ERRORSTREET NOT FOUND AND STATE VINTAGE ERRORSTREET AND TS158 NOT FOUND AND STATE VINTAGE ERRORSTREET NOT FOUND AND STATE AND TS158 VINTAGE ERRORSTREET FILES VINTAGE OR INCOMPLETE DB ERRORSTREET VINTAGE ERROR AND TS158 NOT FOUNDSTREET AND TS158 FILES VINTAGE OR INCOMPLETE DB ERRORSTREET VINTAGE ERROR AND STATE NOT FOUNDSTREET VINTAGE ERROR AND STATE AND TS158 NOT FOUNDSTREET AND TS158 VINTAGE ERROR AND STATE NOT FOUNDSTREET AND STATE FILES VINTAGE OR INCOMPLETE DB ERRORSTREET AND STATE VINTAGE ERROR AND TS158 NOT FOUNDSTREET STATE AND TS158 VINTAGE ERRORINVALID FUNCTION PASSED TO GTDBLIO :GENIO ERROR: FILE = G1GTAUX , FUNC = , ST =GENIO ERROR: FILE = G1GTAX2 , FUNC = , ST =The (DB Vintage) database has expired!The (SPD file Vintage) SPD File has expired!UNABLE TO VALIDATE BOUNDARY LICENSEUNABLE TO OPEN BOUNDARY FILEBOUNDARY FILE NOT FOUNDUNABLE TO VALIDATE USER BOUNDARY LICENSEUNABLE TO OPEN USER BND FILEUSER BND FILE NOT FOUND
Special Purpose Tax DistrictThe following table lists the output fields that contain Special Purpose Tax District (SPD) data. For moreinformation on special purpose tax districts, see AssignGeoTAXInfo on page 60. To include this datain the output, set GeoTAXOutputRecordType = S.
AssignGeoTAXInfo returns multiple districts for IPDs, SPDs, PTDs, and PAYs.Note:
Table 35: Special Purpose Tax District Output Fields
DescriptionResponse Element
Number of SPDs returned.NumberSPDsFound
Indicates where in the district the address resides in relationto the edge of the district.
SPDn.BoundaryBuffer.BufferRelation
One of the following:
The address is inside the district at a distance from theedge that is greater than the specified buffer width.
P
Buffer width is specified either by the option or by theinput field BufferWidth.
The address is inside the district but is close to theedge. This indicates that the address is in the buffer
I
area specified either by the option or by the input fieldBufferWidth.
Spectrum Technology Platform 9.082
Enterprise Tax Module
DescriptionResponse Element
The address is outside the district but is close to theedge. This indicates that the address is in the buffer
B
area specified either by the option or by the input fieldBufferWidth.
For more information, see Buffering on page 232.
Indicates the distance from the address to the border of thedistrict. The distance is in the units specified by the option.
SPDn.BoundaryBuffer.DistanceToBorder
SPD compiled date.SPDn.CompiledDate
3-digit district type code.SPDn.DistrictCode
SPD name.SPDn.DistrictName
SPD district number.SPDn.DistrictNumber
SPD effective date.SPDn.EffectiveDate
SPD update date.SPDn.UpdateDate
SPD version date.SPDn.VersionDate
Tax JurisdictionTax jurisdiction data contains information about the "place" where the address resides. A "place" is ageographic area defined on the basis of population criteria that vary by state; or, an area recognized assignificant because it is located in an incorporated municipality. Places are used to determine taxjurisdiction.
The following table lists the output fields that contain tax jurisdiction data. To include tax jurisdiction datain the output, set GeoTAXOutputRecordType = T.
Table 36: Tax Jurisdiction Output Fields
DescriptionResponse Element
Indicates if the ZIP Code resides in the county.County.PostalCodeConfidence This field is always included in the output regardless of whether
or not you choose to include tax jurisdiction data in the output.Note:
ZIP Code not wholly contained in the county.N
ZIP Code wholly contained in the county.Y
Unknown if ZIP Code is wholly contained in the county ora match was not made at the ZIP Code level.
null
Only available for 5-digit ZIP Code matches, not for streetaddress matches.
Note:
The value in this field varies depending on the option you specified inthe option:
GeoTAXKey
83REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
If you specified , GeoTAXKey contains the proprietary codes used inADP/Taxware tax compliance software. You can use this code in yourADP/Taxware application to find out the tax rate for the jurisdiction.
If you specified , GeoTAXKey contains the proprietary Vertex® jurisdictioncode (comprised of a two-digit Vertex® state code, three-digit FIPScounty code, and four-digit Vertex® city code). You can use this codein your Vertex® application to find out the tax rate for the jurisdiction.
Return code denoting the level of match obtained against the Vertex orTaxware cross reference files.
GeoTAXKey.MatchCode
Exact match using five fields: FIPS state code, FIPS countycode, FIPS place code, ZIP Code, and FIPS place name.
E
Partial match using four fields: FIPS state code, FIPS countycode, FIPS place code, and ZIP Code.
P
Alternate match using two fields: ZIP Code, FIPS place name.This return code is available only when using Vertex.
A
Record is default coded based on valid state code. This returncode is available only when using Vertex.
N
No matching record found.null
A description of the value returned in the GeoTAXKey.MatchCode field.GeoTAXKey.MatchLevel
Exact match. See description inGeoTAXKey.MatchCode.
Exact
Partial match. See description inGeoTAXKey.MatchCode.
Partial
Alternate match. See description inGeoTAXKey.MatchCode.
Alternate
Record is default coded. See description inGeoTAXKey.MatchCode.
DefaultCode
No matching record found.NoMatch
Place class code. Place class codes are used to determine the propertaxing jurisdictions
Place.ClassCode
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
An identifier for a specific place. A "place" is a geographic area definedon the basis of population criteria that vary by state. Or, an area
Place.Code
recognized as significant because it is located in an incorporatedmunicipality.
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
Indicates whether the address is located in an incorporated orunincorporated place. A "place" is a geographic area defined on the
Place.IncorporatedFlag
basis of population criteria that vary by state. Or, an area recognizedas significant because it is located in an incorporated municipality.
Spectrum Technology Platform 9.084
Enterprise Tax Module
DescriptionResponse Element
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
Incorporated place code.Inc
Unincorporated place code.Uninc
Incorporation status unknown.Unknown
Last annexed date, in the format MM/YYYY, representing the monthand year of the most recent boundary change or the most recentavailable boundary information.
Place.LastAnnexedDate
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
Last updated date, in the format MM/YYYY, reflecting the month andyear when TomTom updated the database to reflect attribute (namechange, FIPS change, etc.) or boundary edits to the Place.
Place.LastUpdatedDate
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
Last verified date, in the format MM/YYYY, representing the month andyear that TomTom verified municipality change information.
Place.LastVerifiedDate
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
The name of the "place" where the address is located. A "place" is ageographic area defined on the basis of population criteria that vary by
Place.Name
state. Or, an area recognized as significant because it is located in anincorporated municipality.
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
Indicates if the ZIP Code resides in the place.Place.PostalCodeConfidence
This field is always included in the output regardless of whetheror not you choose to include tax jurisdiction data in the output.
Note:
ZIP Code not wholly contained in the place.N
ZIP Code wholly contained in the place.Y
Unknown if the ZIP Code is wholly contained in the placeor a match was not made at the ZIP Code level.
null
Only available for five-digit ZIP Code matches, not for street addressmatches.
User-Defined Boundary FileThe following table lists the output fields that contain data returned from user-defined boundary files. Toinclude this data in the output, set GeoTAXOutputRecordType = U.
AssignGeoTAXInfo can return up to 10 user-defined areas for each input address.Note:
85REST Web Services Guide
Chapter 2: Web Services
Table 37: Output Fields for User-Defined Boundary Files
DescriptionResponse Element
Number of user-defined polygons returned.NumberUserBoundariesFound
A description of the polygon.UserBoundaryn.BoundaryDescription
The ID of the polygon as specified in the user-definedboundary file.
UserBoundaryn.BoundaryID
Indicates where in the polygon the address resides in relationto the edge of the area.
UserBoundaryn.BufferRelation
One of the following:
The address is inside the polygon at a distance fromthe edge that is greater than the specified buffer width.
P
Buffer width is specified either by the option or by theinput field BufferWidth.
The address is inside the polygon but is close to theedge. This indicates that the address is in the buffer
I
area specified either by the option or by the input fieldBufferWidth.
The address is outside the polygon but is close to theedge. This indicates that the address is in the buffer
B
area specified either by the option or by the input fieldBufferWidth.
For more information, see Buffering on page 232.
Indicates the distance from the address to the border of thepolygon. The distance is in the units specified by the option.
UserBoundaryn.DistanceToBorder
A supplemental ID as specified in the user-defined boundaryfile.
UserBoundaryn.SupplementalBoundaryID
CalculateDistanceCalculateDistance takes two sets of latitude/longitude coordinates as input, calculates the distancebetween the coordinates, and returns the distance between the two points.
CalculateDistance is part of the Enterprise Tax Module.
Resource URL
JSON endpoint:
http://server:port/rest/CalculateDistance/results.json
XML endpoint:
http://server:port/rest/CalculateDistance/results.xml
Spectrum Technology Platform 9.086
Enterprise Tax Module
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/CalculateDistance/results.json?Data.SecondLatitude=41.881833&Option.LatLongFormat=Decimal&Data.SecondLongitude=-87.785587&Data.FirstLatitude=41.857333&Data.FirstLongitude=-88.325183
The JSON returned by this request would be:
{"output_port": [{"Distance": "27.799","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/CalculateDistance/results.xml?Data.SecondLatitude=41.881833&Option.LatLongFormat=Decimal&Data.SecondLongitude=-87.785587&Data.FirstLatitude=41.857333&Data.FirstLongitude=-88.325183
The XML returned by this request would be:
<ns2:xml.CalculateDistanceResponsexmlns:ns2="http://www.pb.com/spectrum/services/CalculateDistance">
<ns2:output_port><ns2:Result>
<ns2:Distance>27.799</ns2:Distance><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.CalculateDistanceResponse>
Request
Parameters for Input DataCalculateDistance takes latitude and longitude information as input.
Table 38: CalculateDistance Input Data
DescriptionParameter
Latitude of the first point for which you want distance returned.Data.FirstLatitude
First latitude directional.Data.FirstLatitude.Directional
NorthN
SouthS
Longitude of the first point for which you want distance returned.Data.FirstLongitude
First longitude directional.Data.FirstLongitude.Directional
EastE
WestW
87REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Latitude of the second point for which you want distance returned.Data.SecondLatitude
Second latitude directional.Data.SecondLatitude.Directional
NorthN
SouthS
Longitude of the second point for which you want distance returned.Data.SecondLongitude
Second longitude directional.Data.SecondLongitude.Directional
EastE
WestW
Parameters for Options
Table 39: Output Data and Format Options
DescriptionParameter
Indicates the format of the input latitude/longitude. The options are:Option.LatLongFormat
For example 90 00 00N180 00 00W.DegMinSec
(090000000N180000000W). Default.PreZero
(090.000000N180.000000W)PreZeroDecimal
(90.000000-180.000000)Decimal
(90000000-180000000)DecimalAssumed
Indicates the measurement units returned for distance calculation:Option.ReturnUnits
• Miles• Km• Feet• Meters
ResponseCalculateDistance always returns the Confidence field to indicate the confidence in the output provided.
If CalculateDistance fails to process the data, it returns the fields Status, Status.Code, andStatus.Descriptions. These fields provide information on why CalculateDistance failed to process thedata. Some examples of failures are your license expired or you did not select any output record typesand fields for CalculateDistance to return. The following table provides the record-level qualifiers anddata outputs for CalculateDistance.
Spectrum Technology Platform 9.088
Enterprise Tax Module
Table 40: CalculateDistance Output Fields
DescriptionResponse Element
Distance between the two input coordinates in the units of measurementthat you specified.
Distance
Reports the success or failure of the match attempt:Status
Successnull
FailureF
Reason for failure or error. If Status = F, Status.Code = Failure.Status.Code
Description of the problem. If Status = F, Status.Description = Unableto compute distance.
Status.Description
GeoConfidence Module
GeoConfidenceSurfaceGeoConfidenceSurface returns geoconfidence polygons (also called surfaces) based on the quality ofthe geocode information generated by the Enterprise Geocoding Module. With the geoconfidencepolygons generated, you can then overlap this polygon with other spatial data to determine a risk orprobability.
This service is used by the GeoConfidence Module's FloodZoneAnalysis dataflow template.
GeoConfidence uses services provided by the Enterprise Geocoding and Location Intelligencemodules.
Note:
Resource URL
JSON endpoint:
http://server:port/rest/GeoConfidenceSurface/results.json
XML endpoint:
http://server:port/rest/GeoConfidenceSurface/results.xml
RequestThe input fields for GeoConfidenceSurface are the output fields returned by the GeoConfidence outputcategory of the Enterprise Geocoding Module. These fields are described below.
DescriptionResponse Element
The value returned in this field indicates whichgeoconfidence surface type has been returned.
GeoConfidenceCode
Possible values are:
89REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
A geocode point for the intersectionof two streets.
INTERSECTION
An array of street segment pointsrepresenting the street segmentwhere the address is located.
ADDRESS
If the geocoder was able to match theaddress using point data, the point
POINT
geometry where the address islocated.
A geocode point for the ZIP centroid.POSTAL1
An array of points for all streetsegments in the ZIP + 2 in which theaddress is located.
POSTAL2
An array of points for street segmentsin the ZIP + 4 in which the address islocated.
POSTAL3
An error has occurred.ERROR
An array of latitude/longitude values that represent thestreet segment points.
StreetSegmentPoints
This field contains values only if theGeoConfidenceCode field returns a value ofADDRESS, POSTAL2, or POSTAL3.
Note:
The latitude of the centroid of the geoconfidencepolygon.
GeoConfidenceCentroidLatitude
The longitude of the centroid of the geoconfidencepolygon.
GeoConfidenceCentroidLongitude
ResponseThe GeoConfidenceSurface output field contains the geoconfidence polygon.
DescriptionResponse Element
A geoconfidence polygon that represents the returned geometry.Geometry
Global Sentry Module
GlobalSentryThe GlobalSentry service attempts to match transactions against government provided watch lists thatcontain data from various countries. The GlobalSentry service relies on the Universal Name, Data
Spectrum Technology Platform 9.090
Global Sentry Module
Normalization, and Advanced Matching modules. The service provides pre-configured and optimizedrules for matching against the normalized and consolidated watch lists. These lists include the following:
• Denied Persons List (United States)• Unverified List (BIS Red Flag) (United States)• Consolidated Financial Sanction Targets (Individuals and Entities) (United Kingdom/European Union)• Consolidated lists of persons, groups, and entities subject to EU financial sanctions (European Union)• DFAT Consolidated List (Australia)• OSFI Consolidated List (Individuals and Entities) (Canada)• Specially Designated Nationals, Terrorists, Narcotic Traffickers and other Blocked Persons List (UnitedStates)
• Statutorily Debarred Parties List (United States)
Matches are performed against Sanctioned Countries, Name, Address, ID Number and other informationsuch as DOB to provide an "Overall Risk Level Score" that allows your organization to make the rightchoice before making a decision to block a particular transaction and avoid false positive results.
The following steps describe how Global Sentry processes data:
1. The service first scans all required data in the transaction to identify countries that have beensanctioned. If a sanction country match has been identified, the transaction bypasses all othermatching criteria and is assigned the highest possible risk score.
2. If a sanctioned country match has not been identified, the service then attempts to match thetransaction against the Global Sentry database using the Global Sentry Name Check, Global SentryAddress Check or Global Sentry ID Number Check subflows.
3. The Global Sentry Name Check attempts to match individuals, entities and vessels. If a name matchis identified a Name Score is returned from the service.
4. The Global Sentry Address Check attempts to match addresses within a country. If an Address matchis identified an Address Score is returned from the service.
5. The Global Sentry ID Number Check attempts to match identification numbers such as Passport,National ID, SSN, Fiscal Code, and so on. If an ID Number match is identified an ID Number Scoreis returned from the service.
6. If a transaction is not identified as a Name, Address or ID Number match, the transaction record iswritten to the output and given an overall risk level score of zero.
7. If a transaction has been identified as a Name, Address or Identification Number match, the serviceattempts to match those transactions against the Global Sentry database using the Global SentryOther Data Check subflow.
8. The Global Sentry Other Data Check attempts to match the Place of Birth, Date of Birth, Nationalityor Citizenship. If a match is identified a Place of Birth Score, Date of Birth Score, Nationality Scoreor Citizenship Score is returned by the service.
9. Global Sentry assigns an Overall Risk Level score to each transaction. The score is a value between0 and 16 and is returned in the OverallRiskLevel field. In calculating the risk level, Global Sentrytakes into account what data was provided in the input record and which inputs, if any, matchedentries in the Global Sentry database. Generally, a higher value indicates a higher risk associatedwith the transaction.
Resource URL
JSON endpoint:
http://server:port/rest/GlobalSentry/results.json
XML endpoint:
http://server:port/rest/GlobalSentry/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GlobalSentry/results.json?Data.FirstName=Miguel&Data.LastName=Batista
91REST Web Services Guide
Chapter 2: Web Services
The JSON returned by this request would be:
Empty response elements have been removed from this example. Only the first response recordshown.
Note:
{"Output": [{"OverallRiskLevel": "10","SanctionedCountryIdentified": "No","Status": "S","FirstName": "Miguel","LastName": "Batista","PlaceOfBirth": "San Sebastian (Guipuzcoa) Spain","EntryID": "315","InputFilteredFirstName": "Miguel","InputFilteredLastName": "Batista","InputFirstName": "Miguel","InputLastName": "Batista","ListType": "DFAT Consolidated List","MatchKey1": "MGL","MatchKey2": "BTST","NameMatchIdentified": "Yes","NameProvided": "Yes","AddressProvided": "No","IDNumberProvided": "No","AddressMatchIdentified": "No","IDNumberMatchIdentified": "No","CitizenshipScore": "0","CitizenshipMatchIdentified": "No","CitizenshipUID": "","DOBScore": "0","DOBMatchIdentified": "No","NationalityScore": "0","NationalityMatchIdentified": "No","PlaceOfBirthScore": "0","PlaceOfBirthMatchIdentified": "No","CitizenshipProvided": "No","DOBProvided": "No","NationalityProvided": "No","PlaceOfBirthProvided": "No","WatchListFirstName": "Miguel","WatchListLastName": "ALBISU IRIARTE","NameScore": "100","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GlobalSentry/results.xml?Data.FirstName=Miguel&Data.LastName=Batista
The XML returned by this request would be:
Empty response elements have been removed from this example. Only the first response recordshown.
Note:
<xml.GlobalSentryResponsexmlns="http://www.pb.com/spectrum/services/GlobalSentry">
<Output><Row>
<OverallRiskLevel>10</OverallRiskLevel><SanctionedCountryIdentified>No</SanctionedCountryIdentified><Status>S</Status><FirstName>Miguel</FirstName>
Spectrum Technology Platform 9.092
Global Sentry Module
<LastName>Batista</LastName><PlaceOfBirth>San Sebastian (Guipuzcoa) Spain</PlaceOfBirth><EntryID>315</EntryID><InputFilteredFirstName>Miguel</InputFilteredFirstName><InputFilteredLastName>Batista</InputFilteredLastName><InputFirstName>Miguel</InputFirstName><InputLastName>Batista</InputLastName><ListType>DFAT Consolidated List</ListType><MatchKey1>MGL</MatchKey1><MatchKey2>BTST</MatchKey2><NameMatchIdentified>Yes</NameMatchIdentified><NameProvided>Yes</NameProvided><AddressProvided>No</AddressProvided><IDNumberProvided>No</IDNumberProvided><AddressMatchIdentified>No</AddressMatchIdentified><IDNumberMatchIdentified>No</IDNumberMatchIdentified><CitizenshipScore>0</CitizenshipScore><CitizenshipMatchIdentified>No</CitizenshipMatchIdentified><DOBScore>0</DOBScore><DOBMatchIdentified>No</DOBMatchIdentified><NationalityScore>0</NationalityScore><NationalityMatchIdentified>No</NationalityMatchIdentified><PlaceOfBirthScore>0</PlaceOfBirthScore><PlaceOfBirthMatchIdentified>No</PlaceOfBirthMatchIdentified><CitizenshipProvided>No</CitizenshipProvided><DOBProvided>No</DOBProvided><NationalityProvided>No</NationalityProvided><PlaceOfBirthProvided>No</PlaceOfBirthProvided><WatchListFirstName>Miguel</WatchListFirstName><WatchListLastName>ALBISU IRIARTE</WatchListLastName><NameScore>100</NameScore><user_fields/>
</Row></Output>
</xml.GlobalSentryResponse>
Request
Parameters for Input Data
Table 41: Global Sentry Input Fields
DescriptionParameter
Full name.Data.Name
Required if FirstName and LastName is not used.
First name or all name elements other than last name.Data.FirstName
Required if Name is not used.
Last name only.Data.LastName
Required if Name is not used.
The first address line.Data.AddressLine1
Recommended if provided.
The second address line.Data.AddressLine2
Recommended if provided.
The third address line.Data.AddressLine3
93REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Recommended if provided.
Full country name.Data.Country
Required if address lines are used.
Identification Number, such as SSN, Passport, Visa, and so on.Data.IDNumber
Recommended if provided.
Any place of birth data.Data.PlaceOfBirth
Recommended if provided.
Date Of Birth, in the format of Year, Month, Day.Data.DOB
Recommended if provided.
Full country name.Data.Citizenship
Recommended if provided.
Full country name.Data.Nationality
Recommended if provided.
Response
Table 42: Global Sentry Service Output
DescriptionResponse Element
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
Spectrum Technology Platform 9.094
Global Sentry Module
DescriptionResponse Element
Address
Input Address line from the original data source.InputAddressLine1
Address line returned from database.AddressLine1
Input Address line from the original data source.InputAddressLine2
Address line returned from database.AddressLine2
Input Address line from the original data source.InputAddressLine3
Address line returned from database.AddressLine3
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
95REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Citizenship returned from database.Citizenship
Citizenship match score. 0 to 100.CitizenshipScore
Identifies Citizenship was a match. Yes or No.CitizenshipMatchIdentified
Identifies Citizenship was provided in the input data. Yes or No.CitizenshipProvided
Nationality
Input Nationality from the original data source.InputNationality
Nationality returned from database.Nationality
Nationality match score. 0-100.NationalityScore
Identifies Nationality was a match. Yes or No.NationalityMatchIdentified
Identifies Nationality was provided in the input data. Yes or No.NationalityProvided
Government List Information
Entry ID that identifies a name, entity, vessel, address, id number, placeof birth, date of birth, citizenship or nationality. This is provided by eachgovt. agency.
EntryID
Name of list provided by the government agencies. SDN, EU, Bank OfEngland, Financial Institutions of Canada.
ListType
Risk Analysis
Risk score per match. 0-16. For more information, see Understandingthe Risk Analysis Score on page 96.
OverAllRiskLevel
Sanction country was identified as a match. Yes or No.SanctionCountryIdentified
Understanding the Risk Analysis ScoreRisk analysis processing assigns a point value to each of these inputs depending on whether the inputwas provided and whether it matched a record in the Global Sentry database. The risk analysis scoreis the sum of these point values. Points are assigned as shown in the following table.
Table 43: Risk Analysis Scoring Method
Did Not MatchMatchedNo Data ProvidedInput
040Name
021Address
021ID
021Date of Birth
021Place of Birth
021Citizenship
021Nationality
Spectrum Technology Platform 9.096
Global Sentry Module
Generally, each input that matches the database is assigned 2 points; Name is the exception. A namematch scores 4 points. Name score is weighted higher following guidance from sources including OFAC,who indicate that a name match is more significant than other types of matches.
If an input is provided and does not match an entry on the database, it is assigned 0 points and has noeffect on the overall risk level. This is consistent with guidance stating that a name match, coupled witha significant amount of additional data which does not match that entry in the database, should not beconsidered a "hit" against a particular list.
If an input is not provided, it is assigned a score of 1. This has the effect of identifying as higher riskthose transactions where one or more inputs match the database, but there are some inputs which arenot available for matching. For these types of transactions, the true risk level cannot be accuratelycalculated because of the missing data. Guidance from agencies such as OFAC suggests that in thesecases you should attempt to obtain as much of the missing data as possible in order to return a moreaccurate assessment of the risk involved in the transaction.
Although higher scores indicate a higher risk transactions, the risk level alone is not always sufficient todetermine the appropriate action. This is because different combinations of matched, not-matched, andnot-provided inputs can result in the same score. To provide additional information to determine whetheran interdiction is appropriate, the Global Sentry service also returns two indicators for each of the seveninputs that are used in matching. These indicate whether the input was provided and whether the inputmatched the database. This allows you to perform additional analysis on transactions that are in themiddle of the risk spectrum to understand whether it is appropriate to report the transaction to the watchlist authority, to flag the transaction as needing additional input data for an accurate risk assessment, toapprove the transaction, or to take some other action.
Customizing the Global Sentry ServiceGlobal Sentry deploys five dataflow templates that you can modify in Enterprise Designer. Each dataflowconsists of various components that were installed from the Spectrum™ Technology Platform, UniversalName, Data Normalization and Advanced Matching modules.
The names of the dataflows are:
• Global Sentry• Global Sentry Name Check• Global Sentry Address Check• Global Sentry ID Number Check• Global Sentry Other Data Check• Global Sentry Batch• Global Sentry Name Check Batch• Global Sentry Address Check Batch• Global Sentry ID Number Check Batch• Global Sentry Other Data Check Batch
Location Intelligence Module
Where to Find Documentation?The Location Intelligence Module provides spatial services that allows you to determine relationshipsbetween locations, areas, or points of interest and other business data, and visually show theserelationships on a map. These services include:
• Geometry• Feature• Mapping• MapTiling
97REST Web Services Guide
Chapter 2: Web Services
• Named Resource• Web Feature Service• Web Map Service• Catalog Service for the Web
To learn about the Location Intelligence Module services, see the Spectrum Spatial Guide onsupport.pb.com.
Universal Addressing Module
AutoCompleteLoqateAutoCompleteLoqate offers real-time entry of address data for fast, accurate results. Users are returnedinstant results based on each character entered into the form, ensuring only accurate data is enteredinto the database.
Resource URL
JSON endpoint:
http://server:port/rest/AutoCompleteLoqate/results.json
XML endpoint:
http://server:port/rest/AutoCompleteLoqate/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/AutoCompleteLoqate/results.json?Data.AddressLine1=1+Global
The JSON returned by this request would be:
To make the example easier to read, empty response elements have been removed and onlythe first three address matches are shown.
Note:
{"output_port": [{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Vw","FirmName": "Map Info","City": "Troy","StateProvince": "NY","PostalCode": "12180-8399","Country": "United States","PostalCode.AddOn": "8399","user_fields": []
},{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Pl","City": "Glendale","StateProvince": "AZ","PostalCode": "85306-3216","Country": "United States","PostalCode.AddOn": "3216",
Spectrum Technology Platform 9.098
Universal Addressing Module
"user_fields": []},
{"ProcessedBy": "LOQATE","HouseNumber": "1","AddressLine1": "1 Global Dr","City": "Olive Hill","StateProvince": "KY","PostalCode": "41164-6739","Country": "United States","PostalCode.AddOn": "6739","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/AutoCompleteLoqate/results.xml?Data.AddressLine1=1+Global
The XML returned by this request would be:
To make the example easier to read, empty response elements have been removed and onlythe first three address matches are shown.
Note:
<ns2:xml.AutoCompleteLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/AutoCompleteLoqate">
<ns2:output_port><ns2:Address>
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Vw</ns2:AddressLine1><ns2:FirmName>Map Info</ns2:FirmName><ns2:City>Troy</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>12180-8399</ns2:PostalCode><ns2:PostalCode.AddOn>8399</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>
</ns2:Address><ns2:Address>
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Pl</ns2:AddressLine1><ns2:City>Glendale</ns2:City><ns2:StateProvince>AZ</ns2:StateProvince><ns2:PostalCode>85306-3216</ns2:PostalCode><ns2:PostalCode.AddOn>3216</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>
</ns2:Address><ns2:Address>
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:HouseNumber>1</ns2:HouseNumber><ns2:AddressLine1>1 Global Dr</ns2:AddressLine1><ns2:City>Olive Hill</ns2:City><ns2:StateProvince>KY</ns2:StateProvince><ns2:PostalCode>41164-6739</ns2:PostalCode><ns2:PostalCode.AddOn>6739</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country>
</ns2:Address></ns2:output_port>
</ns2:xml.AutoCompleteLoqateResponse>
99REST Web Services Guide
Chapter 2: Web Services
Request
Parameters for Input DataThe following table lists the input for AutoCompleteLoqate.
Table 44: Input Format
DescriptionParameter
The first address line.Data.AddressLine1
The second address line.Data.AddressLine2
The third address line.Data.AddressLine3
The fourth address line.Data.AddressLine4
The city name.Data.City
The country code or name, in any of the following formats:Data.Country
• 2-digit ISO country code• 3-digit UPU Country code• English country name
For a list of ISO codes, see Country ISO Codes and Module Supporton page 234.
The company or firm name.Data.FirmName
The postal code for the address.Data.PostalCode
The state or province.Data.StateProvince
Parameters for Options
Table 45: AutoCompleteLoqate Options
DescriptionParameter
Specifies the database to be used for address processing. Onlydatabases that have been defined in the Database Resources panelin the Management Console are available.
Option.Database.Loqate
Specifies the casing of the output data. One of the following:Option.OutputCasing
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
Spectrum Technology Platform 9.0100
Universal Addressing Module
DescriptionParameter
Specifies the default country. You should specify the country wheremost of your addresses reside. For example, if most of the addresses
Option.HomeCountry
you process are in Canada, specify Canada. The valid country namesare:
Afghanistan, Albania, Algeria, American Somoa, Andorra, Angola,Anguilla, Antigua And Barbuda, Argentina, Armenia, Aruba, Australia,Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus,Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, Bosnia AndHerzegovina, Botswana, Brazil, British Virgin Islands, BruneiDarussalam, Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central African Republic, Chad,Chile, China, Colombia, Comoros Islands, Congo, Cook Islands, CostaRica, Cote D'Ivoire, Croatia, Cuba, Cyprus, Czech Republic, DemocraticRepublic Of Congo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea, Eritrea,Estonia, Ethiopia, Falkland Islands, Faroe Islands, Federated States OfMicronesia, Fiji, Finland, France, French Guiana, Gabon, Gambia,Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe,Guam, Guatemala, Guinea, Guinea Bissau, Guyana, Haiti, Holy See,Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan, Kenya,Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho,Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Macedonia,Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Marshall Islands,Martinique, Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru,Nepal, Netherlands Antilles, New Caledonia, New Zealand, Nicaragua,Niger, Nigeria, Niue, Norway, Oman, Pakistan, Palau, Panama, PapuaNew Guinea, Paraguay, Peru, Philippines, Pitcairn Islands, Poland,Portugal, Puerto Rico, Qatar, Republic Of Georgia, Republic Of Korea,Republic Of Singapore, Reunion, Romania, Russia, Rwanda, SaintHelena, Saint Kitts And Nevis, Saint Lucia, Saint Pierre And Miquelon,Saint Vincent And The Grenadines, Samoa, San Marino, Sao TomeAnd Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka,Sudan, Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti, Taiwan,Tajikistan, Tanzania, Thailand, The Netherlands, Togo, Tonga, TrinidadAnd Tobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan, TurksAnd Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna, Yemen,Yugoslavia, Zambia, Zimbabwe
Specifies the alphabet or script in which the output should be returned.This option is bi-directional and generally takes place from Native toLatin and Latin to Native.
Option.OutputScript
Do not perform transliteration and provide output inthe same script as the input (default).
Input
Output in the native script for the selected countrywherever possible.
Native
Use English values.Latn
101REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
The maximum number of addresses that AutoCompleteLoqate shouldreturn. The default is 10.
Option.MaximumResults
Specifies how you want Spectrum Technology Platform to respond whena data license error occurs.
Option.FailJobOnDataLicenseError
Fail the entire job if a data license error occurs.Fail the job
Fail the record(s) for which the data license erroroccurs and continue processing.
Fail the record
ResponseThe output from AutoCompleteLoqate is optional and corresponds directly to the fields you selected inthe Output Fields section of the AutoCompleteLoqate Options dialog box.
Table 46: AutoCompleteLoqate Output
DescriptionResponse Element
The first address line.AddressLine1
The second address line.AddressLine2
The third address line.AddressLine3
The fourth address line.AddressLine4
The city name.City
The three-character ISO 3116-1 Alpha-3 code for the country. For a listof ISO codes, see Country ISO Codes and Module Support on page234.
Country
The firm name.FirmName
The ending house number for the range in which the candidate address'shouse number falls.
HouseNumber
The postal code.PostalCode
The last four digits of the ZIP + 4® Code.PostalCode.AddOn
Indicates which address coder processed the address.ProcessedBy
The Loqate coder processed the address.LOQATE
The state or province abbreviation.StateProvince
Reports the success or failure of the match attempt.Status
Successnull
FailureF
The reason for failure, if there is one.Status.Code
• DisabledCoder• RequestFailed
Spectrum Technology Platform 9.0102
Universal Addressing Module
DescriptionResponse Element
• 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.
103REST Web Services Guide
Chapter 2: Web Services
The Canadian coder contains a reverse lookup routine that takes as input a specific postal code andreturns the street information stored in the database for that postal code. To use this function enternothing but a Canadian postal code in the PostalCode field. See the second example to view the returnfrom a sample postal code.
GetCandidateAddresses is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/GetCandidateAddresses/results.json
XML endpoint:
http://server:port/rest/GetCandidateAddresses/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetCandidateAddresses/results.json?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY
The JSON returned by this request would be:
{"output_port": [{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "60","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10002","Country": "USA","PostalCode.AddOn": "0001","user_fields": []
},{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "9","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10008","Country": "USA","PostalCode.AddOn": "0001","user_fields": []
},
Spectrum Technology Platform 9.0104
Universal Addressing Module
{"ProcessedBy": "USA","RecordType": "PostOfficeBox","MatchLevel": "A","AddressLine1": "PO Box 1","HouseNumberLow": "1","HouseNumberHigh": "60","HouseNumberParity": "B","UnitNumberLow": "","UnitNumberHigh": "","UnitNumberParity": " ","FirmName": "","City": "New York","USUrbanName": "","StateProvince": "NY","PostalCode": "10009","Country": "USA","PostalCode.AddOn": "0001","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetCandidateAddresses/results.xml?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY
The XML returned by this request would be:
<ns2:xml.GetCandidateAddressesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCandidateAddresses">
<ns2:output_port><ns2:Address>
<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:RecordType>PostOfficeBox</ns2:RecordType><ns2:MatchLevel>A</ns2:MatchLevel><ns2:AddressLine1>PO Box 1</ns2:AddressLine1><ns2:HouseNumberLow>1</ns2:HouseNumberLow><ns2:HouseNumberHigh>60</ns2:HouseNumberHigh><ns2:HouseNumberParity>B</ns2:HouseNumberParity><ns2:UnitNumberLow/><ns2:UnitNumberHigh/><ns2:UnitNumberParity></ns2:UnitNumberParity><ns2:FirmName/><ns2:City>New York</ns2:City><ns2:USUrbanName/><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>10002</ns2:PostalCode><ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country><ns2:user_fields/>
</ns2:Address><ns2:Address>
<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:RecordType>PostOfficeBox</ns2:RecordType><ns2:MatchLevel>A</ns2:MatchLevel><ns2:AddressLine1>PO Box 1</ns2:AddressLine1><ns2:HouseNumberLow>1</ns2:HouseNumberLow><ns2:HouseNumberHigh>9</ns2:HouseNumberHigh><ns2:HouseNumberParity>B</ns2:HouseNumberParity><ns2:UnitNumberLow/><ns2:UnitNumberHigh/><ns2:UnitNumberParity></ns2:UnitNumberParity><ns2:FirmName/><ns2:City>New York</ns2:City><ns2:USUrbanName/><ns2:StateProvince>NY</ns2:StateProvince>
105REST Web Services Guide
Chapter 2: Web Services
<ns2:PostalCode>10008</ns2:PostalCode><ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country><ns2:user_fields/>
</ns2:Address></ns2:output_port>
</ns2:xml.GetCandidateAddressesResponse>
Request
Parameters for Input DataThe following table lists the input for GetCandidateAddresses.
Table 47: Input Format
DescriptionParameter
The first address line.Data.AddressLine1
The second address line.Data.AddressLine2
The third address line.Data.AddressLine3
Does not apply to U.S. and Canadian addresses.
The fourth address line.Data.AddressLine4
Does not apply to U.S. and Canadian addresses.
The fifth address line.Data.AddressLine5
Applies only to U.K. addresses. May contain street name, unit number,building number, and so on.
The city name.Data.City
The state or province.Data.StateProvince
For U.S. addresses only, you may put the state in the City field insteadof the StateProvince field.
The postal code for the address. For U.S. addresses this is the ZIPCode™ in one of the following formats:
Data.PostalCode
9999999999-9999A9A9A9A9A 9A99999 999
For Canadian addresses you can complete just this field andhave candidate address data returned. For other countries,AddressLine1 and AddressLine2 must also be completed.
Note:
The country code or name, in any of the following formats:Data.Country
• 2-digit ISO country code• 3-digit UPU Country code• English country name• French country name
Spectrum Technology Platform 9.0106
Universal Addressing Module
DescriptionParameter
• German country name• Spanish country name
For a list of ISO codes, see Country ISO Codes and Module Supporton page 234.
The company or firm name.Data.FirmName
U.S. address urbanization name. Used primarily for Puerto Ricoaddresses.
Data.USUrbanName
Parameters for Options
Table 48: GetCandidateAddresses Options
DescriptionParameter
Specifies whether or not to process U.S. addresses. If youenable U.S. address processing GetCandidateAddresses will
Option.PerformUSProcessing
attempt to retrieve candidate addresses for U.S. addresses.If you disable U.S. address processing, U.S. addresses willfail, meaning they are returned with an "F" in the Status outputfield. The output field Status.Code will say "DisabledCoder."If you are not licensed for U.S. address processing you mustdisable U.S. address processing in order for your jobs tocomplete successfully, regardless of whether or not theycontain U.S. addresses.
You must have a valid license for U.S. addressprocessing to successfully process U.S. addresses.
Note:
If you enable U.S. address processing but are notlicensed for this feature, or your license has expired,you will receive an error.
Yes, process U.S. addresses (default).Y
No, do not process U.S. addresses.N
Specifies the database to be used for U.S. addressprocessing. Only databases that have been defined in the
Option.Database.US
US Database Resources panel in theManagement Consoleare available.
Specifies whether or not to process Canadian addresses. Ifyou enable Canadian address processing
Option.PerformCanadianProcessing
GetCandidateAddresses will attempt to retrieve candidateaddresses for Canadian addresses. If you disable Canadianaddress processing, Canadian addresses will fail, meaningthey are returned with an "F" in the Status output field. Theoutput field Status.Code will say "DisabledCoder." If you arenot licensed for Canadian address processing you mustdisable Canadian address processing in order for your jobsto complete successfully, regardless of whether or not theycontain Canadian addresses.
107REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
You must have a valid license for Canadian addressprocessing to successfully process Canadian
Note:
addresses. If you enable Canadian addressprocessing but are not licensed for this feature, oryour license has expired, you will receive an error.
Yes, process Canadian addresses (default).Y
No, do not process Canadian addresses.N
Specifies the database to be used for Canadian addressprocessing. Only databases that have been defined in the
Option.Database.Canada
Canadian Database Resources panel in the ManagementConsole are available.
Specifies whether or not to process international addresses(addresses outside the U.S. and Canada). If you enable
Option.PerformInternationalProcessing
international address processing GetCandidateAddresseswill attempt to retrieve candidate addresses for internationaladdresses. If you disable international address processing,international addresses will fail, meaning they are returnedwith an "F" in the Status output field. The output fieldStatus.Code will say "DisabledCoder." If you are not licensedfor international address processing you must disableinternational address processing in order for your jobs tocomplete successfully, regardless of whether or not theycontain international addresses.
You must have a valid license for internationaladdress processing to successfully process
Note:
international addresses. If you enable internationaladdress processing but are not licensed for thisfeature, or your license has expired, you will receivean error.
Yes, process international addresses (default).Y
No, do not process international addresses.N
Specifies the database to be used for international addressprocessing. Only databases that have been defined in the
Option.Database.International
International Database Resources panel in theManagementConsole are available.
Specifies the casing of the output data. One of the following:Option.OutputCasing
The output is in mixed case (default). For example:
123 Main StMytown FL 12345
M
The output is in upper case. For example:
123 MAIN STMYTOWN FL 12345
U
Spectrum Technology Platform 9.0108
Universal Addressing Module
DescriptionParameter
The maximum number of candidate addresses thatGetCandidateAddresses should return. The default is 10. Themaximum is 10.
Option.MaximumResults
For U.S. addresses, specifies whether or not to return theUSPS®-approved abbreviation for the city, if there is one. The
Option.OutputShortCityName
USPS® provides abbreviations for city names that are 14characters long or longer. City abbreviations are 13 charactersor less and can be used when there is limited space on themailing label. If there is no short city name for the city, thenthe full city name is returned.
Yes, return the short city name.Y
No, do not return the short city name.N
(U.S. addresses only). Controls whetherGetCandidateAddresses should return a street match or a
Option.DualAddressLogic
PO Box/Rural Route/Highway Contract match when theaddress contains both street and PO Box/RuralRoute/Highway Contract information. For more information,see About Dual Address Logic on page 138.
(Default) USPS® CASS™ regulations determine theaddress returned based on the following order ofpriority:
N
1. PO Box2. Firm3. Highrise4. Street5. Rural Route6. General Delivery
Return a street match, regardless of the address line.S
Return a PO Box match, regardless of the addressline.
P
The strictness of the street name match (U.S. addressesonly).
Option.StreetMatchingStrictness
The input street name must match the databaseexactly.
E
The matching algorithm is "tight."T
The matching algorithm is "medium" (default).M
The matching algorithm is "loose".L
The strictness of the firm name match (U.S. addresses only).Option.FirmMatchingStrictness
The input firm name must match the databaseexactly.
E
The matching algorithm is "tight."T
The matching algorithm is "medium" (default).M
The matching algorithm is "loose."L
109REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
The strictness of the directional match.Option.DirectionalMatchingStrictness
The input directional must match the databaseexactly.
E
The matching algorithm is "tight."T
The matching algorithm is "medium" (default).M
The matching algorithm is "loose."L
Specifies whether or not to perform Enhanced Street Matching(ESM). ESM applies extra matching logic with additional data
Option.PerformESM
to any input address that is not matched through the regularaddress validation process. ESM applies to U.S. addressesonly.
Yes, perform ESM processing.Y
No, do not perform ESM processing (default).N
Specifies whether ValidateAddress will search address linesfor the city, state/province, and postal code.
Option.AddressLineSearchOnFail
This option enables ValidateAddress to search theAddressLine input fields for the city, state/province, postalcode, and country when the address cannot bematched usingthe values in the City, StateProvince, and PostalCode inputfields.
Consider enabling this option if your input addresses havethe city, state/province, and postal code information in theAddressLine fields.
Consider disabling this option if your input addresses use theCity, State/Province and PostalCode fields. If you enable thisoption and these fields are used, there is an increasedpossibility that ValidateAddress will fail to correct values inthese fields (for example a misspelled city name).
Yes, search the address line fields (default).Y
No, do not search the AddressLine fields.N
ResponseGetCandidateAddresses returns the following output.
Table 49: GetCandidateAddresses Output
DescriptionResponse Element
The first address line.AddressLine1
The second address line.AddressLine2
The third address line.AddressLine3
The fourth address line.AddressLine4
Spectrum Technology Platform 9.0110
Universal Addressing Module
DescriptionResponse Element
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
The three-character ISO 3116-1 Alpha-3 code for the country. For a listof ISO codes, see Country ISO Codes and Module Support on page234.
Country
The firm name.FirmName
The ending house number for the range in which the candidate address'shouse number falls.
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
The state or province abbreviation.StateProvince
Reports the success or failure of the match attempt.Status
Successnull
111REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
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
This value will appear ifStatus.Code=DisabledCoder.
PerformCanadianProcessingdisabled
This value will appear ifStatus.Code=DisabledCoder.
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.
Spectrum Technology Platform 9.0112
Universal Addressing Module
GetCandidateAddressesLoqate is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/GetCandidateAddressesLoqate/results.json
XML endpoint:
http://server:port/rest/GetCandidateAddressesLoqate/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetCandidateAddressesLoqate/results.json?Data.AddressLine1=PO+Box+1&Data.City=New+York&Data.StateProvince=NY
The JSON returned by this request would be:
Empty response elements have been removed from this example. Only the first two candidateaddress are shown.
Note:
{"output_port": [{"ProcessedBy": "LOQATE","AddressLine1": "PO Box 101","City": "New York Mls","StateProvince": "NY","PostalCode": "13417-0101","Country": "USA","PostalCode.AddOn": "0101","user_fields": []
},{"ProcessedBy": "LOQATE","AddressLine1": "PO Box 102","City": "New York Mls","StateProvince": "NY","PostalCode": "13417-0102","Country": "USA","PostalCode.AddOn": "0102","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetCandidateAddressesLoqate/results.xml?Data.AddressLine1=PO+Box+1&Data.City=New+York&Data.StateProvince=NY
The XML returned by this request would be:
Empty response elements have been removed from this example. Only the first two candidateaddress are shown.
Note:
<ns2:xml.GetCandidateAddressesLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCandidateAddressesLoqate">
<ns2:output_port><ns2:Address>
113REST Web Services Guide
Chapter 2: Web Services
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:AddressLine1>PO Box 101</ns2:AddressLine1><ns2:City>New York Mls</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>13417-0101</ns2:PostalCode><ns2:PostalCode.AddOn>0101</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country>
</ns2:Address><ns2:Address>
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:AddressLine1>PO Box 102</ns2:AddressLine1><ns2:City>New York Mls</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>13417-0102</ns2:PostalCode><ns2:PostalCode.AddOn>0102</ns2:PostalCode.AddOn><ns2:Country>USA</ns2:Country>
</ns2:Address></ns2:output_port>
</ns2:xml.GetCandidateAddressesLoqateResponse>
Request
Parameters for Input DataThe following table lists the input for GetCandidateAddressesLoqate.
Table 50: Input Format
DescriptionParameter
The first address line.Data.AddressLine1
The second address line.Data.AddressLine2
The third address line.Data.AddressLine3
The fourth address line.Data.AddressLine4
The city name.Data.City
The country code or name, in any of the following formats:Data.Country
• 2-digit ISO country code• 3-digit UPU Country code• English country name
For a list of ISO codes, see Country ISO Codes and Module Supporton page 234.
This field is required. If this field is blank, no output will bereturned.
Note:
The company or firm name.Data.FirmName
The postal code for the address. For U.S. addresses this is the ZIPCode™ in one of the following formats:
Data.PostalCode
The state or province.Data.StateProvince
For U.S. addresses only, you may put the state in the City field insteadof the StateProvince field.
Spectrum Technology Platform 9.0114
Universal Addressing Module
Parameters for Options
Table 51: GetCandidateAddressesLoqate Options
DescriptionParameter
Specifies the database to be used for address processing. Onlydatabases that have been defined in the Management Console areavailable.
Option.Database.Loqate
Specifies the casing of the output data. One of the following:Option.OutputCasing
The output is in mixed case (default). For example:
123 Main StMytown FL 12345
M
The output is in upper case. For example:
123 MAIN STMYTOWN FL 12345
U
Specifies the default country. You should specify the country wheremost of your addresses reside. For example, if most of the addresses
Option.HomeCountry
you process are in Canada, specify Canada.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,
115REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Saint Vincent And The Grenadines, Samoa, San Marino, Sao TomeAnd Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka,Sudan, Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti, Taiwan,Tajikistan, Tanzania, Thailand, The Netherlands, Togo, Tonga, TrinidadAnd Tobago, Tristan Da Cunha, Tunisia, Turkey, Turkmenistan, TurksAnd Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna, Yemen,Yugoslavia, Zambia, Zimbabwe
The maximum number of candidate addresses thatGetCandidateAddressesLoqate should return. The default is 10. Themaximum is 99.
Option.MaximumResults
ResponseGetCandidateAddressesLoqate returns the following output.
Table 52: GetCandidateAddressesLoqate Output
DescriptionResponse Element
The first address line.AddressLine1
The second address line.AddressLine2
The third address line.AddressLine3
The fourth address line.AddressLine4
The city name.City
The three-character ISO 3116-1 Alpha-3 code for the country. For a listof ISO codes, see Country ISO Codes and Module Support on page234.
Country
The firm name.FirmName
The 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
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. There is only one possible value:Status.Code
• RequestFailed
Spectrum Technology Platform 9.0116
Universal Addressing Module
DescriptionResponse Element
A description of the problem, if there is one. There is only one possiblevalue:
Status.Description
The input address matched only one address inthe database. GetCandidateAddressesLoqate
Did not returnmultiples
only returns data if multiple possible matches werefound.
GetCityStateProvinceGetCityStateProvince returns a city and state/province for a given input postal code.
GetCityStateProvince works with U.S. and Canadian addresses only.Note:
GetCityStateProvince is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/GetCityStateProvince/results.json
XML endpoint:
http://server:port/rest/GetCityStateProvince/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetCityStateProvince/results.json?Data.PostalCode=12180
The JSON returned by this request would be:
{"output_port": [{"ProcessedBy": "USA","PostalCode": "12180","City": "TROY","StateProvince": "NY","Country": "USA","City.Type": "P","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetCityStateProvince/results.xml?Data.PostalCode=12180
The XML returned by this request would be:
<ns2:xml.GetCityStateProvinceResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCityStateProvince">
<ns2:output_port>
117REST Web Services Guide
Chapter 2: Web Services
<ns2:Result><ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>12180</ns2:PostalCode><ns2:City>TROY</ns2:City><ns2:City.Type>P</ns2:City.Type><ns2:StateProvince>NY</ns2:StateProvince><ns2:Country>USA</ns2:Country><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.GetCityStateProvinceResponse>
Request
Parameters for Input DataThe following table shows the input fields.
Table 53: GetCityStateProvince Input
DescriptionParameter
A U.S. ZIP Code™ or Canadian postal code in one of the followingformats:
Data.PostalCode
99999
99999-9999
A9A9A9
A9A 9A9
Parameters for Options
Table 54: GetCityStateProvince Options
DescriptionParameter Name
Specifies whether or not to process U.S. addresses. If you enable U.S.address processing GetCityStateProvince will attempt to return the state
Option.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
No, do not process U.S. addresses.N
Spectrum Technology Platform 9.0118
Universal Addressing Module
DescriptionParameter Name
Specifies the database to be used for U.S. address processing. Onlydatabases that have been defined in the US Database Resourcespanel in the Management Console are available.
Option.Database.US
Specifies whether or not to process Canadian addresses. If you enableCanadian address processing GetCityStateProvince will attempt to
Option.PerformCanadianProcessing
return the province for Canadian addresses. If you disable Canadianaddress processing, Canadian addresses will fail, meaning they arereturned with an "F" in the Status output field. The output fieldStatus.Code will say "DisabledCoder." If you are not licensed forCanadian address processing you must disable Canadian addressprocessing in order for your jobs to complete successfully, regardlessof whether or not they contain Canadian addresses.
You must have a valid license for Canadian address processingto successfully process Canadian addresses. If you enable
Note:
Canadian address processing but are not licensed for thisfeature, or your license has expired, you will receive an error.
Yes, process Canadian addresses (default).Y
No, do not process Canadian addresses.N
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.
Option.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.
Option.OutputVanityCity
Yes, include non-mailing city names.Y
No, do not include non-mailing city names (default).N
Specifies the maximum number of city-state/province pairs to return.The default value is 10.
Option.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 55: GetCityStateProvince Output
DescriptionResponse Element
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
119REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
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
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. 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
This value will appear ifStatus.Code=DisabledCoder.
PerformUSProcessingdisabled
This value will appear ifStatus.Code=DisabledCoder.
PerformCanadianProcessingdisabled
GetCityStateProvinceLoqateGetCityStateProvinceLoqate returns a city and state/province for a given input postal code.
This stage is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/GetCityStateProvinceLoqate/results.json
XML endpoint:
http://server:port/rest/GetCityStateProvinceLoqate/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetCityStateProvinceLoqate/results.json?Data.Country=USA&Data.PostalCode=60510
Spectrum Technology Platform 9.0120
Universal Addressing Module
The JSON returned by this request would be:
{"output_port": [{"ProcessedBy": "LOQATE","PostalCode": "60510","City": "Batavia","StateProvince": "IL","Country": "United States","Status": "","Status.Code": "","Status.Description": "","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetCityStateProvinceLoqate/results.xml?Data.Country=USA&Data.PostalCode=60510
The XML returned by this request would be:
<ns2:xml.GetCityStateProvinceLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetCityStateProvinceLoqate">
<ns2:output_port><ns2:Result>
<ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:PostalCode>60510</ns2:PostalCode><ns2:City>Batavia</ns2:City><ns2:StateProvince>IL</ns2:StateProvince><ns2:Country>United States</ns2:Country><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.GetCityStateProvinceLoqateResponse>
Request
Parameters for Input DataThe following table shows the input fields.
Table 56: GetCityStateProvinceLoqate Input
DescriptionParameter
The country code or name, in any of the following formats:Data.Country
• 2-digit ISO country code• 3-digit UPU Country code• English country name
For a list of ISO codes, see Country ISO Codes and Module Supporton page 234.
The postal code for the address.Data.PostalCode
121REST Web Services Guide
Chapter 2: Web Services
Options
Table 57: GetCityStateProvinceLoqate Options
Description / Valid Values
Specifies the database to be used for address processing. Onlydatabases that have been defined in the Database Resources panelin the Management Console are available.
The maximum number of addresses that GetCityStateProvinceLoqateshould return. The default is 10.
Specifies the alphabet or script in which the output should be returned.This option is bi-directional and generally takes place from Native toLatin and Latin to Native.
Do not perform transliteration and provide output in the same scriptas the input (default).
Output in the native script for the selected country wherever possible.
Use English values.
Specifies how you want Spectrum Technology Platform to respondwhen a data license error occurs.
Fail the entire job if a data license error occurs.Fail the job
Fail the record(s) for which the data licenseerror occurs and continue processing.
Fail the record
ResponseGetCityStateProvinceLoqate returns the matching city and state/province for the input postal code aswell as a code to indicate the success or failure of the match attempt. If more than one city/state orcity/province matches the input postal code, multiple output records are returned.
Table 58: GetCityStateProvinceLoqate Output
DescriptionResponse Element
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
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
Spectrum Technology Platform 9.0122
Universal Addressing Module
DescriptionResponse Element
Successnull
FailureF
The reason for failure, if there is one. The only valid value is:Status.Code
• UnrecognizedPostalCode
The description of the failure. The only valid value is:Status.Description
This value will appear ifStatus.Code=UnrecognizedPostalCode.
Postal code not found
GetPostalCodesGetPostalCodes allows you to look up the postal codes for a particular city. The service takes a city,state, and country as input and returns the postal codes for that city. The input must be exactly correctin order to return postal codes.
GetPostalCodes only works with U.S. addresses.Note:
GetPostalCodes is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/GetPostalCodes/results.json
XML endpoint:
http://server:port/rest/GetPostalCodes/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/GetPostalCodes/results.json?Data.City=Holland&Data.StateProvince=MI
The JSON returned by this request would be:
{"output_port": [{"ProcessedBy": "USA","PostalCode": "49422","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []
},{"ProcessedBy": "USA","PostalCode": "49423","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []
123REST Web Services Guide
Chapter 2: Web Services
},{"ProcessedBy": "USA","PostalCode": "49424","Status": "","City.Type": " ","Status.Code": "","Status.Description": "","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/GetPostalCodes/results.xml?Data.City=Holland&Data.StateProvince=MI
The XML returned by this request would be:
<ns2:xml.GetPostalCodesResponsexmlns:ns2="http://www.pb.com/spectrum/services/GetPostalCodes">
<ns2:output_port><ns2:Result>
<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>49422</ns2:PostalCode><ns2:City.Type></ns2:City.Type><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>
</ns2:Result><ns2:Result>
<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>49423</ns2:PostalCode><ns2:City.Type></ns2:City.Type><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>
</ns2:Result><ns2:Result>
<ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:PostalCode>49424</ns2:PostalCode><ns2:City.Type></ns2:City.Type><ns2:Status/><ns2:Status.Code/><ns2:Status.Description/><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.GetPostalCodesResponse>
Request
Parameters for Input DataGetPostalCodes takes a city, state/province, and country as input.
Spectrum Technology Platform 9.0124
Universal Addressing Module
Table 59: GetPostalCodes Input
DescriptionParameter
The city whose postal codes you want to look up.Data.City
You may put the city and state in the City field. If you do this, you mustleave the StateProvince field blank.
The total length of the City and StateProvince fields cannot exceed 100characters.
The state or province of the city whose postal codes you want to lookup.
Data.StateProvince
You may also put the state in the City field instead of the StateProvincefield.
The total length of the City and StateProvince fields cannot exceed 100characters.
The country code or name of the city whose postal codes you want tolook up. The only valid value is US.
Data.Country
Parameters for Options
Table 60: GetPostalCodes Options
DescriptionParameter
Specifies the database to be used for postal code look-ups. Onlydatabases that have been defined in the US Database Resources panelin the Management Console are available.
Option.Database.US
Specifies whether or not to include postal codes for the city's non-mailingcity names. A non-mailing city name is an alternate name for the primary
Option.IncludeVanityCity
city name. For example, Hollywood is a non-mailing city name for LosAngeles.
Yes, include postal codes for non-mailing city names.Y
No, do not include postal codes for non-mailing city names(default).
N
Specifies whether or not to return the city type in the output. If enabled,the city type is returned in the City.Type field.
Option.OutputCityType
Yes, include the city type in the output.Y
No, do not include the city type in the output (default).N
ResponseGetPostalCodes returns the postal codes for a specified city. Each postal code is returned in a separaterecord along with the data listed in the following table.
125REST Web Services Guide
Chapter 2: Web Services
Table 61: GetPostalCodes Output
DescriptionResponse Element
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
Reports the success or failure of the match attempt.Status
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.
Spectrum Technology Platform 9.0126
Universal Addressing Module
Resource URL
JSON endpoint:
http://server:port/rest/ValidateAddress/results.json
XML endpoint:
http://server:port/rest/ValidateAddress/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/ValidateAddress/results.json?Data.AddressLine1=1825+Kramer+Ln&Data.PostalCode=78758
The JSON returned by this request would be:
{"output_port": [{"Confidence": "100","RecordType": "Normal","CountryLevel": "A","ProcessedBy": "USA","MatchScore": "0","AddressLine1": "1825 Kramer Ln","City": "Austin","StateProvince": "TX","PostalCode": "78758-4260","Country": "United States Of America","PostalCode.Base": "78758","PostalCode.AddOn": "4260","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/ValidateAddress/results.xml?Data.AddressLine1=1825+Kramer+Ln&Data.PostalCode=78758
The XML returned by this request would be:
<ns2:xml.ValidateAddressResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddress">
<ns2:output_port><ns2:Address>
<ns2:Confidence>93</ns2:Confidence><ns2:RecordType>Normal</ns2:RecordType><ns2:CountryLevel>A</ns2:CountryLevel><ns2:ProcessedBy>USA</ns2:ProcessedBy><ns2:MatchScore>0</ns2:MatchScore><ns2:AddressLine1>1825 Kramer Ln</ns2:AddressLine1><ns2:City>Austin</ns2:City><ns2:StateProvince>TX</ns2:StateProvince><ns2:PostalCode>78758-4260</ns2:PostalCode><ns2:PostalCode.Base>78758</ns2:PostalCode.Base><ns2:PostalCode.AddOn>4260</ns2:PostalCode.AddOn><ns2:Country>United States Of America</ns2:Country><ns2:user_fields/>
</ns2:Address></ns2:output_port>
</ns2:xml.ValidateAddressResponse>
127REST Web Services Guide
Chapter 2: Web Services
Request
Parameters for Input DataValidateAddress takes an address as input. All addresses use this format regardless of the address'scountry. SeeAddress Line Processing for U.S. Addresses on page 129 for important information abouthow address line data is processed for U.S. addresses.
Table 62: Input Format
DescriptionFormatParameter
The first address line.String[50]
Data.AddressLine1
The second address line.String[50]
Data.AddressLine2
The third address line.String[50]
Data.AddressLine3
Does not apply to Canadian addresses.
The fourth address line.String[50]
Data.AddressLine5
Does not apply to Canadian addresses.
The fifth address line.String[50]
Data.AddressLine5
Applies only to U.K. addresses. May contain street name, unitnumber, building number, and so on.
The city name.String[50]
Data.City
For U.S. addresses only, you may put the city, state, and ZIPCode™ in the City field. If you do this, you must leave theStateProvince and PostalCode fields blank.
The state or province.String[50]
Data.StateProvince
For U.S. addresses only, you may put the state in the Cityfield instead of the StateProvince field.
The postal code for the address in one of the followingformats:
String[10]
Data.PostalCode
9999999999-9999A9A9A9A9A 9A99999 999
For U.S. addresses only, you may put the ZIP Code™ in theCity field.
For U.S. addresses only, if the city/state/ZIP Code™ is in thePostalCode field, ValidateAddress may parse the data andsuccessfully process the address. For best results, put thisdata in the appropriate fields (City, StateProvince, andPostalCode).
The country code or name, in any of the following formats:String[50]
Data.Country
• Two-character ISO 3116-1 Alpha-2 country code
Spectrum Technology Platform 9.0128
Universal Addressing Module
DescriptionFormatParameter
• Three-character ISO 3116-1 Alpha-3 country code• English country name• French country name• German country name• Spanish country name
For a list of ISO codes, seeCountry ISO Codes and ModuleSupport on page 234.
The company or firm name.String[50]
Data.FirmName
The U.S. address urbanization name. This is used primarilyfor Puerto Rico addresses.
String[50]
Data.USUrbanName
If this mailpiece uses a generic barcode, specify yourUSPS®-assigned customer ID in this field. The
String [9]Data.CustomerID
ValidateAddress generic barcode is used for mailpieces thatuse the OneCode ACS® service.
For Canadian addresses only, indicates whether the addressis in English or French, if the optionOption.CanFrenchFormat=T is used.
StringData.CanLanguage
If this field is blank, the address is formatted in English. If thefield contains any non-blank value, the address is formattedin French. Note that addresses in Quebec are alwaysformatted in French regardless of the value in this field.
Address Line Processing for U.S. Addresses
The input fields AddressLine1 through AddressLine4 are handled differently for U.S. addresses dependingon whether the firm name extraction or urbanization code extraction options are enabled. If either ofthese options is enabled, ValidateAddress will look at the data in all four fields to validate the addressand extract the requested data (firm name and/or urbanization code). If neither of these options is enabled,ValidateAddress uses only the first two non-blank address line fields in its validation attempt. The datain the other address line fields is returned in the output field AdditionalInputData. For example,
AddressLine1: A1 Calle AAddressLine2:AddressLine3: URB AlamarAddressLine4: Pitney Bowes Software
In this address, if either firm name extraction or urbanization code extraction were enabled,ValidateAddress would examine all four address lines. If neither firm name extraction nor urbanizationcode extraction were enabled, ValidateAddress would examine AddressLine1 and AddressLine3 (thefirst two non-blank address lines) and attempt to validate the address using that data; the data inAddressLine4 would be returned in the output field AdditionalInputData.
Parameters for OptionsOutput Data Options
The following table lists the options that control the type of information returned by ValidateAddress.Some of these options can be overridden for Canadian addresses. For more information, see CanadianAddress Options on page 148.
129REST Web Services Guide
Chapter 2: Web Services
Table 63: Output Data Options
DescriptionParameter
Type of output record. For more than one, provide a list.Option.OutputRecordType
Returns 1 to 4 lines of address data plus city, state,postal code, firm name, and urbanization name
A
information. Each address line represents an actualline of the address as it would appear on an envelope.For more information, see Response on page 156. IfValidateAddress could validate the address, theaddress lines contain the standardized address.Whenaddresses are standardized, punctuation is removed,directionals are abbreviated, street suffixes areabbreviated, and address elements are corrected. IfValidateAddress could not validate the address, theaddress lines contain the address as it appeared inthe input ("pass through" data). Non-validatedaddresses are always included as pass through datain the address line fields even if you do not specifyOutputRecordType=A.
Parsed address elements. Each part of the address,such as house number, street name, street suffix,
E
directionals, and so on is returned in a separate field.For more information, seeParsed Address ElementsOutput on page 157. Note that if you specify "E" andspecify OutputFormattedOnFail=Y, the parsedaddress elements will contain the input address foraddresses that could not be validated.
Parsed input. This option returns the input address inparsed form regardless of whether or not
I
ValidateAddress is able to validate the address. Eachpart of the input address, such as house number,street name, street suffix, directionals, and so on isreturned in a separate field. Parsed input (value "I")differs from the combination ofOutputRecordType=Eand OutputFormattedOnFail=Y in that "I" returns allinput address in parsed form, not just input that couldnot be validated. For more information, see ParsedInput on page 159.
Postal data. Output addresses contain additional datafor each validated address. For more information, seePostal Data Output on page 160.
P
Do not return any address data or postal data.Blank
Specifies whether to include field-level result indicators.Field-level result indicators describe how ValidateAddress
Option.OutputFieldLevelReturnCodes
handled each address element. Field-level result indicatorsare returned in the qualifier "Result". For example, thefield-level result indicator for HouseNumber is contained inHouseNumber.Result. For a complete listing of resultindicator output fields, see Field-Level Result Indicators onpage 165.
Spectrum Technology Platform 9.0130
Universal Addressing Module
DescriptionParameter
No, do not output field-level return codes (default).N
Yes, output field-level return codes.Y
Specifies whether to return a formatted address when anaddress cannot be validated. The address is formatted using
Option.OutputFormattedOnFail
the preferred address format for the address's country. If thisoption is not selected, the output address fields are blankwhen ValidateAddress cannot validate the address.
This option applies only to U.S. and Canadianaddresses. Formatted data will not be returned forany other address.
Note:
No, do not format failed addresses (default).N
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.
131REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
If you check this option, you must select Include a standardaddress and/or Include address line elements.
For U.S. addresses only, specifies whether or not to use astreet's alias in the output. A street alias is an alternate name
Option.OutputStreetNameAlias
for a street and typically applies only to a specific range ofaddresses on the street. If you do not allow street aliases inthe output then the street's "base" name will appear in theoutput regardless of whether or not there is an alias for thestreet. The base name is the name that applies to the entirestreet.
No, do not return street name aliases in the output.N
Yes, return street name aliases in the output if thereis an alias for the street (default).
Y
For U.S. addresses only, specifies how to handle street namealiases used in the input. A street alias is an alternate name
Option.OutputStreetNameAlias
for a street and typically applies only to a specific range ofaddresses on the street.
If you enable this option, street name aliases used in the inputwill appear in the output. If you do not enable this option,street name aliases in the input will be converted to the basestreet name in the output, with the following exceptions:
• If a preferred alias is used in input the preferred alias willalways be used in output.
• Changed aliases used in input are always converted to thebase street name in output.
This is one of three options that control how ValidateAddresshandles street name aliases. The other two areOption.OutputPreferredAlias andOption.OutputAbbreviatedAlias.
If Option.OutputAbbreviatedAlias is enabled, theabbreviated alias will always appear in the output
Note:
even if you have Option.OutputStreetNameAliasdisabled.
No, do not return street name aliases in the output.N
Yes, return street name aliases in the output if theinput street name is an alias (default).
Y
Specifies whether to return a formatted version of the addressas it would be printed on a physical mailpiece. Each line of
Option.OutputAddressBlocks
the address is returned in a separate address block field.There can be up to nine address block output fields:AddressBlock1 through AddressBlock9.
For example, this input address:
AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600City: Lanham
Spectrum Technology Platform 9.0132
Universal Addressing Module
DescriptionParameter
StateProvince: MDPostalCode: 20706
Results in this address block output:
AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882AddressBlock3: UNITED STATES OF AMERICA
ValidateAddress formats the address into address blocksusing postal authority standards. The country name is returnedusing the Universal Postal Union country name. Note that theoption Option.OutputCountryFormat does not affect thecountry name in the address block, it only affects the namereturned in the Country output field.
For addresses outside the U.S. and Canada, ifValidateAddress is unable to validate the address, no addressblocks are returned. For addresses in the U.S. and Canada,address blocks are returned even if validation fails.
No, do not return address blocks. Default.N
Yes, return address blocks.Y
Obtaining Congressional Districts
ValidateAddress can determine the U.S. congressional district for an address.
To obtain congressional districts, Option.OutputRecordType must contain P. For more informationon Option.OutputRecordType, see Output Data Options on page 129.
Table 64: Congressional District Output
DescriptionResponse Element
Congressional district number. If the address is a non-state address (forexample Puerto Rico or Washington D.C.) this field is blank.
USCongressionalDistrict
Obtaining County Names
ValidateAddress can determine the county where a particular address is located and return the countyname.
County names are available for U.S. addresses only.Note:
To obtain county names, Option.OutputRecordType must contain P. For more information onOption.OutputRecordType, see Output Data Options on page 129.
Table 65: County Name Output
DescriptionResponse Element
County nameUSCountyName
Obtaining FIPS County Numbers
133REST Web Services Guide
Chapter 2: Web Services
Federal Information Processing Standards (FIPS) county numbers are numbers that identify each countyin a state. Note that these numbers are only unique at the state level, not the national level. For moreinformation, see http://www.census.gov.
FIPS county numbers are available for U.S. addresses only.Note:
To obtain FIPS county numbers, Option.OutputRecordType must contain P. For more informationon Option.OutputRecordType, see Output Data Options on page 129.
Table 66: FIPS County Number Output
DescriptionResponse Element
FIPS (Federal Information Processing Standards) county numberUSFIPSCountyNumber
Obtaining Carrier Route Codes
Carrier route codes are unique identifiers assigned to each mail carrier who delivers mail, allowing uniqueidentification of each U.S. delivery route. ValidateAddress can return the code that represents anaddressee's carrier route.
Carrier route codes are available for U.S. addresses only.Note:
To obtain carrier route codes, Option.OutputRecordType must contain P. For more information onOption.OutputRecordType, see Output Data Options on page 129.
Table 67: Carrier Route Code Output
DescriptionResponse Element
Carrier route codeUSCarrierRouteCode
Creating Delivery Point Barcodes
A Delivery Point Barcode (DPBC) is a POSTNET™ barcode representation of the address. It consists of62 bars with beginning and ending frame bars and five bars each for the ZIP + 4® Code, a value calculatedbased on the street address number, and a correction digit. The DPBC allows automated sortation ofletter mail to the carrier level in walk sequence. ValidateAddress generates the data you need to assemblea DPBC.
Delivery Point Barcodes are available for U.S. addresses only. For more information on DeliveryPoint Barcodes, see http://www.usps.com.
Note:
To generate the data needed to assemble a DPBC, Option.OutputRecordType must contain P. Formore information on Option.OutputRecordType, see Output Data Options on page 129.
Table 68: Delivery Point Barcode Output
DescriptionResponse Element
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
Spectrum Technology Platform 9.0134
Universal Addressing Module
For example, if you have the following:
• PostalCode.Base = 49423• PostalCode.Addon = 4506• PostalBarcode = 29• USBCCheckDigit = 2
The assembled barcode would be:
494234506292
Default Options
The following table lists the options that control the format and processing of addresses. These are called"default options" because by default the apply to all addresses. Some of these options can be overriddenfor Canadian addresses. For more information, see Canadian Address Options on page 148.
Table 69: Default Options
DescriptionParameter
Specifies the casing of the output data. One of the following:Option.OutputCasing
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 whether to use separators (spaces or hyphens) inZIP™ Codes or Canadian postal codes.
Option.OutputPostalCodeSeparator
For example, a ZIP + 4® Code with the separator would be20706-1844 and without the separator it would be 207061844.A Canadian postal code with the separator would be P5E"1S7and without the separator it would be P5E1S7.
Yes, use separator (default).Y
No, do not use separator.N
Spaces are used in Canadian postal codes andhyphens in U.S. ZIP + 4® Codes.
Note:
Specifies whether or not to return multinational characters,including diacritical marks such as umlauts or accents. (Notsupported for U.S. addresses).
Option.OutputMultinationalCharacters
No, do not use multinational characters in the output(default). Only standard ASCII characters is returned.
N
Yes, use multinational characters in the output.Y
Indicates whether or not to return multiple address for thoseinput addresses that have more than one possible match.
Option.KeepMultimatch
Yes, return multiple matches (default).Y
No, do not return multiple matches.N
135REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
For more information, see Returning Multiple Matches onpage 139.
Specifies where to place secondary address information forU.S. addresses. Secondary address information refers to
Option.StandardAddressFormat
apartment numbers, suite numbers, and similar designators.For example, in this address the secondary addressinformation is "Apt 10E" and the primary address informationis "424 Washington Blvd".
Apt 10E424 Washington BlvdSpringfield MI 49423
Place both primary and secondary address informationin AddressLine1 (default).
C
Place the primary address information in AddressLine1and the secondary address information inAddressLine2.
S
Place both primary and secondary address informationin AddressLine1 and place dropped information from
D
dual addresses in AddressLine2. A dual address is anaddress that contains both street information and POBox/Rural Route/Highway Contract information. Formore information, see About Dual Address Logic onpage 138.
Specifies how to format city names that have short city nameor non-mailing city name alternatives. Applies to U.S. andCanadian addresses.
Option.OutputShortCityName
Returns the USPS®-approved abbreviation for the city,if there is one. The USPS® provides abbreviations for
Y
city names that are 14 characters long or longer. Cityabbreviations are 13 characters or less and can be usedwhen there is limited space on the mailing label. If thereis no short city name for the city, then the full city nameis returned.
Returns the long city name (default).N
Returns the abbreviated city name only if an abbreviatedcity name is used in the input address. If the input
S
address does not use a short city name, either the longor short city name could be returned, depending onUSPS® regulations for the particular city. Select thisoption if you are performing a CASS™ test.
Output the non-mailing city name (the vanity name) ifthe input city name is a non-mailing city name. For
V
example, "Hollywood" is a non-mailing city name for"Los Angeles". If you do not select this option and theinput city name is a non-mailing city name the longversion of the mailing city is returned.
Spectrum Technology Platform 9.0136
Universal Addressing Module
DescriptionParameter
Specifies the format to use for the country name returned inthe Country output field. For example, if you select English,
Option.OutputCountryFormat
the country name "Deutschland" would be returned as"Germany".
Use English country names (default).E
Use Spanish country names.S
Use French country names.F
Use German country names.G
Use two-letter ISO abbreviation for the countriesinstead of country names.
I
Use Universal Postal Union abbreviation for thecountries instead of country names.
U
Specifies the default country. You should specify the countrywhere most of your addresses reside. For example, if most
Option.HomeCountry
of the addresses you process are in Canada, specify Canada.ValidateAddress uses the country you specify to attemptvalidation when it cannot determine the country from theStateProvince, PostalCode, and Country address fields. Thevalid country names are:
Afghanistan, Albania, Algeria, American Somoa, Andorra,Angola, Anguilla, Antigua And Barbuda, Argentina, Armenia,Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain,Bangladesh, Barbados, Belarus, Belgium, Belize, Benin,Bermuda, Bhutan, Bolivia, Bosnia And Herzegovina,Botswana, Brazil, British Virgin Islands, Brunei Darussalam,Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central AfricanRepublic, Chad, Chile, China, Colombia, Comoros Islands,Congo, Cook Islands, Costa Rica, Cote D'Ivoire, Croatia,Cuba, Cyprus, Czech Republic, Democratic Republic OfCongo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea,Eritrea, Estonia, Ethiopia, Falkland Islands, Faroe Islands,Federated States Of Micronesia, Fiji, Finland, France, FrenchGuiana, Gabon, Gambia, Germany, Ghana, Gibraltar, Greece,Greenland, Grenada, Guadeloupe, Guam, Guatemala,Guinea, Guinea Bissau, Guyana, Haiti, Holy See, Honduras,Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan,Kenya, Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia,Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania,Luxembourg, Macau, Macedonia, Madagascar, Malawi,Malaysia, Maldives, Mali, Malta, Marshall Islands, Martinique,Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar,Namibia, Nauru, Nepal, Netherlands Antilles, New Caledonia,New Zealand, Nicaragua, Niger, Nigeria, Niue, Norway, Oman,Pakistan, Palau, Panama, Papua New Guinea, Paraguay,Peru, Philippines, Pitcairn Islands, Poland, Portugal, PuertoRico, Qatar, Republic Of Georgia, Republic Of Korea,
137REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Republic Of Singapore, Reunion, Romania, Russia, Rwanda,Saint Helena, Saint Kitts And Nevis, Saint Lucia, Saint PierreAnd Miquelon, Saint Vincent And The Grenadines, Samoa,San Marino, Sao Tome And Principe, Saudi Arabia, Senegal,Seychelles, Sierra Leone, Slovakia, Slovenia, SolomonIslands, Somalia, South Africa, Spain, Sri Lanka, Sudan,Surivalue, Swaziland, Sweden, Switzerland, Syria, Tahiti,Taiwan, Tajikistan, Tanzania, Thailand, The Netherlands,Togo, Tonga, Trinidad And Tobago, Tristan Da Cunha,Tunisia, Turkey, Turkmenistan, Turks And Caicos Islands,Tuvalu, Uganda, Ukraine, United Arab Emirates, UnitedKingdom, United States, Uruguay, Uzbekistan, Vanuatu,Venezuela, Vietnam, Virgin Islands (US), Wallis And Futuna,Yemen, Yugoslavia, Zambia, Zimbabwe
Indicates how ValidateAddress should return a match ifmultiple non-blank address lines are present or multiple
Option.DualAddressLogic
address types are on the same address line (U.S. addressesonly).
(Default) USPS® CASS™ regulations determine theaddress returned based on the following order ofpriority:
N
1. PO Box2. Firm3. Highrise4. Street5. Rural Route6. General Delivery
Return a street match, regardless of the address line.S
Return a PO Box match, regardless of the addressline.
P
For more information, see About Dual Address Logic onpage 138.
About Dual Address Logic
For U.S. addresses only, the Option.DualAddressLogic option controls whether ValidateAddress shouldreturn a street match or a PO Box/Rural Route/Highway Contract match when the address contains bothstreet and PO Box/Rural Route/Highway Contract information in the same address line.
The Option.DualAddressLogic option has no effect if the street information is in a different addressline input field than the PO Box/Rural Route/Highway Contract information.
Note:
For example, given the following input address:
AddressLine1: 401 N Main St Apt 1 POB 1City: KempStateProvince: TXPostalCode: 75143
ValidateAddress would return one of the following:
• If Option.DualAddressLogic is set to either N or P, ValidateAddress returns the following:
Spectrum Technology Platform 9.0138
Universal Addressing Module
AddressLine1: PO Box 1City: KempStateProvince: TXPostalCode: 75143-0001
• If Option.DualAddressLogic is set to S, ValidateAddress returns the following:
AddressLine1: 401 N Main St Apt 1City: KempStateProvince: TXPostalCode: 75143-4806
The address data that is not used to standardize the address can be returned in one of two places:
• AddressLine2—The address information not used to standardize the address is returned in theAddressLine2 field if you specify Option.StandardAddressFormat=D. For more information on thisoption, see Default Options on page 135. For example, if you choose to return a street match for dualaddresses,
AddressLine1: 401 N Main St Apt 1AddressLine2: PO Box 1City: KempStateProvince: TXPostalCode: 75143-0001
• AdditionalInputData—If you do not specify Option.StandardAddressFormat=D then the addressinformation not used to standardize the address is returned in the AdditionalInputData field. For moreinformation on this option, see Default Options on page 135. For example, if you choose to return astreet match for dual addresses,
AddressLine1: 401 N Main St Apt 1City: KempStateProvince: TXPostalCode: 75143-0001AdditionalInputData: PO Box 1
Address information that is dropped can be retrieved by setting the Option.StandardAddressFormatoption to D. For more information, see .
Returning Multiple Matches
If ValidateAddress finds multiple address in the postal database that are possible matches for the inputaddress, you can have ValidateAddress return the possible matches. For example, the following addressmatches multiple addresses in the U.S. postal database:
PO BOX 1New York, NY
Options
To return multiple matches, use the options described in the following table.
Table 70: Multiple Match Option
DescriptionParameter
Indicates whether or not to return multiple address for those inputaddresses that have more than one possible match.
Option.KeepMultimatch
Yes, return multiple matches (default).Y
No, do not return multiple matches.N
139REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
A number between 1 and 10 that indicates the maximum number ofaddresses to return.
Option.MaximumResults
The default value is 1.
The difference between Option.Keepmultimatch=N andOption.KeepMultimatch=Y/Option.MaximumResults=1 is that
Note:
a multiple match will return a failure ifOption.KeepMultimatch=N, whereas amultiple match will returnone record if Option.KeepMultimatch=Y andOption.MaximumResults=1.
To identify which output addresses are candidate addresses, you mustspecify a value of Y for Option.OutputFieldLevelReturnCodes. When
Option.OutputFieldLevelReturnCodes
you do this, records that are candidate addresses will have one or more"M" values in the field-level result indicators.
Output
When you choose to return multiple matches, the addresses are returned in the address format youspecify. For information on specifying address format, seeOutput Data Options on page 129. To identifywhich records are the candidate addresses, look for multiple "M" values in the field-level result indicators.For more information, see Field-Level Result Indicators on page 165.
U.S. Address Options
DescriptionParameter
Specifies whether to process U.S. addresses. If you enable U.S. addressprocessing ValidateAddress will attempt to validate U.S. addresses. If
Option.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.
No, do not process U.S. addresses.N
Yes, process U.S. addresses. Default.Y
Specifies which database to use for validating U.S. addresses. Onlydatabases that have been defined in the US Database Resources panelin the Management Console are available.
Option.Database.US
Enhanced Line of Travel (eLOT) processing assigns a Line of Travelsequence code to your addresses. Note that ValidateAddress does not
Option.PerformLOT
sort into eLOT sequence but it provides data (the Line of Travelsequence code) that allows you to sort addresses into eLOT sequence.
To perform eLOT processing you must have the eLOT databaseinstalled.
Spectrum Technology Platform 9.0140
Universal Addressing Module
DescriptionParameter
No, do not perform Line of Travel Processing. Default.N
Yes, perform Line of Travel processing.Y
For a listing of the output fields returned by this option, see EnhancedLine of Travel Output on page 174.
Residential Delivery Indicator (RDI™) processing checks if an addressis a residential address (not a business address). To perform RDI™
processing, you must have the RDI™ database installed.
Option.PerformRDI
If you enable both DPV® and RDI™ processing, RDI™ information is onlyreturned if the address is a valid delivery point. If DPV® does not validatethe address no RDI™ data is returned.
No, do not perform Residential Delivery Indicator processing.Default.
N
Yes, perform Residential Delivery Indicator processing.Y
Enhanced Street Matching (ESM) applies additional matching logic tocorrect misspelled or complex street names and obtain a match. ESM
Option.PerformESM
enables ValidateAddress to validate more addresses but it reducesperformance. You cannot perform ESM when ASM is enabled.
No, do not perform enhanced street matching. Default.N
Yes, perform enhanced street matching.Y
All Street Matching (ASM) applies ESM processing as well as additionalmatching logic to correct errors in street names and obtain a match. It
Option.PerformASM
is effective at matching streets when the first letter of the street isincorrect. ASM provides the best address validation but reducesperformance.
No, do not perform all street matching.N
Yes, perform all street matching. Default.Y
Delivery Point Validation (DPV®) validates that a specific address exists,as opposed to validating that a specific address is within a range of valid
Option.PerformDPV
addresses. CMRA processing checks if an address is for a mailboxrented from a private company, referred to as a Commercial MailReceiving Agent (CMRA).
To perform DPV and CMRA processing, you must have the DPVdatabase installed. The DPV database contains both DPV and CMRAdata.
No, do not perform Delivery Point Validation or CMRAprocessing. Default.
N
Yes, performDelivery Point Validation and CMRA processing.Y
For a listing of the output fields returned by this option, see DPV andCMRA Output on page 175.
The USPS® Locatable Address Conversion System (LACS) allows youto correct addresses that have changed as a result of a rural route
Option.PerformLACSLink
address converting to street-style address, a PO Box renumbering, ora street-style address changing. When enabled, LACSLink processing
141REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
is attempted for addresses that could not be validated, or addresseswere validated and flagged for LACSLink conversion.
To perform LACSLink processing, you must have the LACSLink databaseinstalled.
No, do not attempt LACSLink conversion. Default.N
Yes, attempt LACSLink conversion.Y
For a listing of the output fields returned by this option, see LACSLinkOutput on page 174
The EarlyWarning System (EWS) uses the USPS® EWSFile to validateaddresses that are not in the ZIP + 4® database.
Option.PerformEWS
To perform EWS processing, youmust have the EWS database installed.
If an input address matches an address in the EWS file, ValidateAddresswill return the following record-level result indicators:
• Status="F"• Status.Code="EWSFailure"• Status.Description="Address found in EWS table"
No, do not perform EWS processing. Default.N
Yes, perform EWS processing.Y
Specifies whether to extract the firm name from AddressLine1 throughAddressLine4 and place it in the FirmName output field. This option
Option.ExtractFirm
works in cases where the input record's FirmName field is blank andthere is more than one address line.
Yes, extract the firm name.Y
No, do not extract the firm name. Default.N
To identify firm names in address lines, ValidateAddress scans theaddress lines for keywords and patterns that help it identify which fieldsare address lines and which are FirmName lines. Since this is donebased on patterns, ValidateAddress maymisidentify fields. The followingtips can help ensure optimal firm extraction:
• If possible, place the primary address elements in AddressLine1, thesecondary elements in AddressLine2, Urbanization in AddressLine3,and firm in AddressLine4. If the address has no urbanization code,then place the firm name in AddressLine3 and leave AddressLine4blank. For example,
AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes SoftwareAddressLine4: <blank>
• When you define just two address lines, AddressLine2 is assigned tothe secondary address most of the time. If you want to increase thechance that ValidateAddress will treat AddressLine2 as a firm name,put the firm name in AddressLine3 and leave AddressLine2 blank.
Spectrum Technology Platform 9.0142
Universal Addressing Module
DescriptionParameter
• Numerics in a firm name (such as the "1" in "1 Stop Software") willincrease the likelihood that ValidateAddress will treat the field as anaddress line.
Here are some examples of firm name extraction:
• In this example, AddressLine2 would get extracted into the FirmNameoutput field
FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600AddressLine2: International Goose Feathers inc.
• In this example, AddressLine3 would get extracted into the FirmNameoutput field.
FirmName: <blank>AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes Software
• In this example, AddressLine3 would be placed in theAdditionalInputData output field. The firm name would not be extractedbecause the FirmName input field is not blank.
FirmName: International Goose Feathers Inc.AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600AddressLine3: Pitney Bowes Software
• In this example, no firm name would be extracted because there isonly one non-blank address line, which is always treated as theprimary address element.
FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600
• In this example, AddressLine2 would be treated as a secondaryaddress element because the numeral "1" causes ValidateAddressto treat that field as a secondary address element.
FirmName: <blank>AddressLine1: 4200 Parliament Place Suite 600AddressLine2: Pitney Bowes Software
Specifies whether to extract the urbanization name from AddressLine1through AddressLine4 and place it in the USUrbanName output field.
Option.ExtractUrb
This option works in cases where the input record's USUrbanName fieldis blank and there is more than one address line.
Yes, extract the urbanization name.Y
No, do not extract the urbanization name. Default.N
To identify urbanization names, ValidateAddress scans the addresslines for keywords and patterns that help it identify which fields areaddress lines and which are urbanization name lines. Since this is donebased on patterns, it is possible for ValidateAddress to incorrectly identifyfields. To help ensure optimal urbanization extraction, place the primary
143REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
address elements in AddressLine1, the secondary elements inAddressLine2, Urbanization in AddressLine3, and firm in AddressLine4,if possible. For example,
AddressLine1: A1 Calle AAddressLine2:AddressLine3: URB AlamarAddressLine4: Pitney Bowes Software
Specifies whether to perform SuiteLink™ processing.Option.PerformSuiteLink
SuiteLink corrects secondary address information for U.S. businessaddresses whose secondary address information could not be validated.If SuiteLink processing is enabled, the firm name is matched to a databaseof known firm names and their secondary address information.
For example,
Firm Name: Pitney Bowes SoftwareAddress Line 1: 4200 Parliament PlaceAddress Line 2: STE 1Postal Code: 20706
In this case, SuiteLink processing would change the suite number to thecorrect suite number:
Firm Name: Pitney Bowes SoftwareAddress Line 1: 4200 Parliament PlaceAddress Line 2: STE 600Postal Code: 20706-1844
SuiteLink attempts to correct firm names in addresses where:
• A firm name is present• A valid ZIP Code™, ZIP + 4® Code, and primary number could bedetermined
• A match has been made to a high-rise default record• The secondary address information could not be validated throughnormal processing
To perform SuiteLink™ processing, you must have the SuiteLink™
database installed.
This option takes one of the following values:
No, do not use SuiteLink™. Default.N
Yes, use SuiteLink™ processing.Y
For a listing of fields returned by this option, see SuiteLink Output onpage 176.
Specifies whether to use a street's preferred alias in the output.Option.OutputPreferredAlias
Street name aliases in the United States are alternative names givento sections of a street. There are four types of street name aliases:
• Preferred—A preferred alias is the street name preferred locally. Ittypically applies only to a specific range of addresses on the street.
Spectrum Technology Platform 9.0144
Universal Addressing Module
DescriptionParameter
• Abbreviated—An abbreviated alias is a variation of the street namethat can be used in cases where the length of AddressLine1 is longerthan 31 characters. For example, the street name 1234 BERKSHIREVALLEY RD APT 312A could be abbreviated to 1234 BERKSHIREVLLY RD APT 312A.
• Changed—There has been an official street name change and thealias reflects the new name. For example if SHINGLE BROOK RD ischanged to CANNING DR, then CANNING DR would be a changedalias type.
• Other—The street alias is made up of other names for the street orcommon abbreviations of the street.
The non-alias version of the street name is called the base street name.
If the preferred alias is used in the input then the preferred alias will bethe street name in the output regardless of whether you enable thisoption.
This is one of three options that control how ValidateAddress handlesstreet name aliases. The other two are Option.OutputStreetNameAliasand Option.OutputAbbreviatedAlias.
In most cases, if you select both Option.OutputPreferredAlias andOption.OutputAbbreviatedAlias, and ValidateAddress finds both apreferred and an abbreviated alias in the postal database, theabbreviated alias will be used in the output. The exception to this ruleis if the input street name is a preferred alias. In this case, the preferredalias will be used in the output.
Yes, perform preferred alias processing.Y
No, do not perform preferred alias processing. Default.N
If the input address contains a street name alias of type"changed" the output address will always contain the base streetname regardless of the options you specify.
Note:
Specifies whether to use a street's abbreviated alias in the output if theoutput address line is longer than 31 characters.
Option.OutputAbbreviatedAlias
This is one of three options that control how ValidateAddress handlesstreet name aliases. The other two are Option.OutputStreetNameAliasand Option.OutputPreferredAlias.
If a preferred alias is specified in the input, the output streetname will always be the preferred alias, even if you enableabbreviated street name alias processing.
Note:
Yes, perform abbreviated alias processing.Y
No, do not perform abbreviated alias processing. Default.N
If the input address contains a street name alias of type"changed" the output address will always contain the base streetname regardless of the options you specify.
Note:
Determines the "no stat" status of an address. An address is considered"no stat" if it exists but cannot receive mail, and therefore is not counted
Option.DPVDetermineNoStat
as a delivery statistic on a carrier's route (hence the term "no stat").
145REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Examples include buildings under construction or those that the lettercarrier has identified as not likely to receive mail.
No, do not determine "no stat" status. Default.N
Yes, determine "no stat" status.Y
You must enable DPV processing to use this option.Note:
The result is returned in the DPVNoStat field. For more information seeLACSLink Output on page 174
Determines if the location has been unoccupied for at least 90 days.Option.DPVDetermineVacancy
No, do not determine vacancy. Default.N
Yes, determine vacancy.Y
You must enable DPV processing to use this option.Note:
The result is returned in the DPVVacant field. For more information seeLACSLink Output on page 174
Returns VeriMove detail data in output.Option.ReturnVerimove
No, do not return VeriMove detail data. Default.N
Yes, return VeriMove detail data.Y
Specifies the algorithm to use when determining if an input addressmatches an address in the postal database. One of the following:
Option.StreetMatchingStrictness
The input street name must match the database exactly.E
The matching algorithm is "tight."T
The matching algorithm is "medium" (default).M
The matching algorithm is "loose."L
Specifies the algorithm to use when determining if an input addressmatches an address in the postal database. One of the following:
Option.FirmMatchingStrictness
The input firm name must match the database exactly.E
The matching algorithm is "tight."T
The matching algorithm is "medium" (default).M
The matching algorithm is "loose."L
Specifies the algorithm to use when determining if an input addressmatches an address in the postal database. One of the following:
Option.DirectionalMatchingStrictness
The input directionals, such as the "N" in 123 N Main St.,must match the database exactly.
E
The matching algorithm is "tight."T
The matching algorithm is "medium". Default.M
The matching algorithm is "loose."L
Select thematch condition where a DPV result does NOT cause a recordto fail.
Option.DPVSuccessfulStatusCondition
Spectrum Technology Platform 9.0146
Universal Addressing Module
DescriptionParameter
Full matchF
Partial matchP
Always. Default.A
You must enable DPV processing to use this option.Note:
Treat Commercial Mail Receiving Agency (CMRA)matches as failures?Option.FailOnCMRAMatch
No, do not treat CMRA matches as failures. Default.N
Yes, treat CMRA matches as failures.Y
You must enable DPV processing to use this option.Note:
Specifies where ValidateAddress places Private Mailbox (PMB)information.
Option.StandardAddressPMBLine
Do not include the PMB information in Standard Addressoutput (default).
N
Place the PMB information in AddressLine1. If you specify 1,you must set Option.StandardAddressFormat to either C orD.
1
Place the PMB information in AddressLine2.2
CASS Certified Processing
CASS Certified™ processing also generates the USPS CASS Detailed Report, which contains some ofthe same information as the 3553 report but provides much greater detail about DPV, LACS, and SuiteLinkstatistics. The USPS CASS Detailed Report is not required for postal discounts and does not need tobe submitted with your mailing.
1. Validate Address must be in CASS Certified™ mode. If (Not CASS Certified) appears at the top ofthe window, click the Enable CASS button. The Enforce CASS rules check box will appear.
2. Click Configure CASS 3553. The CASS Report Fields dialog box appears.3. Type the List Processor company name, List Name or ID#, and the Number of Lists being
processed for this job.4. Type the Mailer Name, Address, and City, State, ZIP.5. Click OK.
The List information will appear in Section B and the Mailer information in Section D of the generatedUSPS® CASS Form 3553.
147REST Web Services Guide
Chapter 2: Web Services
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
DescriptionParameter
Specifies whether to process Canadian addresses.If you enable Canadian address processing
Option.PerformCanadianProcessing
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.
Spectrum Technology Platform 9.0148
Universal Addressing Module
DescriptionParameter
No, do not process Canadian addresses.N
Yes, process Canadian addresses(default).
Y
Specifies which database you want to use forvalidating Canadian addresses. To specify a
Option.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
Option.CanFrenchFormat
directional. The following example shows anaddress formatted in English and French:
English: 123 Main St WFrench: 123 Rue Main O
The parameter controls the formatting of theaddress. It also affects the spelling of the directionalbut not spelling of the suffix.
Use the street suffix returned by the matchingprocess to determine the language. The street
C
suffix returned by thematching process, whichis used internally by ValidateAddress duringprocessing, may be different from that in theinput address. Ambiguous records areformatted like the input. Default. All addressesin Quebec are formatted using French.
Use the Canadian database to determine thelanguage. The Canadian database contains
S
data from the Canada Post Corporation(CPC). All addresses in Quebec are formattedusing French.
Use the CanLanguage input field to determinethe language. If there is a non-blank value in
T
this field the address are formatted usingFrench.
For English addresses, specifies the defaultapartment label to use in the output if there is no
Option.CanFrenchFormat
apartment label in the input address. This settingis ignored if you specifyOption.CanStandardAddressFormat=F.
Use "Apt" as the label. Default.Apt
Use "Apartment" as the label.Apartment
Use "Suite" as the label.Suite
Use "Unit" as the label.Unit
149REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
For French addresses, specifies the defaultapartment label to use in the output if there is no
Option.CanFrenchApartmentLabel
apartment label in the input address. This settingis ignored if you specifyOption.CanStandardAddressFormat=F.
Use "App" as the label. Default.App
Use "Appartement" as the label.Appartement
Use "Bureau" as the label.Bureau
Use "Suite" as the label.Suite
Use "Unite" as the label.Unite
In cases where the house number and postal codeare both valid but in conflict, you can force the
Option.CanPreferHouseNum
postal code to be corrected based on the housenumber by specifyingOption.CanPreferHouseNum=Y. If you do notselect this option the house number is changed tomatch the postal code.
Change the house number to match thepostal code. Default.
N
Change the postal code to match thehouse number.
Y
Specifies whether or not to return the city aliaswhen the alias is in the input address. This option
Option.CanOutputCityAlias
is disabled when you specifyOption.CanOutputCityFormat=D.
Output the city alias when the city alias isin the input. Default.
Y
Never output the city alias even if it is inthe input.
N
Specifies whether or not non-civic keywords areabbreviated in the output. For example, Post OfficeBox vs. PO Box.
Option.CanNonCivicFormat
Abbreviate non-civic keywords. Default.A
Do not abbreviate non-civic keywords. Thefull keyword is used.
F
Specifies whether or not to use SERP options.Option.EnableSERP
Enable SERP options.Y
Do not enable SERP options. Default.N
Specifies where to place secondary addressinformation in the output address. Secondary
Option.CanStandardAddressFormat
address information refers to apartment numbers,suite numbers, and similar designators.
Spectrum Technology Platform 9.0150
Universal Addressing Module
DescriptionParameter
Place apartment information in the locationspecified in the. Default.
D
Place apartment information at the at theend of the AddressLine1 field.
B
Place the apartment number only (no label)at the beginning of the AddressLine1 field.For example, 400-123 Rue Main
F
Place the apartment number and label atthe beginning of the AddressLine1 field. Forexample, Apt 400 123 Rue Main
E
Place apartment information on a separateline.
S
Place apartment information in the samelocation as the input address.
S
Specifies whether to use the long, medium, or shortversion of the city if the city has a long name. Forexample,
Option.CanOutputCityFormat
Long: BUFFALO HEAD PRAIRIEMedium: BUFFALO-HEAD-PRShort: BUFFALO-HD-PR
Use the default option specified by theOption.OutputShortCityName parameter.
D
Default. If you specifyOption.OutputShortCityName=V, the city isformatted as if you select for this option(see below) andY forCanOutputCityAlias.
Output short city name.S
Output the long city name.L
Output the medium city name.M
Use the same city format as used in theinput address. Output is L, M, or S.
I
Specifies where to place rural route deliveryinformation. An example of an address with ruralroute delivery information is:
Option.CanRuralRouteFormat
36 GRANT RD RR 3ANTIGONISH NS
In this address, "RR 3" is the rural route deliveryinformation.
Place rural route delivery information on thesame line as the address, after the addressinformation. Default. For example,
36 GRANT RD RR 3
A
151REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Place rural route delivery information on aseparate address line. For example,
36 GRANT RDRR 3
S
Specifies where to place station information. Anexample of an address with station information is:
PO BOX 8625 STN AST. JOHN'S NL
Option.CanDeliveryOfficeFormat
Place station information in the samelocation as it is in the input address. Default.
I
Place station information on the same lineas the address, after the addressinformation. For example,
PO BOX 8625 STN A
A
Place station information on a separateaddress line. For example,
PO BOX 8625STN A
S
Specifies whether ValidateAddress should returna street match or a PO Box/non-civic match when
Option.CanDualAddressLogic
the address contains both civic and non-civicinformation. One of the following:
Use DualAddressLogic Global Option.Default.
D
Match to PO Box or other non-streetdata.
P
Match to street.S
For example, given the following input address:
AddressLine1: 36 GRANT RDAddressLine2: RR 4City: ANTIGONISHStateProvince: NS
ValidateAddress would return one of the following:
• If Option.CanDualAddressLogic is set to S,ValidateAddress returns the following:
AddressLine1: 36 GRANT RDAddressLine2: RR 3City: ANTIGONISHStateProvince: NSPostalCode: B2G 2L1
• If Option.CanDualAddressLogic is set to P,ValidateAddress returns the following:
Spectrum Technology Platform 9.0152
Universal Addressing Module
DescriptionParameter
AddressLine1: RR 4City: ANTIGONISHStateProvince: NSPostalCode: B2G 2L2
The address data that is not used to standardizethe address is returned in theAdditionalInputDatafield. For more information on this option, seeOutput Data Options on page 129.
SERP Processing
1. Validate Address must be in SERP Certified™ mode. If (Not SERP Certified) appears at the top ofthe window, click the Enable SERP settings button. The Configure SERP box will appear.
2. Click Configure SERP. The SERP Report Fields dialog box appears.3. Type your merchant CPC number.4. Type the mailer Name, Address, and City, State, ZIP.5. Click OK.6. In Enterprise Designer, drag the SERPReport from the Reports pallet to the canvas.
7. Double-click the SERPReport icon on the canvas.8. On the Stages tab, ensure that the Validate Address checkbox is checked. Note that if you have
renamed the Validate Address stage to something else, you should check the box with the nameyou have given the address validation stage.
9. On the Parameters tab, select the format for the report. You can create the report in PDF, HTML,or plain text format. PDF format is the default.
10. Click OK.
Obtaining SERP Return Codes
SERP return codes indicate the quality of the input address as determined by the Canada Post's SoftwareEvaluation and Recognition Program regulations.
153REST Web Services Guide
Chapter 2: Web Services
To obtain SERP return codes, specify Option.OutputRecordType=P. For more information onOption.OutputRecordType, see Output Data Options on page 129.
SERP return codes are provided in the following output field.
Table 71: SERP Return Code Output
DescriptionResponse Element
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:
DescriptionParameter
Specifies whether to process internationaladdresses (addresses outside the U.S. and
Option.PerformInternationalProcessing
Canada). If you enable international addressprocessing ValidateAddress will attempt to validateinternational addresses. If you disable internationaladdress processing, international addresses willfail, meaning they is returned with an "F" in theStatus output field. The output field Status.Codewill say "DisabledCoder." If you are not licensed
Spectrum Technology Platform 9.0154
Universal Addressing Module
DescriptionParameter
for international address processing you mustdisable international address processing in orderfor your jobs to complete successfully, regardlessof whether or not they contain internationaladdresses.
You must have a valid license forinternational address processing to
Note:
successfully process internationaladdresses. If you enable internationaladdress processing but are not licensedfor this feature, or your license has expired,you will receive an error.
No, do not process internationaladdresses.
N
Yes, process international addresses(default).
Y
Specifies which database you want to use forvalidating international addresses. To specify a
Option.Database.International
database for international address validation, selecta database in the Database drop-down list. Onlydatabases that have been defined in the INTLDatabase Resources panel in the ManagementConsole are available.
By default, ValidateAddress provides a balance ofgood address matching accuracy with good
Option.InternationalCityStreetSearching
performance. If you are willing to trade matchingaccuracy for faster performance, use theOption.InternationalCityStreetSearching parameterto increase processing speed. When you do this,some accuracy is lost. This option only controlsperformance for addresses outside the U.S. andCanada. This setting affects a small percentage ofrecords, mostly addresses in the U.K. There is noperformance control for U.S. and Canadian addressprocessing.
If you use GetCandidateAddresses, the candidateaddresses returned by GetCandidateAddressesmay differ from the multiple matches returned byValidateAddress if you set the performance tuningoption for international addresses to any value otherthan 100.
To control performance, specify a value from 0 to100. A setting of 100 maximizes accuracy while asetting of 0 maximizes speed. The default is 100.
This option enables ValidateAddress to search theAddressLine input fields for the city, state/province,
Option.AddressLineSearchOnFail
postal code, and country when the address cannotbe matched using the values in the City,StateProvince, and PostalCode input fields.
155REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Consider enabling this option if your inputaddresses have the city, state/province, and postalcode information in the AddressLine fields.
Consider disabling this option if your inputaddresses use the City, State/Province andPostalCode fields. If you enable this option andthese fields are used, there is an increasedpossibility that ValidateAddress will fail to correctvalues in these fields (for example a misspelledcity name).
No, do not search the AddressLine fields.N
Yes, search the address line fields.Default.
Y
ResponseThe output from ValidateAddress contains different information depending on the output categories youselect.
Standard Address OutputStandard address output consists of four lines of the address which correspond to how the addresswould appear on an actual address label. City, state/province, postal code, and other data is also includedin standard address output. ValidateAddress returns standard address output for validated addressesif you set Option.OutputRecordType=A. Standard address fields are always returned for addresses thatcould not be validated. For non-validated addresses, the standard address output fields contain theaddress as it appeared in the input ("pass through" data). If you want ValidateAddress to standardizeaddress according to postal authority standards when validation fails, specifyOption.OutputFormattedOnFail=Y in your request.
Table 72: Standard Address Output
DescriptionResponse Element
Input data not used by ValidateAddress. For more information, seeAbout AdditionalInputData on page 178.
AdditionalInputData
If the address was validated, the first line of the validated andstandardized address. If the address could not be validated, the firstline of the input address without any changes.
AddressLine1
If the address was validated, the second line of the validated andstandardized address. If the address could not be validated, the secondline of the input address without any changes.
AddressLine2
If the address was validated, the third line of the validated andstandardized address. If the address could not be validated, the thirdline of the input address without any changes.
AddressLine3
If the address was validated, the fourth line of the validated andstandardized address. If the address could not be validated, the fourthline of the input address without any changes.
AddressLine4
Spectrum Technology Platform 9.0156
Universal Addressing Module
DescriptionResponse Element
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
The country in the format determined by what you selected in:Country
• ISO Code• UPU Code• English• French• German• Spanish
For U.K. addresses only, a subdivision of a firm. For example,Engineering Department.
DepartmentName
The validated firm or company name.FirmName
The validated ZIP Code™ or postal code.PostalCode
The 4-digit add-on part of the ZIP Code™. For example, in the ZIP Code™
60655-1844, 1844 is the 4-digit add-on. (U.S. addresses only.)PostalCode.AddOn
The 5-digit ZIP Code™; for example 20706 (U.S. addresses only).PostalCode.Base
The validated state or province abbreviation.StateProvince
The validated urbanization name. (U.S. addresses only.)USUrbanName
Parsed Address Elements OutputOutput addresses are formatted in the parsed address format if you set Option.OutputRecordType=E.If you want ValidateAddress to return formatted data in the Parsed Address format when validation fails(that is, a normalized address), specify Option.OutputFormattedOnFail=Y.
If you want ValidateAddress to always return parsed input data regardless of whether or notvalidation is successful, specify Option.OutputRecordType=I. For more information, see ParsedInput on page 159.
Note:
Table 73: Parsed Address Output
DescriptionResponse Element
Input data not used by ValidateAddress. For moreinformation, see About AdditionalInputData onpage 178.
AdditionalInputData
Apartment designator (such as STE or APT), forexample: 123 E Main St APT 3
ApartmentLabel
Secondary apartment designator, for example: 123E Main St APT 3, 4th Floor
ApartmentLabel2
157REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
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
In this release, this field will always beblank.
Note:
Delivery installation name (Canadian addressesonly)
CanadianDeliveryInstallationAreaName
Delivery installation qualifier (Canadian addressesonly)
CanadianDeliveryInstallationQualifierName
Delivery installation type (Canadian addresses only)CanadianDeliveryInstallationType
Validated city nameCity
Country. Format is determined by what youselected in :
Country
• ISO Code• UPU Code• English• French• German• Spanish
For U.K. addresses only, a subdivision of a firm.For example, Engineering Department.
DepartmentName
The validated firm or company nameFirmName
House number, for example: 123 E Main St Apt 3HouseNumber
Leading directional, for example: 123 E Main StApt 3
LeadingDirectional
Post office box number. If the address is a ruralroute address, the rural route box number willappear here.
POBox
Validated postal code. For U.S. addresses, this isthe ZIP Code.
PostalCode
Private mailbox indicator.PrivateMailbox
The type of private mailbox. Possible valuesinclude:
PrivateMailbox.Type
• Standard• Non-Standard
Spectrum Technology Platform 9.0158
Universal Addressing Module
DescriptionResponse Element
This replaces PrivateMailboxType (noperiod in field name). Please modify yourAPI calls accordingly.
Note:
Rural Route/Highway Contract indicatorRRHC
Validated state or province nameStateProvince
Street name, for example: 123 E Main St Apt 3StreetName
Street suffix, for example: 123 E Main St Apt 3StreetSuffix
Trailing directional, for example: 123 PennsylvaniaAve NW
TrailingDirectional
USPS® urbanization name. Puerto Rican addressesonly.
USUrbanName
Parsed InputThe output can include the input address in parsed form. This type of output is referred to as "parsedinput." Parsed input fields contain the address data that was used as input regardless of whether or notValidateAddress validated the address. Parsed input is different from the "parsed address elements"output in that parsed address elements contain the validated address if the address could be validated,and, optionally, the input address if the address could not be validated. Parsed input always containsthe input address regardless of whether or not ValidateAddress validated the address.
To include parsed input fields in the output, set Option.OutputRecordType=I.
Table 74: Parsed Input
DescriptionResponse Element
Apartment designator (such as STE or APT), forexample: 123 E Main St APT 3
ApartmentLabel.Input
Apartment number, for example: 123 E Main StAPT 3
ApartmentNumber.Input
Delivery installation name (Canadian addressesonly)
CanadianDeliveryInstallationAreaName.Input
Delivery installation qualifier (Canadian addressesonly)
CanadianDeliveryInstallationQualifierName.Input
Delivery installation type (Canadian addresses only)CanadianDeliveryInstallationType.Input
Validated city nameCity.Input
Country. Format is determined by what youselected in:
Country.Input
• ISO Code• UPU Code• English• French
159REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
• German• Spanish
The validated firm or company nameFirmName.Input
House number, for example: 123 E Main St Apt 3HouseNumber.Input
Leading directional, for example: 123 E Main StApt 3
LeadingDirectional.Input
Post office box number. If the address is a ruralroute address, the rural route box number willappear here.
POBox.Input
Validated postal code. For U.S. addresses, this isthe ZIP Code.
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
Trailing directional, for example: 123 PennsylvaniaAve NW
TrailingDirectional.Input
USPS® urbanization nameUSUrbanName.Input
Postal Data OutputIf Option.OutputRecordType contains P then the following fields are returned in the output.
Table 75: Postal Data Output
DescriptionResponse Element
Validation/correction return code (Canadian addresses only). For moreinformation, see Obtaining SERP Return Codes on page 153.
CanadianSERPCode
For addresses in France only, a numeric code that represents the street.For information about Hexavia codes, see www.laposte.fr.
IntHexaviaCode
For addresses in France only, a numeric code that represents the city.For a listing of INSEE codes, see www.insee.fr.
IntINSEECode
Spectrum Technology Platform 9.0160
Universal Addressing Module
DescriptionResponse Element
The two-digit delivery point portion of the delivery point barcode (U.S.addresses only) For more information, see Creating Delivery PointBarcodes on page 134.
PostalBarCode
Indicates whether or not alternate address matching logic was used, andif so which logic was used (U.S. addresses only). One of the following:
USAltAddr
No alternate address scheme used.null
Delivery point alternate logic was used.D
Enhanced highrise alternate match logic was used.E
Small town default logic was used.S
Unique ZIP Code logic was used.U
Check-digit portion of the 11-digit delivery point barcode (U.S. addressesonly). For more information, see Creating Delivery Point Barcodes onpage 134.
USBCCheckDigit
Carrier route code (U.S. addresses only). For more information, seeObtaining Carrier Route Codes on page 134.
USCarrierRouteCode
Congressional district (U.S. addresses only). For more information, seeObtaining Congressional Districts on page 133.
USCongressionalDistrict
County name (U.S. addresses only). For more information, seeObtainingCounty Names on page 133.
USCountyName
The finance number in which the address resides (U.S. addresses only).The finance number is a number assigned by the USPS to an area that
USFinanceNumber
covers multiple ZIP Codes. ValidateAddress will successfully validatean address only if its finance number matches the finance number of thecandidate address in the U.S. Database.
FIPS (Federal Information Processing Standards) county number (U.S.addresses only). For more information, see Obtaining FIPS CountyNumbers on page 133.
USFIPSCountyNumber
Indicates whether or not the address is a candidate for LACSLink
conversion (U.S. addresses only). One of the following:USLACS
Yes, the address is a candidate for LACSLink processing. If LACSLink
is enabled, ValidateAddress will attempt to convert the addressY
using the LACSLink database. If the conversion attempt issuccessful, the output address is the new address obtained fromthe LACSLink database. If the attempt is not successful, the addresswill not be converted.
No, the address is not a candidate for LACSLink processing.LACSLink processing may still be attempted if LACSLink processing
N
is requested, the LACSLink database is installed, and one of thefollowing is true:
• The address matches to a Rural Route address and theRecordType.Default field returns a Y.
• The input address could not be matched to any address in theU.S. Postal Database (Failures due to multiple matches are notLACSLink candidates.)
161REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
A six-character alphanumeric value that groups together ZIP Codes thatshare the same primary city. For example, addresses with the followingtwo last lines would have the same last line number:
USLastLineNumber
Chantilly VA 20151 Chantilly VA 20152
Result IndicatorsResult indicators provide information about the kinds of processing performed on an address. There aretwo types of result indicators:
• Record-Level Result Indicators on page 162• Field-Level Result Indicators on page 165
Record-Level Result Indicators
Record-level result indicators provide data about the results of ValidateAddress processing for eachrecord, such as the success or failure of the match attempt, which coder processed the address, andother details. The following table lists the record-level result indicators returned by ValidateAddress.
Table 76: Record Level Indicators
DescriptionResponse Element
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 beingreturned. Range is from zero (0) to 100; zero indicates failure,
Confidence
100 indicates a very high level of confidence that the matchresults are correct. For multiple matches, the confidence levelis 0. For details about how this number is calculated, seeIntroduction to the Validate Address ConfidenceAlgorithm on page 252.
If no match was found, which address component could notbe validated:
CouldNotValidate
• ApartmentNumber• HouseNumber• StreetName• PostalCode• City• Directional• StreetSuffix• Firm• POBoxNumber• RuralRoute
More than one component may be returned, in acomma-separated list.
Note:
Spectrum Technology Platform 9.0162
Universal Addressing Module
DescriptionResponse Element
The category of address matching available. This is always"A" for U.S. and Canadian addresses. One of the following:
CountryLevel
The address is in a country for which there is highlydetailed postal data available. Addresses in this match
A
level can have the following address elements validatedand corrected, and added if missing from the input:
• Postal code• City name• State/county name• Street address elements• Country name.
The address is in a country for which there is a mediumlevel of postal data available. Addresses in this match
B
level can have the following address elements validatedand corrected, and added if missing from the input:
• Postal code• City name• State/county name• Country name
The address is in a country for which the postal data isleast detailed. Addresses in this match level can havethe following actions performed on them:
C
• Validate and correct country name (cannot supplymissing country name)
• Validate the format of the postal code (cannot supplymissing postal code or validate the code)
MatchScore provides an indication of the degree to which theoutput address is correct. It is significantly different from
MatchScore
Confidence in that Confidence is indicates how much theinput address changed to obtain a match, whereas themeaning of Match Score varies between U.S. and non-U.S.addresses.
For U.S. addresses, MatchScore is a one-digit score on ascale of 0 to 9 that reflects the closeness of the street-namematch (after transformations by ValidateAddress, if any). Zeroindicates an exact match and 9 indicates the least likelymatch. If no match was found, this field is blank.
For non-U.S. and non-Canadian addresses, MatchScore isa five-digit score, with a maximum value of 00999. Highernumbers indicates a closer match.
This field does not apply to Canadian addresses.
Note that you cannot equate match scores from U.S.addresses with those of non-U.S. addresses. For example,a match score of 4 for a U.S address does not indicate thesame level of match as a 00004 for a non-U.S. address.
163REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
The Validate Address and AdvancedMatchingModulecomponents both use the MatchScore field. The
Note:
MatchScore field value in the output of a dataflow isdetermined by the last stage to modify the valuebefore it is sent to an output stage. If you have adataflow that contains Validate Address and AdvancedMatching Module components and you want to seethe MatchScore field output for each stage, use aTransformer stage to copy the MatchScore value toanother field. For example, Validate Address producesan output field called MatchScore and then aTransformer stage copies the MatchScore field fromValidate Address to a field called AddressMatchScore.When the matcher stage runs it populates theMatchScore field with the value from thematcher andpasses through the AddressMatchScore value fromValidate Address.
If multiple matches were found, indicates the number ofrecords that are possible matches.
MultimatchCount
Indicates which address component had multiple matches, ifmultiple matches were found:
MultipleMatches
• Firm• LeadingDirectional• PostalCode• StreetName• StreetSuffix• TrailingDirectional• Urbanization
More than one component may be returned, in acomma-separated list.
Note:
Which address coder processed the address:ProcessedBy
U.S. address coderUSA
Canadian address coderCAN
International address coderINT
Type of address record, as defined by U.S. and Canadianpostal authorities (supported for U.S. and Canadian addressesonly):
RecordType
• FirmRecord• GeneralDelivery• HighRise• PostOfficeBox• RRHighwayContract• Normal
Code indicating the "default" match:RecordType.Default
Spectrum Technology Platform 9.0164
Universal Addressing Module
DescriptionResponse Element
The address matches a default record.Y
The address does not match a default record.null
Reports the success or failure of the match attempt. Formultiple matches, this field is "F" for all the possible matches.
Status
Successnull
FailureF
Reason for failure, if there is one. For multiple matches, allpossible matches is "MultipleMatchesFound."
Status.Code
• DisabledCoder• InsufficientInputData• MultipleMatchesFound• UnableToValidate
Description of the problem, if there is one.Status.Description
This value will appear ifStatus.Code=MultipleMatchesFound.
Possible Multiple AddressesFound
This value will appear ifStatus.Code=UnableToValidate.
Address Not Found
This value will appear ifStatus.Code=DisabledCoder.
PerformUSProcessing disabled
This value will appear ifStatus.Code=DisabledCoder.
PerformCanadianProcessingdisabled
This value will appear ifStatus.Code=DisabledCoder.
PerformInternationalProcessingdisabled
Field-Level Result Indicators
Field-level result indicators describe how ValidateAddress handled each address element. Field-levelresult indicators are returned in the qualifier "Result". For example, the field-level result indicator forHouseNumber is contained in HouseNumber.Result.
To enable field-level result indicators, . For more information on this option, see Output Data Optionson page 129.
The following table lists the field-level result indicators. If a particular field does not apply to an address,the result indicator may be blank.
Table 77: Field-Level Result Indicators
DescriptionResponse Element
These result codes apply to international addresses only.AddressRecord.Result
Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field.
M
165REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Standardized. This option includes any standardabbreviations.
S
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
ApartmentLabel.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.
A
Corrected. U.S. and Canadian addresses only.C
Dropped. The field provided on input was removed. U.S. andCanadian addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
F
Pass-through. The data was not used in the validation process,but it was preserved in the output. U.S. and Canadianaddresses only.
P
The apartment label is required but is missing from the inputaddress. U.S. addresses only.
R
Standardized. This option includes any standard abbreviations.S
Unmatched. Does not apply to Canadian addresses.U
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
Corrected. Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
Spectrum Technology Platform 9.0166
Universal Addressing Module
DescriptionResponse Element
City.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
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
Standardized. This option includes any standard abbreviations.Does not apply to U.S. addresses.
S
Unmatched. Does not apply to Canadian addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
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
Validated. The data was confirmed correct and remainedunchanged from input.
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
Corrected. Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
167REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
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
Validated. The data was confirmed correct and remainedunchanged from input.
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
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
F
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
Standardized. This option includes any standard abbreviations.S
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
Corrected. Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
F
Spectrum Technology Platform 9.0168
Universal Addressing Module
DescriptionResponse Element
Multiple matches. The input address matched multiple recordsin the postal database, and each matching record has adifferent value in this field. U.S. addresses only.
M
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
The P.O. Box number is required but is missing from the inputaddress. U.S. addresses only.
R
Standardized. This option includes any standard abbreviations.S
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
PostalCode.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.
A
Corrected. U.S. and Canadian addresses only.C
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
These result codes apply to international addresses only.PostalCodeCity.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
Standardized. This option includes any standardabbreviations.
S
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
169REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
These result codes apply to U.S. addresses only.PostalCode.Source
The ZIP Code™ in the input was verified by usingUSPS® Finance Number groupings.
FinanceNumber
The ZIP Code™ in the input address was correctedbecause the USPS® redrew ZIP Code™ boundariesand the address is now in a different ZIP Code™.
ZIPMOVE
PostalCode.Type The ZIP Code™ contains only PO Box addresses. U.S.addresses only.
P
The ZIP Code™ is a unique ZIP Code™ assigned to aspecific company or location. U.S. addresses only.
U
The ZIP Code™ is for military addresses. U.S. addressesonly.
M
The ZIP Code™ is a standard ZIP Code™.null
RRHC.Result Corrected. Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Multiple matches. The input address matched multiple recordsin the postal database, and each matching record has adifferent value in this field. U.S. addresses only.
M
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
The rural route/highway contract is required but is missing fromthe input address. U.S. addresses only.
R
Standardized. This option includes any standard abbreviations.U.S. and Canadian addresses only.
S
Unmatched. U.S. and Canadian addresses only.U
Validated. The data was confirmed correct and remainedunchanged from input. U.S. and Canadian addresses only.
V
These result codes apply to U.S. addresses only.RRHC.Type
The address is a Highway Contract address.HC
The address is a Rural Route address.RR
StateProvince.Result Appended. The field was added to a blank input field. U.S.and Canadian addresses only.
A
Corrected. U.S. addresses only.C
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
Spectrum Technology Platform 9.0170
Universal Addressing Module
DescriptionResponse Element
The state is required but is missing from the input address.U.S. addresses only.
R
Standardized. This option includes any standard abbreviations.Does not apply to U.S. addresses.
S
Unmatched. Does not apply to Canadian addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
Indicates the result of abbreviated alias processing. One of the following:StreetName.AbbreviatedAlias.Result
No abbreviated alias processing attempted.null
The StreetName field contains the base street name.B
The standardized address length is less than 31 charactersso the StreetName field contains the base name.
L
No abbreviated alias found.N
An abbreviated alias was found for input address. TheStreetName field contains the abbreviated alias.
Y
This result code applies to U.S. addresses only.StreetName.Alias.Type
In previous releases this field was named StreetName.AliasTypewith no "." between "Alias" and "Type." This old name is
Note:
obsolete. Please update your processes to use the new nameStreetName.Alias.Type.
The alias is an abbreviation of the street name. Forexample, HARTS-NM RD is an abbreviated alias forHARTSVILLE NEW MARLBORO RD.
Abbreviated
There has been an official street name change and thealias reflects the new name. For example if SHINGLE
Changed
BROOKRD is changed to CANNINGDR, then CANNINGDR would be a changed alias type.
The street alias is made up of other names for the streetor common abbreviations of the street.
Other
171REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
The street alias is the locally preferred alias. For example,a street is named "South Shore Dr." because it runs along
Preferred
the southern shore of a lake, not because it is south ofa municipal demarcation line. So, "South" is not apredirectional in this case and should not be shorted to"S". So, "South Shore Dr." would be the preferred alias.
Indicates the result of preferred alias processing. One of the following:StreetName.PreferredAlias.Result
No preferred alias processing attempted.null
Preferred alias processing was not attempted because theinput addressmatched to an alias. Preferred alias processingis only attempted for base addresses.
A
No preferred alias found.N
A preferred alias was found for the input address. TheStreetName field contains the preferred alias.
Y
StreetName.Result Appended. The field was added to a blank input field. Canadianaddresses only.
A
Corrected. U.S. and Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
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
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
StreetSuffix.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.
A
Corrected. U.S. and Canadian addresses only.C
Dropped. The field provided on input was removed. U.S. andCanadian addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
F
Spectrum Technology Platform 9.0172
Universal Addressing Module
DescriptionResponse Element
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
Standardized. This option includes any standard abbreviations.S
Unmatched. Does not apply to U.S. addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
TrailingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.
A
Corrected. U.S. and Canadian addresses only.C
Dropped. The field provided on input was removed. U.S. andCanadian addresses only. For more information, see AboutAdditionalInputData on page 178.
D
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
F
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
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
These result codes apply to U.S. addresses only.USUrbanName.Result
Appended. The field was added to a blank input field.A
Corrected.C
Multiple. The input address matched multiple records in thepostal database, and each matching record has a differentvalue in this field.
M
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
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:
173REST Web Services Guide
Chapter 2: Web Services
Enhanced Line of Travel Output
Enhanced Line of Travel processing produces the following output.
DescriptionResponse Element
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
DescriptionResponse Element
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
Spectrum Technology Platform 9.0174
Universal Addressing Module
DescriptionResponse Element
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
DescriptionResponse Element
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
DescriptionResponse Element
Indicates the results of Delivery Point Validation (DPV) processing.DPV
DPV confirmed.Y
Address is not deliverable.N
The primary number was validated but the secondarynumber could not be confirmed.
S
The primary number was validated but the secondarynumber was missing from input.
D
The address matches multiple valid delivery points.M
The address could not be confirmed because the addressdid not code at the ZIP + 4® level.
U
The address caused a false-positive violation.V
Indicates if the address is a Commercial Mail Receiving Agency (CMRA)CMRA
Yes, the address is a CMRA.Y
No, the address is not a CMRA.N
175REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
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
DescriptionResponse Element
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
Spectrum Technology Platform 9.0176
Universal Addressing Module
DescriptionResponse Element
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
DescriptionResponse Element
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
177REST Web Services Guide
Chapter 2: Web Services
About AdditionalInputDataValidateAddress ignores some input data during the address standardization process. This extraneousdata (sometimes referred to as "dropped data") is returned in the AdditionalInputData. Some examplesof dropped data include:
• Delivery instructions (for example, "Leave at back door")• Phone numbers (for example, "555-135-8792")• Attention lines (for example, "Attn: John Smith")
Data such as this is generally not embedded in an address. If it is embedded, ValidateAddress canusually identify this extraneous data and return it in the AdditionalInputData.
ValidateAddress does not return dropped data from split indicia addresses. A split indicia addressis one where a primary address is split betweenmultiple address lines. For example, if the primary
Note:
address is "1 Green River Valley Rd" then the following would be a split indicia version of thisaddress: 1 Green River Valley Rd 01230
If there is more than one piece of dropped data in an address, each piece of data is separated by asemicolon and a space ("; ") for U.S. addresses and a space for addresses outside the U.S. The orderof dropped data in AdditionalInputData is:
1. Care of, mail stop (U.S. addresses only)2. Other extraneous data found on address lines3. Entire unused data lines
For example, if this is the input address:
123 Main St C/O John SmithApt 5 Drop at back [email protected]
Then AdditionalInputData would contain:
C/O John Smith; Apt 5 Drop At Back Dock; 555-123-4567; [email protected]; 555-123-4567
ValidateAddress can handle the following types of extraneous data:
• Care Of Data on page 178• Extraneous Data on Its Own Address Line on page 178• Extraneous Data Within an Address Line on page 179• Dual Addresses on page 180
Care Of Data
For U.S. addresses only, "care of" data is returned in AdditionalInputData. The following addressescontain examples of "care of" data:
123 Main St C/O John SmithApt 505674
123 Main StApt 5 ATTN John Smith05674
123 Main St Apt 5MailStop 205674
Extraneous Data on Its Own Address Line
ValidateAddress returns extraneous data on its own address line for U.S. and Canadian addresses.
Spectrum Technology Platform 9.0178
Universal Addressing Module
For U.S. addresses, ValidateAddress uses the first two non-blank address lines to perform addressstandardization, unless either the firm name extraction or urbanization code extraction options are enabled(see Address Line Processing for U.S. Addresses on page 129 for more information). Data on otheraddress lines is returned in AdditionalInputData. In the following address, "John Smith" would be returnedin AdditionalInputData because it is in the third non-blank address line and ValidateAddress only usesthe first two non-blank address lines for U.S. addresses.
123 Main StApt 5John Smith05674
If one of either of the first two non-blank address lines contains extraneous data, that data is returnedin AdditionalInputData. For example, in the following addresses "John Smith" would be returned inAdditionalAddressData.
123 Main StJohn Smith05674
John Smith123 Main St05674
In the following address both "John Smith" and "Apt 5" would both be returned in AdditionalInputData."John Smith" would be returned because it is extraneous data in one of the first two address lines and"Apt 5" would be returned because U.S. address data must be in the first two non-blank address lines.
John Smith123 Main StApt 505674
Extraneous Data Within an Address Line
Extraneous data that is within an address line is returned in AdditionalInputData. For example, in thefollowing addresses "John Smith" would be returned in AdditionalInputData.
123 Main St John Smith05674
123 Main St Apt 5 John Smith05674
123 Main St John SmithApt 505674
123 Main StApt 5 John Smith05674
For U.S. addresses, only extraneous data at the end of the address line is returned in AdditionalInputData.Extraneous data that is not at the end of an address line is not returned for U.S. addresses. For example,in the following addresses "John Smith" is not returned.
John Smith 123 Main St05674
123 Main John Smith St05674
179REST Web Services Guide
Chapter 2: Web Services
The AdditionalInputData will sometimes contain the original street name or suffix if the street name waschanged to obtain a match and the street name or suffix was at the end of a line. For example thisaddress:
Pitney Bowes Software4200 ParlamentLanham MD
ValidateAddress would correct the spelling of the street name and add the suffix, returning "4200Parliament Pl" as the corrected street address and "Parlament" in AdditionalInputData.
Dual Addresses
A dual address is an address that contains both street and PO Box/Rural Route/Highway Contractinformation. Depending on the processing options you select, the portion of the dual address that is notused for address standardization may be returned in AdditionalInputData. For more information, seeAbout Dual Address Logic on page 138.
ValidateAddressGlobalValidateAddressGlobal provides enhanced address standardization and validation for addresses outsidethe U.S. and Canada. ValidateAddressGlobal can also validate addresses in the U.S. and Canada butits strength is validation of addresses in other countries. If you process a significant number of addressesoutside the U.S. and Canada, you should consider using ValidateAddressGlobal.
ValidateAddressGlobal is part of the Universal Addressing Module.
ValidateAddressGlobal performs several steps to achieve a quality address, including transliteration,parsing, validation, and formatting.
Character Set Mapping and Transliteration
ValidateAddressGlobal handles international strings and their complexities. It uses fully Unicode enabledstring processing which enables the transliteration of non-roman characters into the Latin character setand mapping between different character sets.
Character set mapping and transliteration features include:
• Support for over 30 different character sets including UTF-8, ISO 8859-1, GBK, BIG5, JIS, EBCDIC• Proper "elimination" of diacritics according to language rules• Transliteration for various alphabets into Latin Script• Greek (BGN/PCGN 1962, ISO 843 - 1997)• Cyrillic (BGN/PCGN 1947, ISO 9 - 1995)• Hebrew• Japanese Katakana, Hiragana and Kanji• Chinese Pinyin (Mandarin, Cantonese)• Korean Hangul
Address Parsing, Formatting, and Standardization
Restructuring incorrectly fielded address data is a complex and difficult task especially when done forinternational addresses. People introduce many ambiguities as they enter address data into computersystems. Among the problems are misplaced elements (such as company or personal names in streetaddress fields) or varying abbreviations that are not only language, but also country specific.ValidateAddressGlobal identifies address elements in address lines and assigns them to the properfields. This is an important precursor to the actual validation. Without restructuring, "no match" situationsmight result.
Spectrum Technology Platform 9.0180
Universal Addressing Module
Properly identified address elements are also important when addresses have to be truncated or shortenedto fit specific field length requirements. With the proper information in the right fields, specific truncationrules can be applied.
• Parses and analyzes address lines and identifies individual address elements• Processes over 30 different character sets• Formats addresses according to the postal rules of the country of destination• Standardizes address elements (such as changing AVENUE to AVE)
Global Address Validation
Address validation is the correction process where properly parsed address data is compared againstreference databases supplied by postal organizations or other data providers. ValidateAddressGlobalvalidates individual address elements to check for correctness using sophisticated fuzzy matchingtechnology and produces standardized and formatted output based on postal standards and userpreferences. FastCompletion validation type can be used in quick address entry applications. It allowsinput of truncated data in several address fields and generates suggestions based on this input.
In some cases, it is not possible to fully validate an address. Here ValidateAddressGlobal has a uniquedeliverability assessment feature that classifies addresses according to their probable deliverability.
Resource URL
JSON endpoint:
http://server:port/rest/ValidateAddressGlobal/results.json
XML endpoint:
http://server:port/rest/ValidateAddressGlobal/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/ValidateAddressGlobal/results.json?City.StateProvince=NY&Data.AddressLine1=1+Global+View&Data.City=Troy&Data.Country=USA
The JSON returned by this request would be:
{"output": [{"Country.Input": "USA","AddressLine1.Input": "1 Global View","City.Input": "Troy","Country": "UNITED STATES","AddressLine1": "1 GLOBAL VW","HouseNumber": "1","StreetName": "GLOBAL","StreetSuffix": "VW","City": "TROY","PostalCode": "12180-8371","PostalCode.Base": "12180","PostalCode.AddOn": "8371","StateProvince": "NEW YORK","County": "RENSSELAER","LastLine": "TROY NY 12180-8371","AddressBlock1": "1 GLOBAL VW","AddressBlock2": "TROY NY 12180-8371","ProcessStatus": "C4","ProcessStatus.Description": "Corrected - all elements have been
checked","ModeUsed": "BATCH","CountOverflow": "NO",
181REST Web Services Guide
Chapter 2: Web Services
"MailabilityScore": "5","Confidence": "82.09","ElementResultStatus": "88F088E0F000000000E0","ElementInputStatus": "00600050600000000060","ElementRelevance": "11101010100000000010","AddressType": "S","AMAS.Status": "EAM0","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/ValidateAddressGlobal/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.Country=USA&Data.StateProvince=NY
The XML returned by this request would be:
<ns2:xml.ValidateAddressGlobalResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddressGlobal">
<ns2:output><ns2:Address>
<ns2:Country>UNITED STATES</ns2:Country><ns2:AddressLine1>1 GLOBAL VW</ns2:AddressLine1><ns2:HouseNumber>1</ns2:HouseNumber><ns2:StreetName>GLOBAL</ns2:StreetName><ns2:StreetSuffix>VW</ns2:StreetSuffix><ns2:City>TROY</ns2:City><ns2:PostalCode>12180-8371</ns2:PostalCode><ns2:PostalCode.Base>12180</ns2:PostalCode.Base><ns2:PostalCode.AddOn>8371</ns2:PostalCode.AddOn><ns2:StateProvince>NY</ns2:StateProvince><ns2:County>RENSSELAER</ns2:County><ns2:LastLine>TROY NY 12180-8371</ns2:LastLine><ns2:AddressBlock1>1 GLOBAL VW</ns2:AddressBlock1><ns2:AddressBlock2>TROY NY 12180-8371</ns2:AddressBlock2><ns2:ProcessStatus>C4</ns2:ProcessStatus><ns2:ProcessStatus.Description>
Corrected - all elements have been checked</ns2:ProcessStatus.Description><ns2:ModeUsed>BATCH</ns2:ModeUsed><ns2:CountOverflow>NO</ns2:CountOverflow><ns2:MailabilityScore>5</ns2:MailabilityScore><ns2:Confidence>85.09</ns2:Confidence><ns2:ElementResultStatus>
88F0F8E0F000000000E0</ns2:ElementResultStatus><ns2:ElementInputStatus>
00606050600000000060</ns2:ElementInputStatus><ns2:ElementRelevance>
11101010100000000010</ns2:ElementRelevance><ns2:AddressType>S</ns2:AddressType><ns2:AMAS.Status>EAM0</ns2:AMAS.Status><ns2:user_fields/>
</ns2:Address></ns2:output>
</ns2:xml.ValidateAddressGlobalResponse>
Spectrum Technology Platform 9.0182
Universal Addressing Module
Request
Parameters for Input DataValidateAddressGlobal takes a standard address as input. All addresses use this format no matter whatcountry the address is from.
Table 78: ValidateAddressGlobal Input
DescriptionFormatParameter
These fields contain address line data. AddressLine1 containsthe first address line, AddressLine2 contains the second
String[79]
Data.AddressLine1 throughData.AddressLine6
address line, and so forth. Note that the city, state/province,and postal code information should be placed in theirrespective fields, not address line fields. For example:
AddressLine1: 17413 Blodgett RoadAddressLine2: PO Box 123City: Mount VernonStateProvice: WAPostalCode: 97273Country: USA
If the input address is not already parsed into the appropriateaddress line and City, StateProvice, and PostalCode fields,use the UnformattedLine fields instead of the address linefields.
City nameString[79]
Data.City
State or province.String[79]
Data.StateProvince
The postal code for the address. In the U.S. this is the ZIPCode®.
String[79]:
9999999999-9999
Data.PostalCode
A9A9A9A9A 9A99999999
The name of the addressee. For example, "Mr. Jones".String[79]
Data.Contact
The country name. If no value is specified in the or option,you must specify a country.
String[79]
Data.Country
Company or firm nameString[79]
Data.FirmName
StreetString[79]
Data.Street
NumberBuilding[79]
Data.Number
183REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatParameter
BuildingString[79]
Data.Building
SubBuildingString[79]
Data.SubBuilding
DeliveryServiceString[79]
Data.DeliveryService
Use these fields if the input address is completely unparsedand you want ValidateAddressGlobal to attempt to parse theaddress into the appropriate fields. For example:
String[79]
Data.UnformattedLine1throughData.UnformattedLine10
UnformattedLine1: 17413 Blodgett RoadUnformattedLine2: PO Box 123UnformattedLine3: Mount Vernon WA 97273UnformattedLine4: USA
This address would be parsed into these output fields:
AddressLine1: 17413 Blodgett RoadAddressLine2: PO Box 123City: Mount VernonStateProvice: WAPostalCode: 97273Country: USA
If you specify input in the unformatted line fields youmust specify the entire address using only
Note:
unformatted line fields. Do not use other fields suchas City or StateProvince in combination withunformatted line fields.
Parameters for OptionsInput Options
Table 79: ValidateAddressGlobal Input Options
Description/Valid ValuesParameter
Specifies the database resource containing the postal data to use for addressvalidation. Only databases that have been defined in the Global Database
Option.Database.AddressGlobal
Resources panel in the Management Console are available. For moreinformation, see the Spectrum™ Technology Platform Administration Guide.
Specifies a default country to use when the input record does not containexplicit country information. Specify the country using the ISO3 country code.
Option.Input.DefaultCountryISO3
If you do not specify a default country each input record must have the countryspecified in the Country input field. For a list of ISO codes see Country ISOCodes and Module Support on page 234.
Causes address records to be always treated as originating from the countryspecified here, overriding the country in the address record and the default
Option.Input.ForceCountryISO3
country. Specify the country using the ISO3 country code. For a list of ISOcodes, see Country ISO Codes and Module Support on page 234.
Spectrum Technology Platform 9.0184
Universal Addressing Module
Description/Valid ValuesParameter
Enables you to use non-standard formatting for multi-line addresses in inputfiles. Acceptable values for this field include the following:
Option.Input.FormatDelimiter
• CRLF (default)• LF• CR• SEMICOLON ( 2101 MASSACHUSETTS AVE NW ; WASHINGTON DC20008)
• COMMA (2101 MASSACHUSETTS AVE NW , WASHINGTON DC 20008)
• TAB (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008 )• PIPE (2101 MASSACHUSETTS AVE NW | WASHINGTON DC 20008 )• SPACE (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008)
The same value must be selected for both the input option and outputoption.
Note:
Output Options
Table 80: ValidateAddressGlobal Output Options
DescriptionParameter
This option specifies the maximum number of candidate addresses toreturn. The default is 1. The maximum is 20. If you are using
Option.Result.MaximumResults
FastCompletion mode, you may want to enter a number greater than 1to ensure you are provided with multiple options for completing a field.
Specifies whether to include the input data in the output. If enabled, theoutput will contain fields that end with .Input containing the corresponding
Option.Result.IncludeInputs
input field. For example, the output field AddressLine1.Input wouldcontain the data specified in the input field AddressLine1.
Include the input data in the output.TRUE
Do not include the input data in the output(default).
FALSE
Specifies the format for the StateProvince field. One of the following.Option.Result.StateProvinceType
Return the abbreviation for the state orprovince. For example, North Carolina wouldbe returned as "NC".
ABBREVIATION
Return either the abbreviation or the fullname depending on the format used by thecountry's postal authority. (Default)
COUNTRY_STANDARD
Return the full name of the state or province,not the abbreviation. For example "NorthCarolina".
EXTENDED
Specifies the language or code to use for the country name returned byValidateAddressGlobal.
Option.Result.CountryType
185REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
The two-character ISO code for thecountry
ISO2
The three-character ISO code forthe country
ISO3
The ISO country numberISO_NUMBER
ChineseNAME_CN
DanishNAME_DA
GermanNAME_DE
English (default)NAME_EN
SpanishNAME_ES
FinnishNAME_FI
FrenchNAME_FR
GreekNAME_GR
HungarianNAME_HU
ItalianNAME_IT
JapaneseNAME_JP
KoreanNAME_KR
DutchNAME_NL
PolishNAME_PL
PortugueseNAME_PT
RussianNAME_RU
SanskritNAME_SA
SwedishNAME_SE
Specifies the alphabet in which the output should be returned. Thealphabet in which the data is returned differs from country to country.
Option.Result.PreferredScript
For most countries the output will be Latin I regardless of the selectedpreferred language.
ASCII characters with expansion of specialcharacters (e.g. Ö = OE)
ASCII_Extended
ASCII charactersASCII_Simplified
(default) Latin I or ASCII characters (as perreference database standard)
Database
Latin I charactersLatin
Latin I characters (alternative transliteration)Latin_Alt
Latin I or ASCII characters (local postaladministration alternative)
Postal_Admin_Alt
Latin I or ASCII characters (as preferred bylocal postal administration)
Postal_Admin_Pref
Spectrum Technology Platform 9.0186
Universal Addressing Module
DescriptionParameter
For countries that use an alphabet other than Latin I, the returnedalphabet differs from country to country. For more information, seeAlphabets for Non-Latin 1 Countries on page 187.
Specifies the language in which the output should be returned. Thealphabet in which the data is returned differs from country to country,
Option.Result.PreferredLanguage
but for most countries the output will be Latin, regardless of the selectedpreferred language.
Language derived from reference data for eachaddress. Default.
DATABASE
English locality and state/province names output,if available.
ENGLISH
Specifies the casing of the output.Option.Result.Casing
Output will be based on the reference databasestandard.
NATIVE
Output will be in upper case for all countries.UPPER
Output will be in lower case for all countries.LOWER
Casing determined by country-specific rules.MIXED
For parse mode, returns the data the way it wasentered. For validation mode, uses the casing found
NOCHANGE
in the reference data and according to postal rules.Values that could not be checked against thereference data will retain their input casing.
Enables you to use non-standard formatting for multi-line addresses inthe output. Acceptable values for this field include the following:
Option.Result.FormatDelimiter
• CRLF (default)• LF• CR• SEMICOLON ( 2101 MASSACHUSETTS AVE NW ; WASHINGTONDC 20008)
• COMMA (2101 MASSACHUSETTS AVE NW , WASHINGTON DC20008 )
• TAB (2101 MASSACHUSETTS AVE NW WASHINGTON DC 20008)
• PIPE (2101MASSACHUSETTSAVENW |WASHINGTONDC 20008)
• SPACE (2101 MASSACHUSETTS AVE NW WASHINGTON DC20008)
The same value must be selected for both the input option andoutput option.
Note:
Alphabets for Non-Latin 1 Countries
For countries that use an alphabet other than Latin I, the returned alphabet differs from country to country.The following table shows how the output is returned for specific countries. All countries that are notlisted use the value specified in the field option.
187REST Web Services Guide
Chapter 2: Web Services
LatinDatabaseCountry
CYRILLIC_ISO+ LATIN
CYRILLIC_ISO+LATIN_SIMPLE
CYRILLIC_BGNCYRILLIC_ISOCyrillicCyrillicCyrillicRUS
JAPANESE+ LATIN
JAPANESE+LATIN_SIMPLE
JAPANESEJAPANESEKanaKanjiKanjiJPN
CHINESE_MANDARIN+ LATIN
CHINESE_MANDARIN+LATIN_SIMPLE
CHINESE_CANTONESE
CHINESE_MANDARIN
HanziHanziHanziCHN
CHINESE_CANTONESE+ LATIN
CHINESE_CANTONESE+LATIN_SIMPLE
CHINESE_MANDARIN
CHINESE_CANTONESE
HanziHanziHanziHKG
CHINESE_CANTONESE+ LATIN
CHINESE_CANTONESE+LATIN_SIMPLE
CHINESE_MANDARIN
CHINESE_CANTONESE
HanziHanziHanziTWN
GREEK_ISO+ LATIN
GREEK_ISO+LATIN_SIMPLE
GREEK_BGNGREEK_ISOGreekGreekGreekGRC
KOREAN +LATIN
KOREAN +LATIN_SIMPLE
KOREANKOREANHanjaHangulLatinKOR
HEBREW +LATIN
HEBREW +LATIN_SIMPLE
HEBREWHEBREWHebrewHebrewLatinISR
LATINLATIN_SIMPLELatin-3Latin-3Latin-3Latin-3Latin-3ROM
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2POL
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2CZE
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2CRI
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2HUN
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2MDA
LATINLATIN_SIMPLELatin-2Latin-2Latin-2Latin-2Latin-2SVK
LATINLATIN_SIMPLELatin-7Latin-7Latin-7Latin-7Latin-7LAT
Process Options
Table 81: ValidateAddressGlobal Process Options
DescriptionParameter
Use this option to set the appropriate balance between processing speedand quality. One of the following:
Option.Process.OptimizationLevel
The parser will honor input assignment strictly, with theexception of separation of House Number from Streetinformation.
NARROW
Spectrum Technology Platform 9.0188
Universal Addressing Module
DescriptionParameter
The parser will separate address element more actively asfollows:
STANDARD
• Province will be separated from Locality information• PostalCode will be separated from Locality information• House Number will be separated from Street information• SubBuilding will be separated from Street information• DeliveryService will be separated from Street information• SubBuilding will be separated from Building information• Locality will be separated from PostalCode information
Parser separation will happen similarly to Standard, butadditionally up to 10 parsing candidates will be passed to
WIDE
validation for processing. Validation will widen its search treeand take additional reference data entries into account formatching.
Please note that adjusting the optimization level might have no effect forcountries that lack the postal reference data information required for the kindof separation described above.
Increasing separation granularity from Narrow to Standard consumes someprocessing power, but themajor impact on processing speed is from validationprocessing a larger search tree, thus increasing the number of data accessesand comparisons for the optimization level Wide, in an attempt to make themost out of the input data given.
Specifies the type of processing to perform on the addresses. One of thefollowing:
Option.Process.Mode
Use this mode in batch processing environments whenno human input or selection is possible. It is optimized
BATCH
for speed and will terminate its attempts to correct anaddress when ambiguous data is encountered thatcannot be corrected automatically. The Batchprocessing mode will fall back to Parse mode whenthe database is missing for a specific country.
Use this mode in batch processing environments forAustralian mail. Validate Address Global is certified
CERTIFIED
by Australia Post's AddressMatching Approval System(AMAS). It will standardize and validate your mailagainst the Postal Address File, providing postaldiscounts and allowing for the least amount ofundeliverable pieces.
Use this mode if you want to use FastCompletionmode to enter truncated data in address fields and
FASTCOMPLETION
have Validate Address Global generate suggestions.For example, if you work in a call center orpoint-of-sale environment, you can enter just part ofan address element and the FastCompletion featurewill provide valid options for the complete element.
Use this mode when working in interactiveenvironments to generate suggestions when an
INTERACTIVE
address input is ambiguous. This validation type is
189REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
especially useful in data entry environments whencapturing data from customers or prospects. It requiresthe input of an almost-complete address and willattempt to validate or correct the data provided. Ifambiguities are detected, this validation type willgenerate up to 20 suggestions that can be used forpick lists. The Interactive processing mode will fallback to Parse mode when the respective database ismissing for a specific country.
Use this mode for separating address input into tokensfor subsequent processing in other systems, bypassing
PARSE
validation. For example, you could use this mode whenaddress data of already high quality simply needs tobe tokenized quickly for export to an external systemor for use by a downstream stage.
Specifies how closely an address must match the reference data in order forthe address to be validated. One of the following:
Option.Process.MatchingScope
These settings may not have an effect for countries lacking thenecessary level of detail in the postal reference data.
Note:
All address elements must match.ALL
Validate Global Address must achieve a matchon StateProvince, PostalCode,
DELIVERYPOINT_LEVEL
City/Locality/Suburb, street, house number, andsub building.
Validate Global Address must achieve a matchon StateProvince, PostalCode,City/Locality/Suburb, and street.
STREET_LEVEL
Validate Global Address must achieve a matchon StateProvince, PostalCode, andCity/Locality/Suburb.
LOCALITY_LEVEL
Response
Address Data
Table 82: Parsed Address Elements
DescriptionResponse Element
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:
Spectrum Technology Platform 9.0190
Universal Addressing Module
DescriptionResponse Element
AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600City: LanhamStateProvince: MDPostalCode: 20706
Results in this address block output:
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
191REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
The second part of a postcode. For example, for Canadian addressesthis will be the LDU. For U.S. addresses this is the ZIP + 4 add on. Thisfield is not used by most countries.
PostalCode.AddOn
The base portion of the postcode.PostalCode.Base
A room number in a building.Room
The name of a secondary street or rural route.SecondaryStreet
The name of the state or province.StateProvince
The name of street where property is located, for example: 123 E MainSt Apt 3
StreetName
The street suffix, for example: 123 E Main St Apt 3StreetSuffix
A portion of a building, such as a suite. For example, Suite 102.SubBuilding
Dependent place name that further subdivides a Locality. An examplewould be Mahalle in Turkey.
Suburb
The name of a territory. Territories are larger than a state/province.Territory
The trailing directional, for example: 123 Pennsylvania Ave NWTrailingDirectional
Original Input DataThis option outputs the original input data in <FieldName>.Input fields.
Table 83: Original Input Data
DescriptionFormatResponse Element
First address lineString[79]
AddressLine1.Input
Second address lineString[79]
AddressLine2.Input
Third address lineString[79]
AddressLine3.Input
Fourth address lineString[79]
AddressLine4.Input
Fifth address lineString[79]
AddressLine5.Input
Sixth address lineString[79]
AddressLine6.Input
City nameString[79]
City.Input
State or provinceString[79]
StateProvince.Input
Spectrum Technology Platform 9.0192
Universal Addressing Module
DescriptionFormatResponse Element
The postal code for the address. In the U.S. this is the ZIPCode. One of these formats:
String[79]:
PostalCode.Input
9999999999-9999A9A9A9A9A 9A99999 999
The name of the addressee. For example, "Mr. Jones".String[79]
Contact.Input
Specify the country using the format you chose for inputcountry format (English name, ISO code, or UPU code). For
String[79]
Country.Input
a list of valid values, see Country ISO Codes and ModuleSupport on page 234.
Company or firm nameString[79]
FirmName.Input
StreetString[79]
Street.Input
NumberBuilding[79]
Number.Input
BuildingString[79]
Building.Input
SubBuildingString[79]
SubBuilding.Input
DeliveryServiceString[79]
DeliveryService.Input
Result CodesThese output fields contain information about the result of the validation processing.
Table 84: Result Codes
Result CodeResponse Element
For United States and Canada addresses only, the AddressType fieldindicates the type of address. One of the following:
AddressType
The address was validated/corrected to the firm name.F
The address was validated/corrected to the building name.B
The address is a general delivery address.G
The address was validated/corrected to the high-rise default.H
The address is a large volume receiver.L
The address is a military address.M
193REST Web Services Guide
Chapter 2: Web Services
Result CodeResponse Element
The address was validated/corrected to PO box.P
The address was validated/corrected to a rural route.R
The address was validated/corrected to a street address.S
The address could not be validated/corrected so the type isunknown.
U
The level of confidence assigned to the address being returned. Range isfrom zero (0) to 100; zero indicates failure, 100 indicates a very high level ofconfidence that the match results are correct.
Confidence
Indicates whether the number of candidate addresses exceeds the numberreturned. One of the following:
CountOverflow
Yes, there are additional candidate addresses. To obtain theadditional candidates, increase the value.
Yes
No, there are no additional candidates.No
ElementInputStatus provides per element information on the matching ofinput elements to reference data. The values in this field vary depending on
ElementInputStatus
whether you are using batch mode or parse mode. For information about thevalue in this field, see Interpreting ElementInputStatus,ElementResultStatus, and ElementRelevance on page 196.
Indicates which address elements are actually relevant from the local postalauthority's point of view. For information about the value in this field, see
ElementRelevance
Interpreting ElementInputStatus, ElementResultStatus, andElementRelevance on page 196.
ElementResultStatus categorizes the result in more detail than theProcessStatus field by indicating if and how the output fields have been
ElementResultStatus
changed from the input fields. For information about the value in this field,see Interpreting ElementInputStatus, ElementResultStatus, andElementRelevance on page 196.
An estimate of how likely it is that mail sent to the address would be successfuldelivered. One of the following:
MailabilityScore
Completely confident of deliverability5
Almost certainly deliverable4
Should be deliverable3
Fair chance2
Risky1
No chance0
Indicates the processing mode used. The processing mode is specified inthe option. For a description of the modes, see Process Options on page188.
ModeUsed
If the address was matched to multiple candidate addresses in the referencedata, this field contains the number of candidate matches found.
MultimatchCount
Provides a general description of the output quality. For a more detaileddescription of the output quality, see the ElementResultStatus field.
ProcessStatus
Spectrum Technology Platform 9.0194
Universal Addressing Module
Result CodeResponse Element
One of the following:
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
195REST Web Services Guide
Chapter 2: Web Services
Result CodeResponse Element
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
Spectrum Technology Platform 9.0196
Universal Addressing Module
• 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.
197REST Web Services Guide
Chapter 2: Web Services
• 4—Validated but not changed due to lack of reference data.• 5—Validated but not changed due to multiple matches. Only set in batch mode, otherwise multiplesuggestions that replace the input are marked as corrected (status value 7).
• 6—Validated and changed by eliminating the input value• 7—Validated and changed due to correction based on reference data• 8—Validated and changed by adding value based on reference data• 9—Validated, not changed, but delivery status not clear (e.g. DPV value wrong; given number rangesthat only partially match reference data).
• C—Validated, verified but changed due to outdated name• D—Validated, verified but changed from exonym to official name• E—Validated, verified but changed due to standardization based on casing or language. Validationonly sets this status if input fully matches a language alternative.
• F—Validated, verified and not changed due to perfect match
For Country (position 19 & 20), the following values are possible:
• 0—Empty• 1—Country not recognized• 4—Country recognized from DefaultCountryISO3 setting• 5—Country not recognized - multiple matches• 6—Country recognized from script• 7—Country recognized from format• 8—Country recognized from major town• 9—Country recognized from province• C—Country recognized from territory• D—Country recognized from name with errors• E—Country recognized from name without errors• F—Country recognized from ForceCountryISO3 setting
ValidateAddressLoqateValidateAddressLoqate standardizes and validates addresses using postal authority address data.ValidateAddress Loqate can correct information and format the address using the format preferred bythe applicable postal authority. It also adds missing postal information, such as postal codes, city names,state/province names, and so on.
ValidateAddressLoqate also returns result indicators about validation attempts, such as whether or notValidateAddressLoqate validated the address, the level of confidence in the returned address, the reasonfor failure if the address could not be validated, and more.
During address matching and standardization, ValidateAddressLoqate separates address lines intocomponents and compares them to the contents of the Universal Addressing Module databases. If amatch is found, the input address is standardized to the database information. If no database match isfound, ValidateAddressLoqate optionally formats the input addresses. The formatting process attemptsto structure the address lines according to the conventions of the appropriate postal authority.
ValidateAddressLoqate is part of the Universal Addressing Module.
Resource URL
JSON endpoint:
http://server:port/rest/ValidateAddressLoqate/results.json
XML endpoint:
http://server:port/rest/ValidateAddressLoqate/results.xml
Spectrum Technology Platform 9.0198
Universal Addressing Module
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/ValidateAddressLoqate/results.json?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY
The JSON returned by this request would be:
{"output_port": [{"Confidence": "95","CouldNotValidate": "","ProcessedBy": "LOQATE","MatchScore": "100.0","AddressLine1": "1 Global Vw","AddressLine2": "","City": "Troy","StateProvince": "NY","PostalCode": "12180-8371","Country": "United States","FirmName": "","PostalCode.Base": "12180","PostalCode.AddOn": "8371","user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/ValidateAddressLoqate/results.xml?Data.AddressLine1=1+Global+View&Data.City=Troy&Data.StateProvince=NY
The XML returned by this request would be:
<ns2:xml.ValidateAddressLoqateResponsexmlns:ns2="http://www.pb.com/spectrum/services/ValidateAddressLoqate">
<ns2:output_port><ns2:Address>
<ns2:Confidence>95</ns2:Confidence><ns2:CouldNotValidate/><ns2:ProcessedBy>LOQATE</ns2:ProcessedBy><ns2:MatchScore>100.0</ns2:MatchScore><ns2:AddressLine1>1 Global Vw</ns2:AddressLine1><ns2:AddressLine2/><ns2:City>Troy</ns2:City><ns2:StateProvince>NY</ns2:StateProvince><ns2:PostalCode>12180-8371</ns2:PostalCode><ns2:PostalCode.Base>12180</ns2:PostalCode.Base><ns2:PostalCode.AddOn>8371</ns2:PostalCode.AddOn><ns2:Country>United States</ns2:Country><ns2:FirmName/><ns2:user_fields/>
</ns2:Address></ns2:output_port>
</ns2:xml.ValidateAddressLoqateResponse>
Request
Parameters for Input DataValidateAddressLoqate takes an address as input. All addresses use this format regardless of theaddress's country. See Address Line Processing for U.S. Addresses on page 200 for importantinformation about how address line data is processed for U.S. addresses.
199REST Web Services Guide
Chapter 2: Web Services
Table 85: Input Format
DescriptionFormatParameter
The first address line.StringData.AddressLine1
The second address line.StringData.AddressLine2
The third address line.StringData.AddressLine3
The fourth address line.StringData.AddressLine4
The city name.StringData.City
The country code or name, in any of the following formats:StringData.Country
• Two-character ISO 3116-1 Alpha-2 country code• Three-character ISO 3116-1 Alpha-3 country code• English country name
For a list of ISO codes, seeCountry ISO Codes and ModuleSupport on page 234.
The company or firm name.StringData.FirmName
The postal code for the address in one of the followingformats:
StringData.PostalCode
9999999999-9999A9A9A9A9A 9A99999 999
The state or province.StringData.StateProvince
Address Line Processing for U.S. Addresses
The input fields AddressLine1 through AddressLine4 are handled differently for U.S. addresses dependingon whether the firm name extraction or urbanization code extraction options are enabled. If either ofthese options is enabled, ValidateAddressLoqate will look at the data in all four fields to validate theaddress and extract the requested data (firm name and/or urbanization code). If neither of these optionsis enabled, ValidateAddressLoqate uses only the first two non-blank address line fields in its validationattempt. The data in the other address line fields is returned in the output field AdditionalInputData. Forexample,
AddressLine1: A1 Calle AAddressLine2:AddressLine3: URB AlamarAddressLine4: Pitney Bowes Software
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.
Spectrum Technology Platform 9.0200
Universal Addressing Module
Table 86: Output Data Options
DescriptionParameter
Specifies which database you want to use for validatinginternational addresses. To specify a database for
Option.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
Option.OutputFieldLevelReturnCodes
ValidateAddressLoqate handled each address element.Field-level result indicators are returned in the qualifier"Result". For example, the field-level result indicator forHouseNumber is contained in HouseNumber.Result. For acomplete listing of result indicator output fields, see ResultIndicators on page 209.
No, do not output field-level return codes (default).N
Yes, output field-level return codes.Y
Specifies whether to return a formatted address when anaddress cannot be validated. The address is formatted using
Option.OutputFormattedOnFail
the preferred address format for the address's country. If thisoption is not selected, the output address fields are blankwhen ValidateAddressLoqate cannot validate the address.
This option applies only to U.S. and Canadianaddresses. Formatted data will not be returned forany other address.
Note:
No, do not format failed addresses (default).N
Yes, format failed addresses.Y
Formatted addresses are returned using the format specifiedby theInclude a standard address, Include address lineelements, and Include postal information check boxes.Note that if you select Include address line elements, theparsed address elements will contain the parsed, validatedaddress for addresses that could be validated. If the addresscould not be validated the parsed address elements willcontain the input address in parsed form. If you always wantthe output to contain the input address in parsed form,regardless of whether or not ValidateAddressLoqate couldvalidate the address, select Include standardized inputaddress elements.
If you check this option, you must select Include a standardaddress and/or Include address line elements.
Formatted addresses are returned using the format specifiedby the OutputRecordType option. Note that if you specifyOutputRecordType=E, the parsed address elements willcontain the parsed, validated address for addresses thatcould be validated. If the address could not be validated theparsed address elements will contain the input address inparsed form. If you always want the output to contain theinput address in parsed form, regardless of whether or not
201REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
ValidateAddressLoqate could validate the address, specifyOutputRecordType=I.
If you specify Y, you must specify "A" and/or "E" forOutputRecordType.
Formatted addresses are returned using the format specifiedby the Option.OutputRecordType option. Note that if youspecify Option.OutputRecordType=E, the parsed addresselements will contain the parsed, validated address foraddresses that could be validated. If the address could notbe validated the parsed address elements will contain theinput address in parsed form. If you always want the outputto contain the input address in parsed form, regardless ofwhether or not ValidateAddressLoqate could validate theaddress, specify Option.OutputRecordType=I.
If you specify Y, you must specify "A" and/or "E" forOption.OutputRecordType.
Specifies whether to return a formatted version of the addressas it would be printed on a physical mailpiece. Each line of
Option.OutputAddressBlocks
the address is returned in a separate address block field.There can be up to nine address block output fields:AddressBlock1 through AddressBlock9.
For example, this input address:
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
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.
One of the following:
No, do not return address blocks. Default.N
Yes, return address blocks.Y
Specifies the casing of the output data. One of the following:Option.OutputCasing
Spectrum Technology Platform 9.0202
Universal Addressing Module
DescriptionParameter
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 countrywhere most of your addresses reside. For example, if most
Option.HomeCountry
of the addresses you process are in Canada, specify Canada.ValidateAddressLoqate uses the country you specify toattempt validation when it cannot determine the country fromthe StateProvince, PostalCode, and Country address fields.The valid country names are:
Afghanistan, Albania, Algeria, American Somoa, Andorra,Angola, Anguilla, Antigua And Barbuda, Argentina, Armenia,Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain,Bangladesh, Barbados, Belarus, Belgium, Belize, Benin,Bermuda, Bhutan, Bolivia, Bosnia And Herzegovina,Botswana, Brazil, British Virgin Islands, Brunei Darussalam,Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon,Canada, Cape Verde, Cayman Islands, Central AfricanRepublic, Chad, Chile, China, Colombia, Comoros Islands,Congo, Cook Islands, Costa Rica, Cote D'Ivoire, Croatia,Cuba, Cyprus, Czech Republic, Democratic Republic OfCongo, Denmark, Djibouti, Dominica, Dominican Republic,East Timor, Ecuador, Egypt, El Salvador, Equitorial Guinea,Eritrea, Estonia, Ethiopia, Falkland Islands, Faroe Islands,Federated States Of Micronesia, Fiji, Finland, France, FrenchGuiana, Gabon, Gambia, Germany, Ghana, Gibraltar, Greece,Greenland, Grenada, Guadeloupe, Guam, Guatemala,Guinea, Guinea Bissau, Guyana, Haiti, Holy See, Honduras,Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq,Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan,Kenya, Kiribati, Korea, Kuwait, Kyrgyzstan, Laos, Latvia,Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania,Luxembourg, Macau, Macedonia, Madagascar, Malawi,Malaysia, Maldives, Mali, Malta, Marshall Islands, Martinique,Mauritania, Mauritius, Mayotte, Mexico, Moldova, Monaco,Mongolia, Monserrat, Morocco, Mozambique, Myanmar,Namibia, Nauru, Nepal, Netherlands Antilles, NewCaledonia,New Zealand, Nicaragua, Niger, Nigeria, Niue, Norway,Oman, Pakistan, Palau, Panama, Papua New Guinea,Paraguay, Peru, Philippines, Pitcairn Islands, Poland,Portugal, Puerto Rico, Qatar, Republic Of Georgia, RepublicOf Korea, Republic Of Singapore, Reunion, Romania, Russia,Rwanda, Saint Helena, Saint Kitts And Nevis, Saint Lucia,Saint Pierre And Miquelon, Saint Vincent And TheGrenadines, Samoa, San Marino, Sao Tome And Principe,Saudi Arabia, Senegal, Seychelles, Sierra Leone, Slovakia,Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri
203REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Lanka, Sudan, Surivalue, Swaziland, Sweden, Switzerland,Syria, Tahiti, Taiwan, Tajikistan, Tanzania, Thailand, TheNetherlands, Togo, Tonga, Trinidad And Tobago, Tristan DaCunha, Tunisia, Turkey, Turkmenistan, Turks And CaicosIslands, Tuvalu, Uganda, Ukraine, United Arab Emirates,United Kingdom, United States, Uruguay, Uzbekistan,Vanuatu, Venezuela, Vietnam, Virgin Islands (US), WallisAnd Futuna, Yemen, Yugoslavia, Zambia, Zimbabwe
Specifies the format to use for the country name returned inthe Country output field. For example, if you select English,
Option.OutputCountryFormat
the country name "Deutschland" would be returned as"Germany".
Use English country names (default).E
Use two-letter ISO abbreviation for the countriesinstead of country names.
I
Use Universal Postal Union abbreviation for thecountries instead of country names.
U
Specifies the alphabet or script in which the output shouldbe returned. This option is bi-directional and generally takesplace from Native to Latin and Latin to Native.
Option.OutputScript
Do not perform transliteration and provideoutput in the same script as the input(default).
Input
Output in the native script for the selectedcountry wherever possible.
Native
Use English values.Latn
Indicates whether or not to return multiple address for thoseinput addresses that have more than one possible match.
Option.KeepMultimatch
Yes, return multiple matches (default).Y
No, do not return multiple matches.N
For more information, see Returning Multiple Matches onpage 204.
Returning Multiple Matches
If ValidateAddressLoqate finds multiple address in the postal database that are possible matches forthe input address, you can have ValidateAddressLoqate return the possible matches. For example, thefollowing address matches multiple addresses in the U.S. postal database:
PO BOX 1 New York, NY
Options
To return multiple matches, use the options described in the following table.
Spectrum Technology Platform 9.0204
Universal Addressing Module
Table 87: Multiple Match Option
Description/Valid Values
Indicates whether or not to return multiple address for those inputaddresses that have more than one possible match.
number between 1 and 10 that indicates the maximum number ofaddresses to return. The default value is 1.
The difference between and is that a multiple match will returna failure if, whereas a multiple match will return one record if.
Note:
To identify which output addresses are candidate addresses, you must.When you do this, records that are candidate addresses will have oneor more "M" values in the field-level result indicators.
Output
When you choose to return multiple matches, the addresses are returned in the address format youspecify. For information on specifying address format, seeOptions on page 200. To identify which recordsare the candidate addresses, look for multiple "M" values in the field-level result indicators. For moreinformationResult Indicators on page 209, see .
ResponseThe output from ValidateAddressLoqate contains various information depending on the output categoriesyou select.
Standard Address OutputStandard address output consists of four lines of the address which correspond to how the addresswould appear on an actual address label. City, state/province, postal code, and other data is also includedin standard address output. ValidateAddressLoqate returns standard address output for validatedaddresses if you. Standard address fields are always returned for addresses that could not be validatedregardless of whether or not you. For non-validated addresses, the standard address output fields containthe address as it appeared in the input ("pass through" data). If you want ValidateAddressLoqate tostandardize address according to postal authority standards when validation fails,.
Table 88: Standard Address Output
DescriptionResponse Element
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 country in the format determined by what you selected in:Country
• ISO Code• UPU Code
205REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
• English
The validated firm or company name.FirmName
The validated ZIP Code™ or postal code.PostalCode
The 4-digit add-on part of the ZIP Code™. For example, in the ZIP Code™
60655-1844, 1844 is the 4-digit add-on.PostalCode.AddOn
The 5-digit ZIP Code™; for example 20706.PostalCode.Base
The validated state or province abbreviation.StateProvince
Parsed Address Elements OutputOutput addresses are formatted in the parsed address format if you. If you want ValidateAddressLoqateto return formatted data in the Parsed Address format when validation fails (that is, a normalized address),.
If you want ValidateAddressLoqate to always return parsed input data regardless of whether ornot validation is successful,. For more information, see Parsed Input on page 207.
Note:
Table 89: Parsed Address Output
DescriptionResponse Element
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:
AddressLine1: 4200 Parliament PlaceAddressLine2: Suite 600City: LanhamStateProvince: MDPostalCode: 20706
Results in this address block output:
AddressBlock1: 4200 PARLIAMENT PL STE 600AddressBlock2: LANHAM MD 20706-1882
Apartment designator (such as STE or APT), forexample: 123 E Main St APT 3
ApartmentLabel
Apartment number. For example: 123 E Main StAPT 3
ApartmentNumber
Secondary apartment number. For example: 123E Main St APT 3, 4th Floor
ApartmentNumber2
Spectrum Technology Platform 9.0206
Universal Addressing Module
DescriptionResponse Element
In this release, this field will always beblank.
Note:
Validated city nameCity
Country. Format is determined by what youselected in :
Country
• ISO Code• UPU Code• English
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
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
Parsed InputThe output can include the input address in parsed form. This type of output is referred to as "parsedinput." Parsed input fields contain the address data that was used as input regardless of whether or notValidateAddress validated the address. Parsed input is different from the "parsed address elements"output in that parsed address elements contain the validated address if the address could be validated,and, optionally, the input address if the address could not be validated. Parsed input always containsthe input address regardless of whether or not ValidateAddress validated the address.
To include parsed input fields in the output,.
Table 90: Parsed Input
DescriptionResponse Element
Apartment designator (such as STE or APT), forexample: 123 E Main St APT 3
ApartmentLabel.Input
Apartment number, for example: 123 E Main StAPT 3
ApartmentNumber.Input
Validated city nameCity.Input
207REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Country. Format is determined by what youselected in:
Country.Input
• ISO Code• UPU Code• English
The validated firm or company nameFirmName.Input
House number, for example: 123 E Main St Apt 3HouseNumber.Input
Leading directional, for example: 123 E Main StApt 3
LeadingDirectional.Input
Post office box number. If the address is a ruralroute address, the rural route box number willappear here.
POBox.Input
Validated postal code. For U.S. addresses, this isthe ZIP Code.
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
Trailing directional, for example: 123 PennsylvaniaAve NW
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 .
Table 91: Standard Address Output
DescriptionResponse Element
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
Spectrum Technology Platform 9.0208
Universal Addressing Module
DescriptionResponse Element
The second byte represents the level of geocoding matching and is oneof the following:
Delivery point (post box or subbuilding)5
Premise or building4
Thoroughfare3
Locality2
Administrative area1
None0
Eight-digit number in degrees and calculated to five decimal places (inthe format specified).
Latitude
Eight-digit number in degrees and calculated to five decimal places (inthe format specified).
Longitude
The radius of accuracy in meters, providing an indication of the probablemaximum distance between the given geocode and the actual physical
SearchDistance
location. This field is derived from and dependent upon the accuracyand coverage of the underlying reference data.
Result IndicatorsResult indicators provide information about the kinds of processing performed on an address. There aretwo types of result indicators:
• Record-Level Result Indicators• Field-Level Result Indicators
Record-Level Result Indicators
Record-level result indicators provide data about the results of ValidateAddressLoqate processing foreach record, such as the success or failure of the match attempt, which coder processed the address,and other details. The following table lists the record-level result indicators returned byValidateAddressLoqate.
Table 92: Record Level Indicators
DescriptionResponse Element
The level of confidence assigned to the address being returned. Rangeis from zero (0) to 100; zero indicates failure, 100 indicates a very high
Confidence
level of confidence that the match results are correct. For multiplematches, the confidence level is 0. For details about how this numberis calculated, see Introduction to the Validate Address ConfidenceAlgorithm on page 252.
If no match was found, which address component could not be validated:CouldNotValidate
• ApartmentNumber• HouseNumber• StreetName
209REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
• 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
The Loqate coder processed the address.LOQATE
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
Spectrum Technology Platform 9.0210
Universal Addressing Module
Field-Level Result Indicators
Field-level result indicators describe how ValidateAddressLoqate handled each address element.Field-level result indicators are returned in the qualifier "Result". For example, the field-level resultindicator for HouseNumber is contained in HouseNumber.Result.
To enable field-level result indicators, .
The following table lists the field-level result indicators. If a particular field does not apply to an address,the result indicator may be blank.
Table 93: Field-Level Result Indicators
DescriptionResponse Element
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
Corrected. Canadian addresses only.C
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
211REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
City.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
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
Standardized. This option includes any standard abbreviations.Does not apply to U.S. addresses.
S
Unmatched. Does not apply to Canadian addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
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
Validated. The data was confirmed correct and remainedunchanged from input.
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
Corrected. Canadian addresses only.C
Spectrum Technology Platform 9.0212
Universal Addressing Module
DescriptionResponse Element
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
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
Validated. The data was confirmed correct and remainedunchanged from input.
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
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
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
Standardized. This option includes any standard abbreviations.S
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
Corrected. Canadian addresses only.C
Dropped. The field provided on input was removed. U.S.addresses only. For more information, see About AdditionalInput Data.
D
213REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
The P.O. Box number is required but is missing from the inputaddress. U.S. addresses only.
R
Standardized. This option includes any standard abbreviations.S
Unmatched.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
PostalCode.Result Appended. The field was added to a blank input field. U.S. andCanadian addresses only.
A
Corrected. U.S. and Canadian addresses only.C
Formatted. The spacing and/or punctuation was changed toconform to postal standards. Does not apply to U.S. orCanadian addresses.
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
Validated. The data was confirmed correct and remainedunchanged from input.
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
Spectrum Technology Platform 9.0214
Universal Addressing Module
DescriptionResponse Element
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
Standardized. This option includes any standard abbreviations.Does not apply to U.S. addresses.
S
Unmatched. Does not apply to Canadian addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
StreetName.Result Appended. The field was added to a blank input field. Canadianaddresses only.
A
Corrected. U.S. and Canadian addresses only.C
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
215REST Web Services Guide
Chapter 2: Web Services
DescriptionResponse Element
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
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
Validated. The data was confirmed correct and remainedunchanged from input.
V
StreetSuffix.Result Appended. The field was added to a blank input field. U.S. andCanadian 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. Does not apply to U.S. orCanadian addresses.
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
Standardized. This option includes any standard abbreviations.S
Unmatched. Does not apply to U.S. addresses.U
Validated. The data was confirmed correct and remainedunchanged from input.
V
TrailingDirectional.Result Appended. The field was added to a blank input field. U.S. andCanadian 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. Does not apply to U.S. orCanadian addresses.
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
Pass-through. The data was not used in the validation process,but it was preserved in the output. Canadian addresses only.
P
Spectrum Technology Platform 9.0216
Universal Addressing Module
DescriptionResponse Element
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
Universal Name Module
OpenNameParserOpenNameParser breaks down personal and business names and other terms in the name data fieldinto their component parts. These parsed name elements are then subsequently available to otherautomated operations such as namematching, name standardization, or multi-record name consolidation.
OpenNameParser does the following:
• Determines the type of a name in order to describe the function that the name performs. Name entitytypes are divided into two major groups: personal names and business names. Within each of thesemajor groups are subgroups.
• Determines the form of a name in order to understand which syntax the parser should follow for parsing.Personal names usually take on a natural (signature) order or a reverse order. Business names areusually ordered hierarchically.
• Determines and labels the component parts of a name so that the syntactical relationship of eachname part to the entire name is identified. The personal name syntax includes prefixes, first, middle,and last name parts, suffixes, and account description terms, among other personal name parts. Thebusiness name syntax includes the firm name and suffix terms.
• Parses conjoined personal and business names and either retains them as one record or splits theminto multiple records. Examples of conjoined names include "Mr. and Mrs. John Smith" and "BaltimoreGas & Electric dba Constellation Energy".
• Parses output as records or as a list.• Assigns a parsing score that reflects the degree of confidence that the parsing is correct.
Resource URL
JSON endpoint:
http://server:port/rest/OpenNameParser/results.json
XML endpoint:
http://server:port/rest/OpenNameParser/results.xml
Example with JSON Response
The following example requests a JSON response:
http://myserver:8080/rest/OpenNameParser/results.json?Data.Name=John+Williams+Smith
217REST Web Services Guide
Chapter 2: Web Services
The JSON returned by this request would be:
{"output_port": [{"Name": "John Williams Smith","CultureCodeUsedToParse": "","FirstName": "John","LastName": "Smith","MiddleName": "Williams","Names": [],"IsParsed": true,"IsPersonal": true,"IsConjoined": false,"IsReverseOrder": false,"IsFirm": false,"NameScore": 100,"user_fields": []
}]}
Example with XML Response
The following example requests an XML response:
http://myserver:8080/rest/OpenNameParser/results.xml?Data.Name=John+Williams+Smith
The XML returned by this request would be:
<ns2:xml.OpenNameParserResponsexmlns:ns2="http://www.pb.com/spectrum/services/OpenNameParser">
<ns2:output_port><ns2:Result>
<ns2:Name>John Williams Smith</ns2:Name><ns2:CultureCodeUsedToParse/><ns2:FirstName>John</ns2:FirstName><ns2:LastName>Smith</ns2:LastName><ns2:MiddleName>Williams</ns2:MiddleName><ns2:Names/><ns2:IsParsed>true</ns2:IsParsed><ns2:IsPersonal>true</ns2:IsPersonal><ns2:IsConjoined>false</ns2:IsConjoined><ns2:IsReverseOrder>false</ns2:IsReverseOrder><ns2:IsFirm>false</ns2:IsFirm><ns2:NameScore>100</ns2:NameScore><ns2:user_fields/>
</ns2:Result></ns2:output_port>
</ns2:xml.OpenNameParserResponse>
Request
Parameters for Input Data
Table 94: Open Name Parser Input
DescriptionParameter
The culture of the input name data. The options are listed below.Data.CultureCode
Global culture (default).Null (empty)
German.de
Spanish.es
Japanese.ja
Spectrum Technology Platform 9.0218
Universal Name Module
DescriptionParameter
If you added your own domain using the Open Parser DomainEditor, the cultures and culture codes for that domain are alsovalid.
Note:
The name you want to parse. This field is required.Data.Name
OptionsParameters for Parsing Options
The following table lists the options that control the parsing of names.
Table 95: Open Name Parser Parsing Options
DescriptionParameter
Specifies whether to parse names where the is inthe order Title, First Name, Middle Name, LastName, and Suffix.
Option.ParseNaturalOrderPersonalNames
Parse personal names that are innatural order.
true
Do not parse names that are innatural order.
false
Specifies whether to parse names where the lastname is specified first.
Option.ParseReverseOrderPersonalNames
Parse personal names that are inreverse order.
true
Do not parse names that are inreverse order.
false
Specifies whether to parse conjoined names.Option.ParseConjoinedNames
Parse conjoined names.true
Do not parse conjoined names.false
Specifies whether to separate names containingmore than one individual into multiple records, forexample, Bill & Sally Smith.
Option.SplitConjoinedNames
Split conjoined names.true
Do not split conjoined names.false
Specifies whether to parse business names.Option.ParseBusinessNames
Parse business names.true
Do not parse business names.false
Specifies whether to return the parsed nameelements in a list form.
Option.OutputAsList
Return the parsed elements in a listform.
true
219REST Web Services Guide
Chapter 2: Web Services
DescriptionParameter
Do not return the parsed elements ina list form.
false
Specifies how to balance performance versusquality. A faster performance will result in lower
Option.ShortcutThreshold
quality output; likewise, higher quality will result inslower performance. When this threshold is met,no other processing will be performed on therecord.
Specify a value from 0 to 100. The default is 100.
Parameters for Culture Options
The following table lists the options that control name cultures.
Table 96: Open Name Parser Cultures Options
DescriptionParameter
Specifies which culture(s) you want to include in the parsing grammar.Global Culture is the default selection.
Option.DefaultCulture
Specify cultures by specifying the two-character culture code in acomma-separated list in priority order. For example, to attempt to parsethe name using the Spanish culture first then Japanese, you wouldspecify:
es,ja,,
Parameters for Advanced Options
The following table lists the advanced options for name parsing.
Table 97: Open Name Parser Advanced Options
DescriptionOption
Specifies the domain to use when parsing natural order personal names.The valid values are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.
Option.NaturalOrderPersonalNamesDomain
Specify a number between 1 and 5 that indicates the priority of thenatural order personal names domain relative to the other domains that
Option.NaturalOrderPersonalNamesPriority
you are using. This determines the order in which you want the parsersto run.
Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches thatthreshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.
Spectrum Technology Platform 9.0220
Universal Name Module
DescriptionOption
Specifies the domain to use when parsing reverse order personal names.The valid values are the domain names defined in the Open ParserDomain Editor too in Enterprise Designer.
Option.ReverseOrderPersonalNamesDomain
Specify a number between 1 and 5 that indicates the priority of thereverse order personal names domain relative to the other domains that
Option.ReverseOrderPersonalNamesPriority
you are using. This determines the order in which you want the parsersto run.
Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches thatthreshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.
Specifies the domain to use when parsing natural order conjoinedpersonal names. The valid values are the domain names defined in theOpen Parser Domain Editor too in Enterprise Designer.
Option.NaturalOrderConjoinedPersonalNamesDomain
Specify a number between 1 and 5 that indicates the priority of thenatural order conjoined personal names domain relative to the other
Option.NaturalOrderConjoinedPersonalNamesPriority
domains that you are using. This determines the order in which youwant the parsers to run.
Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches thatthreshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.
Specifies the domain to use when parsing reverse order conjoinedpersonal names. The valid values are the domain names defined in theOpen Parser Domain Editor too in Enterprise Designer.
Option.ReverseOrderConjoinedPersonalNamesDomain
Specify a number between 1 and 5 that indicates the priority of thereverse order conjoined personal names domain relative to the other
Option.ReverseOrderConjoinedPersonalNamesPriority
domains that you are using. This determines the order in which youwant the parsers to run.
Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches thatthreshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.
Specifies the domain to use when parsing business names. The validvalues are the domain names defined in the Open Parser Domain Editortoo in Enterprise Designer.
Option.BusinessNamesDomain
Specify a number between 1 and 5 that indicates the priority of thebusiness names domain relative to the other domains that you are using.This determines the order in which you want the parsers to run.
Option.BusinessNamesPriority
Results will be returned for the first domain that scores higher than thenumber set in the shortcut threshold option. If no domain reaches that
221REST Web Services Guide
Chapter 2: Web Services
DescriptionOption
threshold, results for the domain with the highest score are returned. Ifmultiple domains reach the threshold at the same time, priority goes tothe domain that was run first (determined by the order set here) and itsresults will be returned.
Response
Table 98: Open Name Parser Output
DescriptionFormatResponse Element
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
Spectrum Technology Platform 9.0222
Universal Name Module
DescriptionFormatResponse Element
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
223REST Web Services Guide
Chapter 2: Web Services
DescriptionFormatResponse Element
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
Spectrum Technology Platform 9.0224
Universal Name Module
Appendix
In this section:
• The ACR Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227• Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231• Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233• ValidateAddress Confidence Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
AThe ACR Code
In this section:
• The ACR Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
The ACR CodeThe Address Correction Result (ACR) code describes what data has been changed in each record. Anexample of an ACR is:
L5-P0S0A5T1R0Z0C4-098
ACR codes consist of three parts:
• Validation Level• Component Status• Validation Match Score
Validation Level
The first two characters of the address correction result state the type and level of validation.
The first character, which is always alphabetic, specifies the type of validation:
• U—Unable to standardize address• C—Address is in component form• L—Address has been formatted into address lines• R—Address has been reverted and has not reached acceptable level
The second character, which is always numeric, specifies the level of validation. The higher the level,the better the validation will be. The levels that can be achieved are as follows:
• 0—No components validated• 1—Country only validated• 2—City and country validated• 3—City, postal code and country validated• 4—Street, city, postal code and country validated• 5—Premise number, building name, sub-building, PO box, company, street, city, postal code, andcountry validated.
Component Status
The second part of the ACR code gives the status of the main address components. The addresscomponents are identified as follows:
• Character 3-4: P—Premise/house number• Character 5-6: S—Street• Character 7-8: A—Subcity (city area)• Character 9-10: T—City• Character 11-12: R—Region/state• Character 13-14: Z—Postal code/ZIP Code®
• Character 15-16: C—Country
A number follows each component and can take one of the following values:
• 0—Not found/empty• 1—Derived using position in input data• 2—Recognized using the Address Now Module database• 3—Recognized and updated to standard form using the Address Now Module database• 4—Validated using Address Now Module database• 5—Updated/corrected using Address Now Module database• 6—Added using Address Now Module database• 7—Correctly empty
Spectrum Technology Platform 9.0228
• 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
229REST Web Services Guide
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:
Spectrum Technology Platform 9.0230
BBuffering
In this section:
• Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
BufferingUse buffering to define areas that are close to the edges of a polygon, line, or point.
Buffered Point (circle)Buffered Line (corridor)Buffered Polygon (zone)
For example, if you work for an insurance company you may want to know if a potential customer's houseis within 500 feet of a flood plain so that you can suggest that they buy flood insurance even though theyare not actually within the flood plain. The following illustration shows this scenario using a bufferedpolygon. The dotted line indicates the boundary of the flood plain and the shaded area shows a 500-footbuffer zone around the boundary.
The buffer area extends on both sides of the boundary (inside and outside). When you use buffering,the output field BufferRelation indicates whether or not the point is in the buffered zone, and whetherthe point is inside or outside of the polygon, as shown in the following illustrations.
The point is outside the polygonbut in the buffer area.
The point is inside the polygonand in the buffer area.
The point is inside the polygonand not in the buffer area.
The output field BufferRelationwill contain "B".
The output field BufferRelationwill contain "I".
The output field BufferRelationwill contain "P".
Specify the size of polygon buffers using the BufferWidth input field to set it on a record-by-record basisand the option to set a default polygon buffer width for the job.
Spectrum Technology Platform 9.0232
CCountry Codes
In this section:
• Country ISO Codes and Module Support . . . . . . . . . . . .234
Country ISO Codes and Module SupportThe following table lists the ISO codes for each country as well as the modules that support addressing,geocoding, and routing for each country.
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
AFGAFAfghanistan
Address Now ModuleUniversal Addressing Module
ALAAXAland Islands
Address Now ModuleUniversal Addressing Module
ALBALAlbania
Address Now ModuleUniversal Addressing Module
DZADZAlgeria
Address Now ModuleUniversal Addressing Module
ASMASAmerican Samoa
Address Now ModuleEnterprise Geocoding Module1
Universal Addressing Module
ANDADAndorra
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
AGOAOAngola
Address Now ModuleUniversal Addressing Module
AIAAIAnguilla
Address Now ModuleUniversal Addressing Module
ATAAQAntarctica
Address Now ModuleUniversal Addressing Module
ATGAGAntigua And Barbuda
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
ARGARArgentina
Address Now ModuleUniversal Addressing Module
ARMAMArmenia
Address Now ModuleUniversal Addressing Module
ABWAWAruba
Address Now ModuleEnterprise Geocoding Module
AUSAUAustralia
Enterprise Routing ModuleUniversal Addressing Module
1 Andorra is covered by the Spain geocoder
Spectrum Technology Platform 9.0234
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleEnterprise Geocoding Module
AUTATAustria
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
AZEAZAzerbaijan
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
BHSBSBahamas
Address Now ModuleUniversal Addressing Module
BHRBHBahrain
Address Now ModuleUniversal Addressing Module
BGDBDBangladesh
Address Now ModuleUniversal Addressing Module
BRBBBBarbados
Address Now ModuleUniversal Addressing Module
BLRBYBelarus
Address Now ModuleEnterprise Geocoding Module
BELBEBelgium
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
BLZBZBelize
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
BENBJBenin
Address Now ModuleUniversal Addressing Module
BMUBMBermuda
Address Now ModuleUniversal Addressing Module
BTNBTBhutan
Address Now ModuleUniversal Addressing Module
BOLBOBolivia, Plurinational State Of
Address Now ModuleUniversal Addressing Module
BESBQBonaire, Saint Eustatius AndSaba
Address Now ModuleUniversal Addressing Module
BIHBABosnia And Herzegovina
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
BWABWBotswana
235REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
BVTBVBouvet Island
Address Now ModuleEnterprise Geocoding Module
BRABRBrazil
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
IOTIOBritish Indian Ocean Territory
Address Now ModuleUniversal Addressing Module
BRNBNBrunei Darussalam
Address Now ModuleUniversal Addressing Module
BGRBGBulgaria
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
BFABFBurkina Faso
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
BDIBIBurundi
Address Now ModuleUniversal Addressing Module
KHMKHCambodia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
CMRCMCameroon
Address Now ModuleEnterprise Geocoding Module
CANCACanada
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
CPVCVCape Verde
Address Now ModuleUniversal Addressing Module
CYMKYCayman Islands
Address Now ModuleUniversal Addressing Module
CAFCFCentral African Republic
Address Now ModuleUniversal Addressing Module
TCDTDChad
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
CHLCLChile
Spectrum Technology Platform 9.0236
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
CHNCNChina
Address Now ModuleUniversal Addressing Module
CXRCXChristmas Island
Address Now ModuleUniversal Addressing Module
CCKCCCocos (Keeling) Islands
Address Now ModuleUniversal Addressing Module
COLCOColombia
Address Now ModuleUniversal Addressing Module
COMKMComoros
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
COGCGCongo
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
CODCDCongo, The DemocraticRepublic Of The
Address Now ModuleUniversal Addressing Module
COKCKCook Islands
Address Now ModuleUniversal Addressing Module
CRICRCosta Rica
Address Now ModuleUniversal Addressing Module
CIVCICôte d'Ivoire
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
HRVHRCroatia
Address Now ModuleUniversal Addressing Module
CUBCUCuba
Address Now ModuleUniversal Addressing Module
CUWCWCuracao
Address Now ModuleUniversal Addressing Module
CYPCYCyprus
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
CZECZCzech Republic
Address Now ModuleEnterprise Geocoding Module
DNKDKDenmark
Enterprise Routing ModuleUniversal Addressing Module
237REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
DJIDJDjibouti
Address Now ModuleUniversal Addressing Module
DMADMDominica
Address Now ModuleUniversal Addressing Module
DOMDODominican Republic
Address Now ModuleUniversal Addressing Module
ECUECEcuador
Address Now ModuleUniversal Addressing Module
EGYEGEgypt
Address Now ModuleUniversal Addressing Module
SLVSVEl Salvador
Address Now ModuleUniversal Addressing Module
GNQGQEquatorial Guinea
Address Now ModuleUniversal Addressing Module
ERIEREritrea
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
ESTEEEstonia
Address Now ModuleUniversal Addressing Module
ETHETEthiopia
Address Now ModuleUniversal Addressing Module
FLKFKFalkland Islands (Malvinas)
Address Now ModuleUniversal Addressing Module
FROFOFaroe Islands
Address Now ModuleUniversal Addressing Module
FJIFJFiji
Address Now ModuleEnterprise Geocoding Module
FINFIFinland
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding Module
FRAFRFrance
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding Module 2
Universal Addressing Module
GUFGFFrench Guiana
2 French Guiana is covered by the France geocoder
Spectrum Technology Platform 9.0238
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
PYFPFFrench Polynesia
Address Now ModuleUniversal Addressing Module
ATFTFFrench Southern Territories
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
GABGAGabon
Address Now ModuleUniversal Addressing Module
GMBGMGambia
Address Now ModuleUniversal Addressing Module
GEOGEGeorgia
Address Now ModuleEnterprise Geocoding Module
DEUDEGermany
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
GHAGHGhana
Address Now ModuleEnterprise GeocodingModule 3UniversalAddressing Module
GIBGIGibraltar
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
GRCGRGreece
Address Now ModuleUniversal Addressing Module
GRLGLGreenland
Address Now ModuleUniversal Addressing Module
GRDGDGrenada
Address Now ModuleEnterprise Geocoding Module 4
Universal Addressing Module
GLPGPGuadeloupe
Address Now ModuleUniversal Addressing Module
GUMGUGuam
Address Now ModuleUniversal Addressing Module
GTMGTGuatemala
Address Now ModuleUniversal Addressing Module
GGYGGGuernsey
3 Gibraltar is covered by the Spain geocoder4 Guadeloupe is covered by the France geocode
239REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
GINGNGuinea
Address Now ModuleUniversal Addressing Module
GNBGWGuinea-Bissau
Address Now ModuleUniversal Addressing Module
GUYGYGuyana
Address Now ModuleUniversal Addressing Module
HTIHTHaiti
Address Now ModuleUniversal Addressing Module
HMDHMHeard Island and McDonaldIslands
Address Now ModuleEnterprise Geocoding Module 5
Universal Addressing Module
VATVAHoly See (Vatican City State)
Address Now ModuleUniversal Addressing Module
HNDHNHonduras
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
HKGHKHong Kong
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
HUNHUHungary
Address Now ModuleUniversal Addressing Module
ISLISIceland
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
INDINIndia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
IDNIDIndonesia
Address Now ModuleUniversal Addressing Module
IRNIRIran, Islamic Republic Of
Address Now ModuleUniversal Addressing Module
IRQIQIraq
Address Now ModuleEnterprise Geocoding Module
IRLIEIreland
Enterprise Routing ModuleUniversal Addressing Module
5 The Vatican is covered by the Italy geocoder
Spectrum Technology Platform 9.0240
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
IMNIMIsle Of Man
Address Now ModuleUniversal Addressing Module
ISRILIsrael
Address Now ModuleEnterprise Geocoding Module
ITAITItaly
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
JAMJMJamaica
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
JPNJPJapan
Address Now ModuleUniversal Addressing Module
JEYJEJersey
Address Now ModuleUniversal Addressing Module
JORJOJordan
Address Now ModuleUniversal Addressing Module
KAZKZKazakhstan
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
KENKEKenya
Address Now ModuleUniversal Addressing Module
KIRKIKiribati
Address Now ModuleUniversal Addressing Module
PRKKPKorea, Democratic People'sRepublic Of
Address Now ModuleUniversal Addressing Module
KORKRKorea, Republic Of
Address Now ModuleUniversal Addressing Module
KOSKSKosovo
Address Now ModuleUniversal Addressing Module
KWTKWKuwait
Address Now ModuleUniversal Addressing Module
KGZKGKyrgyzstan
Address Now ModuleUniversal Addressing Module
LAOLALao People's DemocraticRepublic
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
LVALVLatvia
241REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
LBNLBLebanon
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
LSOLSLesotho
Address Now ModuleUniversal Addressing Module
LBRLRLiberia
Address Now ModuleUniversal Addressing Module
LBYLYLibyan Arab Jamahiriya
Address Now ModuleEnterprise Geocoding Module 6
LIELILiechtenstein
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
LTULTLithuania
Address Now ModuleEnterprise Geocoding Module 7
LUXLULuxembourg
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
MACMOMacao
Address Now ModuleUniversal Addressing Module
MKDMKMacedonia, Former YugoslavRepublic Of
Address Now ModuleUniversal Addressing Module
MDGMGMadagascar
Address Now ModuleUniversal Addressing Module
MWIMWMalawi
Address Now ModuleEnterprise Geocoding Module
MYSMYMalaysia
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
MDVMVMaldives
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
MLIMLMali
6 Liechtenstein is covered by the Switzerland geocoder7 Luxembourg is covered by the Belgium geocoder
Spectrum Technology Platform 9.0242
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
MLTMLMalta
Address Now ModuleUniversal Addressing Module
MHLMHMarshall Islands
Address Now ModuleEnterprise Geocoding Module
MTQMQMartinique
Guadeloupe is covered by the Francegeocode Universal Addressing Module
Address Now ModuleUniversal Addressing Module
MRTMRMauritania
Address Now ModuleUniversal Addressing Module
MUSMUMauritius
Address Now ModuleEnterprise Geocoding Module UniversalAddressing Module
MYTYTMayotte
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
MEXMXMexico
Address Now ModuleUniversal Addressing Module
FSMFMMicronesia, Federated StatesOf
Address Now ModuleUniversal Addressing Module
MDAMDMoldova, Republic Of
Address Now ModuleEnterprise Geocoding Module10Universal Addressing Module
MCOMCMonaco
Address Now ModuleUniversal Addressing Module
MNGMNMongolia
Address Now ModuleUniversal Addressing Module
MNEMEMontenegro
Address Now ModuleUniversal Addressing Module
MSRMSMontserrat
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
MARMAMorocco
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
MOZMZMozambique
8 Martinique is covered by the France geocoder.9 Mayotte is covered by the France geocoder.10 Monaco is covered by the France geocoder
243REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
MMRMMMyanmar
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
NAMNANamibia
Address Now ModuleUniversal Addressing Module
NRUNRNauru
Address Now ModuleUniversal Addressing Module
NPLNPNepal
Address Now ModuleEnterprise Geocoding Module
NLDNLNetherlands
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
NCLNCNew Caledonia
Address Now ModuleEnterprise Geocoding Module
NZLNZNew Zealand
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
NICNINicaragua
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
NERNENiger
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
NGANGNigeria
Address Now ModuleUniversal Addressing Module
NIUNUNiue
Address Now ModuleUniversal Addressing Module
NFKNFNorfolk Island
Address Now ModuleUniversal Addressing Module
MNPMPNorthern Mariana Islands
Address Now ModuleEnterprise Geocoding Module
NORNONorway
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
OMNOMOman
Spectrum Technology Platform 9.0244
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
PAKPKPakistan
Address Now ModuleUniversal Addressing Module
PLWPWPalau
Address Now ModuleUniversal Addressing Module
PSEPSPalestinian Territory,Occupied
Address Now ModuleUniversal Addressing Module
PANPAPanama
Address Now ModuleUniversal Addressing Module
PNGPGPapua New Guinea
Address Now ModuleUniversal Addressing Module
PRYPYParaguay
Address Now ModuleUniversal Addressing Module
PERPEPeru
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
PHLPHPhilippines
Address Now ModuleUniversal Addressing Module
PCNPNPitcairn
Address Now ModuleEnterprise Geocoding Module
POLPLPoland
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding Module
PRTPTPortugal
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
PRIPRPuerto Rico
Address Now ModuleUniversal Addressing Module
QATQAQatar
Address Now ModuleEnterprise Geocoding Module11Universal Addressing Module
REUREReunion
Address Now ModuleUniversal Addressing Module
ROURORomania
11 Reunion is covered by the France geocoder
245REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
RUSRURussian Federation
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
RWARWRwanda
Address Now ModuleUniversal Addressing Module
BLMBLSaint Barthelemy
Address Now ModuleUniversal Addressing Module
SHESHSaint Helena, Ascension &Tristan Da Cunha
Address Now ModuleUniversal Addressing Module
KNAKNSaint Kitts and Nevis
Address Now ModuleUniversal Addressing Module
LCALCSaint Lucia
Address Now ModuleUniversal Addressing Module
MAFMFSaint Martin (French Part)
Address Now ModuleUniversal Addressing Module
SPMPMSaint Pierre and Miquelon
Address Now ModuleUniversal Addressing Module
VCTVCSaint Vincent And TheGrenadines
Address Now ModuleUniversal Addressing Module
WSMWSSamoa
Address Now ModuleEnterprise Geocoding Module 12
Universal Addressing Module
SMRSMSan Marino
Address Now ModuleUniversal Addressing Module
STPSTSao Tome And Principe
Address Now ModuleUniversal Addressing Module
SAUSASaudi Arabia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
SENSNSenegal
Address Now ModuleUniversal Addressing Module
SRBRSSerbia
Address Now ModuleUniversal Addressing Module
SYCSCSeychelles
12 San Marino is covered by the Italy geocoder
Spectrum Technology Platform 9.0246
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
SLESLSierra Leone
Address Now ModuleEnterprise Geocoding Module
SGPSGSingapore
Enterprise Routing ModuleUniversal Addressing Module
Universal Addressing ModuleSXMSXSint Maarten (Dutch Part)
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
SVKSKSlovakia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
SVNSISlovenia
Address Now ModuleUniversal Addressing Module
SLBSBSolomon Islands
Address Now ModuleUniversal Addressing Module
SOMSOSomalia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
ZAFZASouth Africa
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
SGSGSSouth Georgia And The SouthSandwich Islands
Address Now ModuleUniversal Addressing Module
SSDSSSouth Sudan
Address Now ModuleEnterprise Geocoding Module
ESPESSpain
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
LKALKSri Lanka
Address Now ModuleUniversal Addressing Module
SDNSDSudan
Address Now ModuleUniversal Addressing Module
SURSRSuriname
Address Now ModuleUniversal Addressing Module
SJMSJSvalbard And Jan Mayen
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
SWZSZSwaziland
247REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleEnterprise Geocoding Module
SWESESweden
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding Module
CHECHSwitzerland
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
SYRSYSyrian Arab Republic
Address Now ModuleUniversal Addressing Module
TWNTWTaiwan, Province of China
Address Now ModuleUniversal Addressing Module
TJKTJTajikistan
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
TZATZTanzania, United Republic Of
Address Now ModuleEnterprise Geocoding Module
THATHThailand
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
TLSTLTimor-Leste
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
TGOTGTogo
Address Now ModuleUniversal Addressing Module
TKLTKTokelau
Address Now ModuleUniversal Addressing Module
TONTOTonga
Address Now ModuleUniversal Addressing Module
TTOTTTrinidad and Tobago
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
TUNTNTunisia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
TURTRTurkey
Address Now ModuleUniversal Addressing Module
TKMTMTurkmenistan
Spectrum Technology Platform 9.0248
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
TCATCTurks And Caicos Islands
Address Now ModuleUniversal Addressing Module
TUVTVTuvalu
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
UGAUGUganda
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
UKRUAUkraine
Address Now ModuleUniversal Addressing Module
AREAEUnited Arab Emirates
Address Now ModuleEnterprise Geocoding Module
GBRGBUnited Kingdom
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleEnterprise Geocoding Module
USAUSUnited States
Enterprise Routing ModuleUniversal Addressing Module
Address Now ModuleUniversal Addressing Module
UMIUMUnited States Minor OutlyingIslands
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
URYUYUruguay
Address Now ModuleUniversal Addressing Module
UZBUZUzbekistan
Address Now ModuleUniversal Addressing Module
VUTVUVanuatu
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
VENVEVenezuela, BolivarianRepublic Of
Address Now ModuleUniversal Addressing Module
VNMVNViet Nam
Address Now ModuleUniversal Addressing Module
VGBVGVirgin Islands, British
Address Now ModuleUniversal Addressing Module
VIRVIVirgin Islands, U.S.
Address Now ModuleUniversal Addressing Module
WLFWFWallis and Futuna
249REST Web Services Guide
Appendix C: Country Codes
Supported ModulesISO 3116-1Alpha-3
ISO 3116-1Alpha-2
ISO Country Name (English)
Address Now ModuleUniversal Addressing Module
ESHEHWestern Sahara
Address Now ModuleUniversal Addressing Module
YEMYEYemen
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
ZMBZMZambia
Address Now ModuleEnterprise Geocoding ModuleUniversal Addressing Module
ZWEZWZimbabwe
Spectrum Technology Platform 9.0250
DValidateAddress ConfidenceAlgorithm
In this section:
• Introduction to the Validate Address ConfidenceAlgorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
• Confidence Algorithm for U.S. and Canadian Addresses .252• Confidence Algorithm for International Addresses . . .253
Introduction to the Validate Address Confidence AlgorithmValidateAddress computes a confidence score for each validated address. This score describes howlikely it is that the validated address is correct. Confidence code values range from 0 to 100, with a zeroconfidence level indicating no confidence and 100 indicating a very high level of confidence that thematch results are correct. Confidence codes are calculated based on an algorithm that takes into accountthe match results for individual output fields. The output fields involved in this calculation include:
• Country• City• State• PostalCode• StreetName• HouseNumber• LeadingDirectional• TrailingDirectional• StreetSuffix• ApartmentNumber
Each field has its own Weight in the algorithm. Additionally, for each field the match result could belabeled as Success, Failure, or Changed. ("Changed" refers to cases where the contents of the fieldhave been corrected in order to get a match.) The match result—Success, Failure, orChanged—determines what the Factor is for that field. Thus, the calculation for the confidence code isa product of Weight by Factor as follows:
Confidence = (Weight * Factor) for City+ (Weight * Factor) for Country+ (Weight * Factor) for State+ (Weight * Factor) for PostalCode+ (Weight * Factor) for StreetName+ (Weight * Factor) for HouseNumber+ (Weight * Factor) for Directionals+ (Weight * Factor) for Street Suffix+ (Weight * Factor) for ApartmentNumber
Confidence Algorithm for U.S. and Canadian AddressesThe following table details the scoring and logic behind the ValidateAddress confidence algorithm forU.S. and Canadian addresses.
Table 99: Confidence Algorithm for U.S. and Canadian Addresses
Factor If Filled14Factor ifChanged13
Weight/Match ScoreField
0%100%10Country
75%50%10City
75%50%15State
25%25%15PostalCode
75%50%15StreetName
14 Refers to instances when the input data in this field is not present but is filled in order to achievea match.
13 Refers to instances when the input data in this field is changed in order to achieve a match.
Spectrum Technology Platform 9.0252
Factor If Filled14Factor ifChanged13
Weight/Match ScoreField
75%50%15HouseNumber
75%50%10Directionals
75%50%5StreetSuffix
75%50%5ApartmentNumber
Confidence Algorithm for International AddressesThere are two confidence algorithms for addresses outside the U.S. and Canada, one for addresses incountries that use postal codes and one for addresses in countries that do not use postal codes.
The following table details the confidence algorithm for non-U.S. and non-Canadian addresses fromcountries that use postal codes.
Table 100: Confidence Algorithm for Countries With Postal Codes
Factor if PostalDataUnavailable
Factor IfFilled16
Factor ifChanged15
Weight/Match ScoreField
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
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.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.
253REST Web Services Guide
Appendix D: ValidateAddress Confidence Algorithm
The following table details confidence algorithm for countries that do not use postal codes.
Table 101: Confidence Algorithm for Countries Without Postal Codes
Factor if PostalDataUnavailable
Factor IfFilled19
Factor ifChanged18
Weight/Match ScoreField
0%0%100%13.3333333333333Country
0%75%2050%13.3333333333333City
80%100100%20State
50%75%50%20StreetName
50%75%50%20HouseNumber
0%75%50%0Directionals
50%75%50%6.66666666666667StreetSuffix
50%75%50%6.66666666666667ApartmentNumber
The following table lists countries without postal codes.
Table 102: Countries Without Postal Codes
AngolaAlbaniaAfghanistan
BarbadosBahamasAnguilla
BhutanBeninBelize
BurundiBurkina FasoBotswana
Central African Rep.Cayman IslandsCameroon
ColumbiaCocos IslandsChad
Congo (Rep.)Congo (Dem. Rep.)Comoros
DjiboutiKorea (North)Cote d'Ivoire
EritreaEquatorial GuineaDominica
GambiaGabonFiji
GuyanaGrenadaGhana
19 Refers to instances when the input data in this field is not present but is filled in order to achievea match.
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.
Spectrum Technology Platform 9.0254
KiribatiJamaicaIreland
MaliMalawiLibya
NauruNamibiaMauritania
PeruPanamaPalaos
Saint LuciaRwandaQatar
Sao Tome & PrincipeSamoaSaint Vincent & Grenadines
SurinameSierra LeoneSeychelles
TogoTimorTanzania
TuvaluTrinidad & TobagoTonga
VanuatuUnited Arab EmiratesUganda
ZimbabweYemen
255REST Web Services Guide
Appendix D: ValidateAddress Confidence Algorithm
Notices
© 2013 Pitney Bowes Software Inc. All rights reserved. MapInfo and Group 1 Software are trademarksof Pitney Bowes Software Inc. All other marks and trademarks are property of their respective holders.
USPS® Notices
Pitney Bowes Inc. holds a non-exclusive license to publish and sell ZIP + 4® databases on optical andmagnetic media. The following trademarks are owned by the United States Postal Service: CASS, CASSCertified, DPV, eLOT, FASTforward, First-Class Mail, Intelligent Mail, LACSLink, NCOALink, PAVE,PLANET Code, Postal Service, POSTNET, Post Office, RDI, SuiteLink , United States Postal Service,Standard Mail, United States Post Office, USPS, ZIP Code, and ZIP + 4. This list is not exhaustive ofthe trademarks belonging to the Postal Service.
Pitney Bowes Inc. is a non-exclusive licensee of USPS® for NCOALink® processing.
Prices for Pitney Bowes Software's products, options, and services are not established, controlled, orapproved by USPS® or United States Government. When utilizing RDI™ data to determine parcel-shippingcosts, the business decision on which parcel delivery company to use is not made by the USPS® orUnited States Government.
Data Provider and Related Notices
Data Products contained on this media and used within Pitney Bowes Software applications are protectedby various trademarks and by one or more of the following copyrights:
© Copyright United States Postal Service. All rights reserved.
© 2013 TomTom. All rights reserved. TomTom and the TomTom logo are registered trademarks ofTomTom N.V.
© Copyright NAVTEQ. All rights reserved
Data © 2013 NAVTEQ North America, LLC
Fuente: INEGI (Instituto Nacional de Estadística y Geografía)
Based upon electronic data © National Land Survey Sweden.
© Copyright United States Census Bureau
© Copyright Nova Marketing Group, Inc.
Portions of this program are © Copyright 1993-2007 by Nova Marketing Group Inc. All Rights Reserved
© Copyright Canada Post Corporation
This CD-ROM contains data from a compilation in which Canada Post Corporation is the copyright owner.
© 2007 Claritas, Inc.
The Geocode Address World data set contains data licensed from the GeoNames Project(www.geonames.org) provided under the Creative Commons Attribution License ("Attribution License")located at http://creativecommons.org/licenses/by/3.0/legalcode. Your use of the GeoNames data(described in the Spectrum™ Technology PlatformUser Manual) is governed by the terms of the AttributionLicense, and any conflict between your agreement with Pitney Bowes Software, Inc. and the AttributionLicense will be resolved in favor of the Attribution License solely as it relates to your use of the GeoNamesdata.
ICU Notices
Copyright © 1995-2011 International Business Machines Corporation and others.
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software andassociated documentation files (the "Software"), to deal in the Software without restriction, includingwithout limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of theSoftware, and to permit persons to whom the Software is furnished to do so, provided that the above
Spectrum Technology Platform 9.0258
copyright notice(s) and this permission notice appear in all copies of the Software and that both theabove copyright notice(s) and this permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THEWARRANTIES OF MERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NOEVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLEFORANYCLAIM,ORANYSPECIAL INDIRECTORCONSEQUENTIALDAMAGES,ORANYDAMAGESWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTIONOF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR INCONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in advertising orotherwise to promote the sale, use or other dealings in this Software without prior written authorizationof the copyright holder.
259REST Web Services Guide
Copyright