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 :
<string xmlns="http://tempuri.org/">
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
- DPB
- RECORDTYPE
- ERRORCODE
ConfirmAddressXML – This method accepts/returns the same data as ConfirmAddress, however it formats the results as an XML string, as follows :
<string xmlns="http://tempuri.org/">
<results>
<dpv_answer value="Y" />
<zip value="95118-4007" />
<dpv_answer_text value="Address was DPV confirmed for both primary and (if present) secondary numbers" />
<street value="5020 Russo Dr" />
<city value="San Jose" />
<state value="CA" />
<company value="" />
<housenum value="5020" />
<predir value="" />
<streetname value="Russo" />
<suffix value="Dr" />
<postdir value="" />
<pmb value="" />
<street2 value="" />
<leftovers value="" />
<suite value="" />
<sud value="" />
<unitnum value="" />
<urb value="" />
<lastline value="San Jose CA 95118-4007" />
<countyname value="Santa Clara" />
<countynum value="085" />
<zip4 value="4007" />
<rdi value="Y" />
<lot value="0037" />
<lot_dir value="A" />
<lacs value="" />
<congress_dist value="18" />
<crrt value="C026" />
<dpv_cmra value="N" />
<dpb value="951184007203" />
<recordtype value="S" />
<errorcode value="" />
</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
<string xmlns="http://tempuri.org/">
<results>
<error value="7: There are no street name matches in the given ZIP code or in any geographically-related ZIP code." />
</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
<string xmlns="http://tempuri.org/">San Jose$CA</string>
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.
<string xmlns="http://tempuri.org/">
<results>
<zipCityState zip="03579" city="Errol" state="NH" />
<zipCityState zip="03579" city="Wentworths Location" state="NH" />
<zipCityState zip="03579" city="Wntwrths Lctn" state="NH" />
</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 :
<string xmlns="http://tempuri.org/">
<results>
<zip4 value="95118-4007" />
<dpv_answer value="Y" />
<city value="San Jose" />
<state value="CA" />
<street value="5020 Russo Dr" />
</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 :
<string xmlns="http://tempuri.org/">
<results>
<Count value="2" />
<Latitude value="+037.257643" />
<Longitude value="-121.881765" />
<Block value="1005" />
<CMSA value="7362" />
<LatFrom value="37257643" />
<LatTo value="37258186" />
<LongFrom value="-121881765" />
<LongTo value="-121882630" />
<Plus4 value="2701" />
<PMSA value="7400" />
<Side value="82" />
<Tract value="502910" />
</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
<string xmlns="http://tempuri.org/">
<results>
<zip value="95128" />
<zipPlus4 value="4007" />
<city value="San Jose" />
<state value="CA" />
<company value="" />
<street value="11?? Greenbriar Ave" />
<suite value="" />
<housenumber value="11??" />
<predir value="" />
<streetname value="GREENBRIAR" />
<postdir value="" />
<streetsuffix value="AVE" />
<sud value="" />
<unit value="" />
</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 :
<ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.org/">
<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 –
<results>
<citystatedata city="Red Lake" state="TX" />
<citystatedata city="Bagwell" state="TX" />
<citystatedata city="Gilmer" state="TX" />
<citystatedata city="Dike" state="TX" />
...(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
<results>
<streetdata zip="75855" zipindex="0" streetindex="0" predir="" street="RR 1" suffix="" postdir="" city="Oakwood" state="TX" />
<streetdata zip="75855" zipindex="0" streetindex="1" predir="" street="RR 1" suffix="" postdir="" city="Oakwood" state="TX" />
<streetdata zip="75855" zipindex="0" streetindex="2" predir="" street="RR 2" suffix="" postdir="" city="Oakwood" state="TX" />
<streetdata zip="75855" zipindex="0" streetindex="3" predir="" street="RR 2" suffix="" postdir="" city="Oakwood" state="TX" />
<streetdata zip="75855" zipindex="0" streetindex="4" predir="" street="RR 3" suffix="" postdir="" city="Oakwood" state="TX" />
<streetdata zip="75855" zipindex="0" streetindex="5" predir="" street="RR 3" suffix="" postdir="" city="Oakwood" state="TX" />
...(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 –
<results>
<premisedata zip="75855" zipindex="0" streetindex="0" primaryindex="0" lowprem="" highprem="" parity="" outcrrt="R001" outzip4="9801" outcompany="" secondaryavailable="False" />
...(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.
Advanced settings
Lower level addressing API settings can be controlled by modifying the web.config (normally located in C:\Program Files\matchIT Web\website\USAddressingWebService)
you would locate the corresponding node, and can control it by changing the value= from "true" to "false"
<add key="EnableDpv" value="true"/>
These settings may impact the results in most cases of the following calls:
ConfirmAddress, ConfirmAddressXML, getDPV, getDPVXML
AllowDPVNoMatch - . If set to true, generated address elements are returned where there's no DPV match.
Otherwise, Error 19 is returned is returned when an address is valid only down to the street, but not the premise, and no address elements are returned
*This setting requires you are running 2.5.1.2 or newer
UseMixedCase - addresslines are returned Mixed Case when active, or UPPER CASE
when off.
UseAlias - when active, addresses are returned using alias street names when
these are used in the input. When off - only official street names are used.