How do I verify freeform (single-line) addresses in a list?



Last Updated: April 3, 2013

I allow my users to enter their address all on one single line, or sometimes in multiple lines but not separated into address, city, state, zip fields. I need to be able to parse the address data and then perform address validation. How can I do that with LiveAddress for Lists?


First, the bad news...

Our list service does not parse single-line/freeform addresses because it must conform to rigorous CASS™ specifications set by the USPS. Because parsing such addresses introduces too much ambiguity into our CASS™ engine, we are unable to provide this feature with LiveAddress for Lists.

The list service always returns, at most, one response per input address whereas the LiveAddress API will return as many possible matches as it can. With the API you, the end user, have the option to choose how you want to handle an ambiguous address. With the list service, if we have to guess for you we would default to the official response of "no match" rather than submit an address the might be wrong (false positive).

... now the good news!

LiveAddress API does parse street addresses into components. Be aware that doing so may produce unexpected (but still valid) results. It's fine when you're verifying addresses one-at-a-time at point-of-entry, but here's our recommended procedure for doing this en masse:

  1. Extract the list of addresses from your database or spreadsheet, one per line.
  2. Write a little script or program to read those addresses and append them to an API query. (You can do up to 100 addresses per query.)
  3. Submit your requests to the API (you'll have to purchase an API subscription) and store the results, which will include the address components.
  4. Re-incorporate those results back into your list, split into components. If practical, we suggest you review the accuracy of the results. The data will always be valid, but may not be what you expect. We cannot guarantee CASS™ accuracy as if they were originally split into components.
  5. For the CASS™ Summary Report Form (to do a bulk mailing), run that newly-augmented file through LiveAddress for Lists. Now that the addresses are split into components, LiveAddress for Lists can handle your file, and the results from that list will be returned to you, CASS-Certified™ and ready-to-go.

We have sample code which can help you perform bulk requests to the API to complete step 3. Also, if you get stuck on step 2 (reading the addresses in your list) -- you might try selecting the column in Excel, for example, and pasting the rows into a text file so that you have one address per line. Then simply have your program read lines of the text file. Usually this can be done in less than 30 lines of code.

You may contact us if you encounter difficulties using our products according to the documentation herein and we'll be happy to help!