How can I parse and verify freeform addresses?

Question

I receive addresses in a single-line, or freeform, format; they're not split into pieces like most forms where street line 1, city, state, and ZIP Code are entered separately. I need to parse the address into components and then verify the data. How can I componentize the address?

Answer

Recent upgrades to LiveAddress API bring freeform address processing to the table. To parse and verify a freeform address, submit the entire address into the street field. You may also submit the first line and last line of the address in the street and lastline input fields.

LiveAddress API will only return valid and official data as usual, and the results will look exactly like the results of any other regular query to the API. You will probably be most interested in the components field which has the address split into granular pieces: primary number, street name, street suffix, unit designator, secondary number, and more.

There are a few edge cases we have yet to look at, and we urge you to consider the following (these things are actually very important to know):

• Addresses submitted in a single line are unpredictable, so our API will have to be more aggressive in the results it returns (which may not always be what you expect).
• Because of the inherit ambiguity of freeform addresses, we cannot guarantee CASS™-quality results all of the time. There are some address where it's impossible for even a human, just by looking at it, to split an address into its first and last line components. (For example: 123 Main St Charles Iowa. Is "St. Charles" the city name? There is also a Charles City, IA which may be typed without "City." As you can see, it's complicated...)
• Currently, line breaks are not valid delimiters in freeform addresses. We recommend you convert line breaks into spaces before submitting the address (although that may introduce even more edge cases).
• Addresses that contain too much information may confuse our parser. Results will still be valid and deliverable, but occasionally a mail carrier might see a glitch and raise an eyebrow when delivering that item (ie. no harm done).
• Single-line addresses that are malformed or incomplete will be less likely to return results than the same address submitted in the traditional format because of the risks in parsing a freeform address that is hardly legible.
• It is expected that the street (or address line 1) comes first, and the city/state or ZIP Code appear last, even in a "freeform" address. Again, addresses that are obscure, malformed, very incomplete, etc, may not be verifiable.
• It is expected that users will be on the receiving end of the API call to confirm or refute the results of a single-line address verification request. In other words, the user should ideally be involved in confirming the validity of the result (especially moreso than for addresses submitted in components).