W1.10 The US Addressing Web Service – Software Support

matchIT Web Index

The US Addressing Web Service is a distinct web service and can be used after installing matchIT web and the USA address data, however you do not need to load the configuration file using the administrative application prior to getting results.

The US Addressing Web Service uses the local address data resource files, so these will need to be installed on the machine. Also please note for some Windows users there is a problem with accessing the data files. By default the files will be located at :

C:\addressIT_Data

To fix this issue on Windows Server 2008, you will need to add permission for the IIS User running the findIT S2 app pool to the ACMDATA directory in the folder where the US address data was installed.

Web Service Methods

The following methods are exposed within the US addressing web service and explained in the section below.

ConfirmAddress – This method returns a $ delimited list of address elements for a supplied address.

This will return the following results string :

Y$95118-4007$Address was DPV confirmed for both primary and (if present) secondary numbers$5020 Russo Dr$San Jose$CA$$5020$$Russo$Dr$$$$$$$$$San Jose, CA 95118-4007$Santa Clara$085$4007$$0162$A$$16$C026$N$

</string>

The delimited parts are as follows :

DPV RESULT CODE
ZIP CODE WITH +4
DPV ANSWER DESCRIPTION
STREET LINE
CITY
STATE
COMPANY
HOUSE NUMBER
PRE DIRECTIONAL
STREET NAME
SUFFIX
POST DIRECTIONAL
POSTAL MAIL BOX
SECOND STREET LINE
ADDRESS LEFTOVERS
SUITE NUMBER/NAME
SUD
UNIT NUMBER
URBANIZATION CODE
LASTLINE OF ADDRESS
COUNTY NAME
COUNTY NUMBER
ZIP4
RDI
LINE OF TRAVEL
LOT OF TRAVEL DIRECTIONAL
LACS CODE
CONGRESSIONAL DISTRICT
CRRT
DPV CMRA

ConfirmAddressXML – This method accepts/returns the same data as ConfirmAddress, however it formats the results as an XML string, as follows :

<dpv_answer value="Y" />

<dpv_answer_text value="Address was DPV confirmed for both primary and (if present) secondary numbers" />

<lot_dir value="A" />

<congress_dist value="16" />

<dpv_cmra value="N" />

</results>

</string>

If an error or warning is encountered with the address lookup, an XML string of the following format will be returned by ConfirmAddressXML

</results>

</string>

A complete list of these error values can be found in Appendix C.

GetCityState – This method returns a $ delimited list of the city and state for a selected ZIP code.

Examples as follows :

For a ZIP located wholly in a city or state, you would get the following response

For a ZIP located partially in a city, we use the return value, Multiple

<string xmlns="http://tempuri.org/">Multiple$NH</string>

GetCityStateXML – This method returns an XML string containing a list of possible cities and states for the selected ZIP code. This function has additional functionality, to allow a user to see the actual cities or states returned in full, without use of the keyword ‘Multiple’. Here is an example return string for multiple results.

</results>

</string>

GetDPV – This method returns a $ delimited list of elements to allow a user to establish what the correct Delivery Point Verification code is for a selected address.

<string xmlns="http://tempuri.org/">95118-4007$Y$San Jose$CA$5020 Russo Dr$</string>

The output delimitation is as follows :

ZIP+4 Code
DPV Correction Result
City Value
State Value
Street Value (N.B. That apartment or sub-premise information is passed and returned in this line)

GetDPVXML – Identical to the above, however the return details are presented as an XML string :

<dpv_answer value="Y" />

</results>

</string>

ReturnTIGERData – TIGER Data is a USPS data set that allows ZIP codes to be matched to geographical location. A user will submit a ZIP+4 code and the additional data files will work out the location of the centroid for this location, and then present longitude and latitude data back in the XML return value.

If an invalid ZIP+4 is entered, the lookup will attempt to locate the centroid for just the ZIP code portion, ignoring the +4 element, This will compromise the accuracy somewhat, so it’s important if consistent accurate results are required that an well formatted and verified ZIP+4 is supplied to this web method.

The output is as follows :

</results>

</string>

count

The number of data points contained at this ZIP+4 location.

latitude

The angular distance north or south from the equator of a point on the earth's surface, measured on the meridian of the point.

longitude

The angular distance east or west on the earth's surface, measured by the angle contained between the meridian of a particular place and some prime meridian, as that of Greenwich, England, and expressed either in degrees or by some corresponding difference in time.

block

Blocks are numbered uniquely within each census tract with a 3-character number that identifies the collection block used in the census and a character block suffix. This character block suffix is often blank.

cmsa

A 4-digit code assigned to areas that consist of primary metropolitan statistical areas.

latFrom

The north/south measurement indicating the beginning point of the address.

latTo

A north/south measurement indicating the ending point of the address.

lonfrom

The east/west measurement indicating the beginning point of the address.

lonTo

The east/west measurement indicating the ending point of the address.

plus4

Describes the last four positions of a ZIP+4 Code. Most delivery addresses are assigned a single ZIP+4 Code. However, large companies may be given a range of ZIP+4 Codes that can be used to route mail to a specific department.

pmsa

A 4-digit code assigned to areas that comprise one or more counties, including a major population nucleus and nearby communities that have a high degree of interaction.

side

Side indicate what side of the line segment the location occurs at, this is why Lat/Long From and To are returned, to allow identification of the location based on the range of the location. The side is loosely related to the side of a street or highway the ZIP+4 is located, but translating this to an actual side of a road is unreliable.

tract

Small, locally delineated statistical areas within selected counties, generally having stable boundaries and, when first established by local communities, designed to have relatively homogeneous demographic characteristics.

Reverse9Lookup – We have added the ability to look up an address based on just the ZIP+4 details in light of customer feedback.

This function is independent from the findIT S2 interface, as there are some USPS restrictions on how we can return data from this service. We appreciate however that this web method may be useful in certain situations.

By entering a full ZIP+4 code you get the following XML return string

</results>

</string>

Note the USPS will work out the address down to the level of granularity the DPV data supports, in most cases, this will not allow a full street name and street number to be returned. The above examples demonstrate how question marks are used as wildcards, which will then have to be validated manually.

However there are definite keying benefits to certain systems when using a Full ZIP+4 reverse lookup, and so is good source of lookup if the source information is available.

getTypeDown – This web method is used to return a candidate list of potential street names and premise details from a ZIP code.

The method asks for a ZIP code then the first x letters of address line 1 to lookup a list of possible streets.

You need to pass the first x letters for address line 1, the number of results you want to return, the contextKey (which is the reference to your current lookup) to access the specific results and the ZIP Code.

This will return the results in XML format as follows :

<string>5020 Durango Ct</string>

<string>5020 El Roble Ct</string>

<string>5020 Howes Ln</string>

<string>5020 Hawley Ct</string>

<string>5020 Jarvis Ave</string>

<string>5020 Joseph Ln</string>

<string>5020 Gelia Way</string>

<string>5020 Carter Ave</string>

<string>5020 Corbin Ave</string>

<string>5020 Las Cruces Ct</string>

<string>5020 Lenelle Ct</string>

<string>5020 Russo Dr</string>

<string>5020 Rio Verde Dr</string>

<string>5020 Rebel Ct</string>

<string>5020 Sutcliff Ave</string>

<string>5020 Trenary Way</string>

<string>5020 Tifton Way</string>

<string>5020 Wayland Ave</string>

<string>5020 Yucatan Way</string>

</ArrayOfString>

The main usage of this method is for a typedown interface to allow auto fill of the first line of address. The only restriction is that you need to capture the ZIP code first, to allow the candidate list to be populated. The more information that is submitted with the first line of address the smaller the list of candidates. Within the findIT S2 interface we restrict this in a couple of ways. Firstly we only trigger the event after the first space in the address1 line using the AJAX control, then we limit the results to the number specified in the <maxrecords value="???" /> node of findITConfiguration.xml , to maintain a manageable group of possible candidates, but aid keying speed at the same time.

TypeDownCityStateXML

This is the first of the ‘TypeDown’ style methods offered by the US Addressing Web Service. With TypeDownCityStateXML, it is possible to enter a city, city and state, or just state, to get a complete list of city / state combinations that match the input. For example, if you wanted to retrieve a complete list of cities in Texas, you would simply leave the city argument blank, and pass TX (or Texas) as the state argument. The XML Returned would look as follows –

...(Not all results shown)

</results>

TypeDownStreetsFromCityStateXML

A filtered result from the previous method, TypeDownCityStateXML, can be used in this method to retrieve a complete list of streets in the city. Foe example, using the result Red Lake, TX, we get the following

...(Not all results shown)

</results>

From these results, it is important to take note of the zip, zipindex and streetindex in particular for use in the ‘TypeDownPrimaryRangeXML’ method.

TypeDownStreetsFromZIPXML

This method returns exactly the same results as TypeDownStreetsFromCityStateXML, however the argument required by this method is the zip. Looking at the example above, passing the ZIP 75855 to this method would have yielded exactly the same result.

TypeDownPrimaryRangeXML

This method is used to get a list of primary premise ranges for a given street for a particular zip. The arguments required are the zip, zip index and street index from a ‘TypeDownStreetsXML’ call. Using the first result in the example above (75855, 0, 0) you will get the following result –

...(First Result Only Shown)

</results>

Note that from this result, as well as keeping hold of the zip, zip index and street index, we now need to make note of the primary index, for use in the TypeDownSecondaryRangeXML method.

TypeDownSecondaryRangeXML

This method is used to get a list of secondary premise ranges for a primary premise on a given street for a particular zip. The arguments required are the zip, zip index, street index and primary index from a ‘TypeDownPrimaryRangeXML’ call. As can be seen in the example above, the secondaryavailable attribute is set to false, indicating that no secondary premise range is available, so a call will not yield any results. If it was set to true however, a call could be made to further verify the secondary premise of an address.

matchIT Web Index