DOTS Address Validation 2 – US

• Introduction
• Integration
• Web Service Structure
• Operation Definitions
  • ValidateAddress
  • ValidateAddressWithExtras
  • ValidateAddressWithFragments
  • ValidateAddressWithDPV
  • GetPossibleMatches
  • ValidateAddressSingleLine
  • ValidateAddressType
  • ValidateCityStateZip
  • ParseAddress
  • ValidateAddressWithRDI
  • ValidateAddressWithSuiteLink
• Error Codes
• Frequently Asked Questions
• Conclusion

Introduction

DOTS Address Validation 2 US (AV2) is a publicly available XML web service that provides parsed and corrected information about a physical US address.  The service provides corrected information such as the correct street location and zip plus four code, along with parsed address tokens, such as the PMB box number, pre- and post-directionals, county and state codes, and much more.

AV2 can provide instant address verification and correction to websites or enhancement to contact lists.  However, the output from AV2 must be considered carefully before the existence or non-existence of an address is decided.

Integration

Integrating AV into your application should be easy and straightforward.  If you are using a common platform, Service Objects may already have sample code built that you can use:
https://www.serviceobjects.com/developers/sample-code/address-validation-us-legacy

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example.  Email support@serviceobjects.com for more details.

Web Service Structure

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic.  Web services are too large of a topic to cover in this document, but ServiceObjects has developed its web services to be as easy to integrate and as accessible as possible.

AV is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/av2/AddressValidate.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link.):
https://trial.serviceobjects.com/av2/AddressValidate.asmx?WSDL

Every web service has operations that it offers to subscribers – methods that do different work and return different output.  Examining the link above, you will notice several of these operations available, which are described in detail later on.

ValidateAddress – validates an address’s authenticity, and appends locational metadata about the address.
ValidateAddressWithExtras – like ValidateAddress, but accepts an Address2 field in the case that it may help with the address’s validation.
ValidateAddressWithFragments – like ValidateAddress, but returns parsed elements of the address’s street location.
GetPossibleMatches – like ValidateAddressWithFragments, but may return many possible matches.
ValidateAddressSingleLine – like ValidateAddressWithFragments, but takes all the address’s elements on the same line.
ValidateAddressType – Returns address type information about an address –whether it is a PO Box, street location, high-rise, etc.
ValidateCityStateZip – Returns whether the given city/state/zip combination match correctly.
ParseAddress – returns a corrected address’s parsed elements and fragments, even if the address did not validate.  Much like ValidateAddressWithFragments, only guaranteed to return parsed address information.
ValidateAddressWithDPV – Returns parsed and validated address elements including Delivery Point Validation.
ValidateAddressWithRDI – Functions identically to ValidateAddressWithDPV except it also returns the “Residential Delivery Indicator” (RDI) flag. This operation is only available to active DOTS Address Validation – US subscribers through a special agreement. Please call Service Objects for more information about the RDI operation.
ValidateAddressWithSuiteLink – Functions identically to ValidateAddressWithDPV except it accepts a business name to potentially append Suite data if it’s missing.

Each of these operations will be described in detail later in this document.

Operation Definitions

This document defines the input, output and behavior of the web service operations in AV2.  Each operation has its own unique behavior and output, although some of the operations are very similar.

ValidateAddress

This is the basic operation for validating and correcting a US address.  This operation takes a standard US address (Address, City, State, Zip) and will try to verify its authenticity and return validated address elements.  It cannot always find the location, especially when it comes to empty lots or new construction areas.

This operation will also return locational metadata, such as county name/code, congress code, and barcode digits, for the given address.  This data is valuable for tracking demographics and statistical analysis.

This operation requires the Address value, and either City and State, or the Zip code.  Providing all inputs is recommended, because it helps the validation proceed if some of the elements are malformed.

ValidateAddress Inputs

ValidateAddress Outputs

ValidateAddressWithExtras

This operation is almost exactly like ValidateAddress, but rather than taking only an Address1 (Address) element, it also accepts an Address2.  Typically, AV will only use Address2 in the case that Address1 is a nonsensical element (e.g., “Smith Building”.)  However, if the Address2 is an element that does not assist with the validation of an address, it will be passed through to the output without any modifications made to it.  For example, an Address2 of “Next to the stairs” does not assist with validation, but would be necessary for the delivery of packages to that address.

For operations that do not take Address2, you can append a comma, then a space, then your Address2 to the Address line, and it will be processed as the Address2.   For example, if you had an Address like:

ValidateAddressWithExtras Inputs

ValidateAddressWithExtras Outputs

ValidateAddressWithFragments

This operation is almost exactly like ValidateAddress, but instead returns all the parsed fragment tokens from the validated address.

ValidateAddressWithFragments Inputs

ValidateAddressWithFragments Outputs

ValidateAddressWithDPV

Returns parsed and validated address elements including Delivery Point Validation.

ValidateAddressWithDPV Inputs

ValidateAddressWithDPV Outputs

DPV Codes

GetPossibleMatches

This operation is almost exactly like ValidateAddressWithFragments, but may return multiple address with fragments.

GetPossibleMatches Inputs

GetPossibleMatches Outputs

ValidateAddressSingleLine

Often, users have addresses as a single line of data, which may or may not be separated by commas, slashes, spaces, etc.  For this reason, ValidateAddressSingleLine behaves almost exactly like ValidateAddressWithFragments, but takes all of its input as a single field. 

ValidateAddressSingleLine Inputs

ValidateAddressSingleLine Outputs

ValidateAddressType

This operation returns the validated address’s type.  Possible types are:

S – Street address

P – Post office box

R – Rural route or highway contract

H – High rise apartment or office building

F – Firm or business

G – General delivery

ValidateAddressType Inputs

ValidateAddressType Outputs

ValidateCityStateZip

This operation will validate that a given city-state-zip validate together properly.  The inputs can be marginally incorrect, and this operation will correct them.  For instance, a combination with a valid city, slightly misspelled state, and totally incorrect zip code will be corrected to a valid city – state – zip code combination.

ValidateCityStateZip Inputs

ValidateCityStateZip Outputs

ParseAddress

This operation will parse the corrected address out into logical fragment elements, much like ValidateAddressWithFragments, but will return these parsed fragments even if the given address did not validate properly. 

ParseAddress Inputs

ParseAddress Outputs

ValidateAddressWithRDI

Identical to the ValidateAddressWithDPV operation but also returns RDI (Residential Delivery Indicator) data in the form of the “IsResidential” output node. Returns parsed and validated address elements including Delivery Point Validation.

This operation is only available to DOTS Address Validation – US subscribers through a special agreement. Please contact Service Objects at (805) 963-1700 or by emailing the sales department at sales@serviceobjects.com for more information about Residential Delivery Indicator.

ValidateAddressWithRDI Inputs

ValidateAddressWithRDI Outputs

DPV Codes

ValidateAddressWithSuiteLink

Identical to the ValidateAddressWithDPV operation but also accepts a business name in order to attempt to append Suite data. Also returns parsed and validated address elements including Delivery Point Validation.

ValidateAddressWithSuiteLink Inputs

ValidateAddressWithSuiteLink Outputs

DPV Codes

Error Codes

Error codes in AV2 are the same for all operations.  They are as follows:

Error Code 1 — “Input cannot be less than zero length”

This error means the web service did not get any input.  The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand.

This error often happens when input is passed to the service with namespaces that the service does not understand.  Applying a namespace to any of the parameters (Address, City, State, etc.) will cause this error.  Additionally, requests made in the “rpc/encoded” format will cause this error.  The only namespace that should appear in any element is the “https://www.serviceobjects.com” namespace on the root Validate* element as so:

<ValidateAddress xmlns="https://www.serviceobjects.com/">

Error Code 2 — Various descriptions

This error code appears when various errors occur, but are of the expected nature.  Oftentimes, maligned or incomplete input will cause an error 2.

The following is a list of the possible Error Descriptions that may accompany an Error Code 2:

Bad or Incomplete Addresses Errors:

• “Address and Address2 fields were too long.  Together, they must be 100 characters or less.”
• “Address field was too long, must be 100 characters or less.”
• “Address not found”
• “Firm/Highrise name conflict”
• “Multiple addresses match”
• “Insufficient address data”
• “Please enter a valid address number.”
• “Please input a street address.”
• “Please input either zip code or both city and state.”
• “PR Urb not found in city street list”
• “Street not found”
• “Street Not Found”
• “Street number or box number out of range”

Failed Authentication Errors:

• “Please provide a valid license key for this web service.”
• “The daily allowable number of transactions for this license key has been exceeded.”
• “The monthly allowable number of transactions for this license key has been exceeded.”
• “The total allowable number of transactions for this license key has been exceeded.”
• “There are not enough transactions available.  Check your daily/monthly transaction limits.”
• “This license key has expired.”
• “This license key has not yet been activated.”
• “This operation is limited to specific usage.  Please contact customer service to have your key enabled.”
• “Your license key does not work on this service.”

Web Service Invocation Errors:

• “Address could not be found, search timed out.”
• “City has no streets (Unable to load street list)”
• “Could not parse address line.  Internal error “
• “Error initializing service”
• “Internal error.”
• “Server busy. Please try your request again.”
• “This operation is not supported with this data provider.”
• “Multiple addresses match” means that there was an ambiguity about the address, most likely having to do with the street directional.  Often, if there is a “West Main St” and an “East Main St” in a given location, trying to validate just “Main St” will give a “multiple addresses match” error.

Error Code 3/4/5 — Various descriptions

An error code 3, 4, or 5 is a fatal error and it means something serious has gone wrong.  You will never see one of these error codes in a live production environment.

Frequently Asked Questions

Which Operation Should I Use?

Picking which operation you want to use should be decided carefully.  Depending on your environment and needs, you will need to use different operations for their corresponding strengths. As of this writing, we recommend ValidateAddressWithDPV as it provides standardization, validation, fragment returns, DPV descriptions, and corrections.

If you only want to standardize your address and don’t mind if it’s not “DPV” valid, you could use our “ParseAddress” operation. If your addresses are not parsed out into address1, address2, city, state, and zip code, you could use our ValidateAddressSingleLine operation and put the entire address string into one line.

If you have an Address2 field, you can use any operation with the proper input.  See the question below for more information.

I Have Address2 elements.  What should I do?  How do I give you Address2 if I’m using an operation that doesn’t have an Address2 input?

You can either switch operations, or you can concatenate your Address2 data onto your Address1 line, separated by a comma. The operation will interpret everything after the comma as secondary address information.

If you need fragment elements, it is highly recommended that you use ValidateAddressWithDPV or ValidateAddressWithFragments.  If not, use ValidateAddressWithExtras to save you from having to concatenate the Address2 to the Address1 field.

For example, if your address is:

I have an Address3.  What should I do with it?

We currently don’t support any handling of the Address3 field.  Passing it in as part of either the Address1 or Address2 fields is not recommended, as it may inhibit validation. If this information must be included, then your best option is to append all your address lines together separated by spaces, and sent through our ValidateAddressSingleLine operation along with city, state, and zip code appended.

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to ServiceObjects.  Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses.

The easiest way to check for this is to open a browser on the machine running the sample code.  In your browser, navigate to:
https://trial.serviceobjects.com/av2/AddressValidate.asmx

Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn’t able to connect either.  Contact your systems administrator to resolve why you are not able to connect to ServiceObjects.

Address Validation says it can’t find my street!

DOTS Address Validation doesn’t know about every address, especially empty lots or new streets.  Often, it won’t be able to validate these locations.  In general, we are as good as the USPS at identifying addresses. If they have an address we don’t, we will have it within 30 days after our monthly update is run.

Does Address Validation do delivery point validation?  I need to know if the USPS can deliver to this address.

Yes, we do. We recommend using our “ValidateAddressWithDPV” operation, but our “ValidateAddressWithSuiteLink” and “ValidateAddressWithRDI” operations also include DPV information.

Is Address Validation CASS-certified?  Can I use it to get postal discounts?

Yes and No, our core address validation engine is CASS certified.  It meets and exceeds all requirements for address correction expect bulk mail discounts. AV does not print the UPSP forms required for bulk mail discounts, because of this we are not formally CASS certified.  You cannot us AV for bulk-rate postal discounts.

What are the possible errors that AV will return if an address is invalid?

Please refer to “Error Codes”, above.

What does “Multiple Addresses Match” mean?  How do I get a single result?

“Multiple Addresses Match” means that AV found the address, but couldn’t resolve it from other addresses that were very similar, typically because of directional elements.

For example, if you validate “123 Main street, Anytown, CA”, but in Anytown, CA, there is only a “West Main street” and an “East Main street”, then this will result in a “Multiple Addresses Match”.  You will need to specify either West Main or East Main as the street name to get a corrected, single address.

There are other cases in which “multiple addresses match” will occur, but are rare and often have to do with a difference in zip+4, or suite numbers.

In this case you can try calling our GetPossibleMatches operation to see the results, but if none of the results are DPV valid, GetPossibleMatches won’t return any results.

I need to know exactly how long each of the output fields could be.  What is your standard field length?

Please email us at support@serviceobjects.com, and we’ll send you the exact field length specifications.  As a general rule, you won’t get a field longer than 80 characters.

Does AV validate suite or apartment numbers?

If you use any of our DPV-enabled operations (ValidateAddressWithDPV, ValidateAddressWithRDI, ValidateAddressWithSuiteLink) then yes.

Does AV validate PO Boxes/box numbers?

Yes.  PO boxes are correctable and are indeed validated.  Out of range PO Box numbers will yield the appropriate error

I need both address correction and geocoding information. How can I get both at once?

We offer alternative services to provide this information.  Please see “DOTS Address Validation Plus US” at this URL:
https://www.serviceobjects.com/products/address/address-validation-plus-us

Additionally, if we run batches for you (see question below) we can provide both address correction and geocoding simultaneously.

If you have a need for special information or format, email us at support@serviceobjects.com

Where do you get your address information?

We gather our data from many various sources.  The short answer is the US Postal Service.

How often do you update your address data?

We’ll update our information monthly, but in some special situations, we may update it more frequently.

I am not a programmer.  How do I use DOTS Address Validation US?

ServiceObjects runs batches for you!  A free batch trial is available at https://www.serviceobjects.com/upload-center/.

Conclusion

ServiceObjects is proud to offer you a free trial of DOTS Address Geocode – CA.

Sign up today for a free trial at:
https://www.serviceobjects.com/products/address/address-validation-us

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS Address Validation 2 – US, please contact sales@serviceobjects.com 

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com