The USPS API and address validation

The USPS API isn't a single API, but a suite of dozens. The USPS APIs include:

Address APIs - Address Validation API, ZIP Code Lookup API, City/State Lookup API
Hold for Pickup Facilities Lookup API
Package Pickup APIs
Post Office Locations API
Price Calculator APIs
Shipping Label APIs
Service Standards & Commitments APIs
Tracking & Delivery Information APIs

Among the most important, is their address validation API. An Address Validation API (or verification API) is an application programming interface (API) that verifies postal information. US address validation APIs normalize addresses to match the USPS's standard address format. These APIs efficiently integrate with websites, databases, CRMs, and other software to enhance address data quality.

Smarty™ enhances USPS data to provide ridiculously fast address validation, address data enrichment, standardization, and autocomplete with a collection of flexible address APIs. Try one here:

US Address Validation API	US Address Autocomplete API	US ZIP Code API
Try It Now	Try It Now	Try It Now

Each of the USPS address lookup APIs is limited to 5 lookups per request and performs specific functions such as address validation, address normalization, ZIP+4 appending, and more. Here's what each of the USPS address APIs can do:

USPS Address Validation/Standardization API - Verifies that addresses are real, mailable, and returns them in the USPS standardized format.
USPS ZIP Code Lookup API - Tells you the ZIP+4 Code for addresses you submit.
USPS City/State Lookup API - Provides the city and state for a particular ZIP Code.

In this article, we'll cover:

The USPS address database
USPS address validation APIs
Is the USPS API free? Are there limitations?
USPS API & alternatives
USPS API examples and tutorials

USPS address database

The United States Postal Service maintains a database of 160 million mailing addresses in the United States that is updated monthly. The database contains business, residential, and post office box delivery points. A few metadata points such as; county, delivery point code, and vacancy status are available on each delivery point.

Sure, the USPS address database is a thing of beauty, but the Postal Service won't hand their data out to just anyone who asks. But, they do give access for anyone to check an address against their data through the official USPS address APIs and web forms. The USPS database data is also accessible through third party providers that are willing to jump through all the hoops and abide by their strict agreements in order to become CASS Certified vendors.

These vendors (like Smarty) are permitted to use and enhance the USPS address data intelligence for broader use cases that wouldn't be allowed through the USPS APIs directly.

So, can you access information in the USPS address database? You betcha. Can you download the entire thing from the USPS? Not without a truckload of effort, boatload of cash, or violating the USPS TOS.

Even though USPS doesn't allow you to download their database, Smarty will allow you to download our comprehensive US address database through our US Master Address List product. 160 million USPS addresses is a good start, but Smarty's US Master Address List features 200+ million valid US addresses. Not all are deliverable via USPS but that doesn't make them any less real. When you validate against Smarty's address database, we will tell you if the matched address is a USPS address or a non-USPS address.

The USPS address validation API

The USPS address verification API doesn't just make sure an address is valid. The API is also an address standardization API that changes an address to match the accepted USPS address format.

The first step in using the USPS address validation API begins with comparison. The US postal service compares the provided address against their address database to identify possible matches.

Maybe you enter an address that looks like this:

USPS address validation example of entered address

If the postal service finds an exact match in their database, they will return a response that the address is valid and properly formatted. And just like that, your address is validated. Ka-ching!

If the address you provided doesn't quite match an existing address in the database, the next step in the USPS address verification process is to attempt to correct it in a process called address standardization. Errors in casing, abbreviation, spelling or other typographical errors are corrected and the address is standardized to the official USPS address format.

Now, the address is updated to look like this:

USPS API example - output of validated address

To match the USPS database, “ST” has been added, Suite changed to STE, the ZIP Code has been corrected, and finally, the +4 Code has been added to the ZIP Code.

Having an API that validates the address is the easy part. It is just a simple matching game. Address standardization is more complicated. An API that can identify a Jabba the Hut caliber address and match it with the Princess Leia version is worth its weight in Galactic credits. A flexible and forgiving address standardization API plays a pivotal role in address data quality. Most address validation APIs include some form of standardization. This is why the USPS address verification API is commonly referred to as the USPS address standardization API.

Once the API has standardized and validated the address, the address is also enriched with additional metadata in the response. Data such as carrier route, ZIP+4 Codes and DPV confirmation indicator as seen here:

There are even a few additional points provided in the output that can be used in creative ways.

Before you grab these APIs and start coding up a storm, you may want to become familiar with the possible limitations of consuming the USPS address standardization APIs. The most common USPS API limitations fall under the categories of Terms of Service, completeness, uptime, documentation.

USPS API price & limitations

We love the USPS. So, discussing the limitations of their API is as awkward for us as the classic, handshake-hug-high-five mix-up.

But, despite the awkwardness... If you are going to use the postal service's APIs, you need to know where you might run into problems.

Is the USPS API free? What are the terms of service?

Yes, all the USPS postal address APIs are completely free to use after account registration. The APIs are to be used exclusively for shipping and mailing services as written in the USPS terms of service. In other words, you can't use them for bulk address validation, database cleansing or record management.

Regarding terms of use, the USPS web tools user guide states:

The Address Validation APIs can be used in conjunction with USPS SHIPPING OR MAILING SERVICES ONLY. The Address API must only be used on an individual transactional basis, i.e. not batch processing or cleansing of a database, but as a customer enters the information into a form on a website.
Failure to comply with these terms and conditions can result in termination of USPS API access without prior notice.”

If you need to standardize a database of addresses, merge address data or check more than a few addresses at a time, you need to look elsewhere for a solution and if you're working with a large volume of addresses, there's a tremendous opportunity to unlock revenue and drive ROI in your organization. You might want to check out our ebook to learn more:

Or, continue to learn about the limitations of the USPS API with documentation and support.

USPS API documentation & support

Do you:

Want oodles and oodles of delicious, tried and true example code provided by the very developers who created the USPS address APIs?
Want to be up and running with your program in hours instead of days because all you had to do was to copy and paste some code and tweak a few lines?
Want access to stellar official SDKs in Python, JavaScript, C#, iOS and more? Do you look like Tony Stark when you show your integration to your boss?
Want legendary phone, email and chat support?
Hate XML?

If you answered “yes” to any of these questions, then we are sorry to disappoint you. The USPS cannot give you what you want.

The USPS APIs feature little to no example code. Their documentation is considered weak by nearly all who use them. SDKs for their postal address APIs aren't provided at all, so you'll have to code it one line at a time. The USPS really doesn't offer any shortcuts here.

Chat support isn't available for the USPS address APIs. When it comes to phone support, we can tell you that the experience is even more painful than testing in production. After listening to the same two and a half minute song 43 times (107 Minutes), we couldn't take it anymore and ended the call.

Finally, the USPS APIs are all XML all-the-time. So, you'll need to hop in your time machine and go to the world of Windows 98, Furby, and an average internet speed of 30 KBPS to prepare for your XML adventure.

Now, lets talk about the USPS API uptime.

USPS API uptime status

Why would we bring up the USPS address lookup API status? Because even though the US Postal service database is the official repository of address info for the United States, their API is well-known for its lack of consistent uptime.

Sure, the USPS APIs are free to use, but they come at a price: reliability.

Besides being notorious for poor documentation and weak support, the USPS APIs are well known among developers for having chronic downtime issues.

If the uptime doesn't get you, maybe their incomplete data will.

Non-USPS addresses: Address data completeness

The USPS database supports the US mail delivery system. It may surprise you that the USPS database does NOT include every deliverable address in the United States. It maintains records on approximately 160 million homes and businesses but excludes millions of addresses that are not part of its delivery network.

If an address is in a rural area, or the weather conditions are too harsh to send a mail carrier, the USPS simply won't deliver to that address. Likewise, newly developed areas often are not included in their database for some time. We refer to these locations as non-postal or non-USPS addresses.

Luckily for these locations, private companies like FedEx, UPS, DHL, and Amazon happily deliver to these areas. If you want to validate all real addresses, regardless of where they're located, you'll need to find a more reliable solution than the USPS database.

In addition to not including every address, the USPS API system lacks reliability, its documentation falls flat, and its Terms of Service are restrictive. So, what's the solution for getting every single deliverable address?

Fortunately, there are several address validation services available in addition to the USPS that can provide the addresses you need.

USPS address verification API & alternatives

When it comes to software for USPS address validation, the postal service focuses on organizing address data, NOT on sharing it. Therefore, third-party companies create the best address validation services and software, allowing you to use the USPS database info in a more effective and less restrictive way than the USPS. Many of these companies take the data from the USPS and combine it with supplemental information they feel would be helpful to their customers. Most of these providers make this augmented data available through APIs.

What each provider's API does or doesn't do, varies, as does its ease of use, uptime, tech support, and so on. Each provider has something to bring to the table, and we've highlighted a few of the most popular ones in this article, discussing the pros and cons of each.

The short version is this: the USPS has the most up-to-date data, Melissa provides the most supplemental information, Loqate has widely used international data, and Smarty is the fastest and easiest to use address validation software with the most thorough international data.

Note: Since this article deals with APIs (which are used to validate addresses then give them back to you), it may be helpful to brush up on terms like "uptime" and "documentation."

USPS

The proud men and women in blue shorts are the authority when it comes to shipping in the United States. Their data is always up-to-date because it comes to them first. They keep track of virtually every mailable address in the country—and with 160,000,000 delivery points in the US, that's no small feat. They handle the deliveries, and they keep track of where everything is going.

In short, they do all the hard work.

The USPS has recognized that the information they've aggregated is worth something to the rest of the nation, and they've made it available in a number of ways. For starters, they have a Web Interface that can validate an address for you, free of charge, right on their website. It's a simple little gizmo that lets you enter addresses one-at-a-time, and gives you a quick thumbs-up/thumbs-down for validation. They also have an API that provides address validation services.

The USPS solutions (their Web Interface and their API) would be well suited for anyone with an address validation job that's not system critical, not time sensitive, not high volume, and will result in packages being sent via the USPS (as per their API's license agreement). In other words, if your needs are standard and simple, you can have this done for free.

But if you're reading this article, we have a feeling that your address validation needs are a little more extensive. Maybe you need something easier to use, or something more reliable for your mission-critical applications. Keep reading, and we'll tell you about some companies that make the USPS's blood, sweat, and tears easier to access.

Melissa

Melissa isn't a person, it is a company that serves a clientele largely composed of big businesses. Because they're a larger organization serving larger companies, they offer a breadth of supplemental information. They go well beyond USPS's "Yes or No" model, offering things like email and name validation, demographics, and even census and weather information on addresses that are processed. Essentially, you hand them what you want validated, and they hand you back an encyclopedia entitled, "Everything you wanted to know about this address, but were afraid to ask."

Their API is fairly straightforward and easy to use, and their uptime is pretty darn great. They have a tech support team to help answer your questions, and their documentation is easier to understand than what the USPS offers.

If you're looking for real in-depth, gotta-know-everything kind of information, Melissa is a solid choice.

Loqate

Loqate's primary selling point is its accuracy—both in domestic and international service. For them, the USPS is only one of many data providers. Their API offers access to insanely accurate addresses and geocodes for 250 countries and territories.

Loqate is a good solution for someone who is highly skilled at reading technical documentation and can work well independent of hand-holding from customer service.

Their claim to fame, in a nutshell, is the aforementioned data accuracy. In fact, they're often used as a database by other validators much in the same way as the USPS, just for foreign addresses.

Smarty

At Smarty, we believe that things should be fast and simple. Kind of like teleportation in sci-fi movies: push a button and—poof!—you're where you want to go. We don't have Scotty to beam us up. But we do have the fastest turnaround times in the address validation industry.

Smarty's address standardization API ensures your addresses are formatted correctly according to postal standards, enhancing data accuracy and integrity.

Our online APIs and our Command-Line Interface can process hundreds of thousands of addresses in minutes (single-digit minutes) instead of the days of turnaround that some companies take to get your data back to you. At speeds like that, your validation is nearly instantaneous, and with one-at-a-time address lookups, it's so close to instantaneous you might think you're using an infinite improbability drive.

Our APIs are also among the easiest to use. That's our specialty: we take complicated things and make them simple. You can have our APIs plugged into your own programs in a matter of minutes (single digits again). Operating the APIs is streamlined and intuitive. Our uptime is also one of the best (there's lots of 9's in the percentage). And in case your redshirts encounter any problems, we have extensive documentation for self-help. There's also a direct phone line to our tech support crew, where real-live human beings are happy to speak with you.

With Smarty, the USPS database is just the beginning of our address data. From there, we add millions of additional valid addresses that the USPS doesn't have. This includes addresses delivered to by FedEX, UPS, DHL and Amazon. By using Smarty, you get access to one of the most complete address datasets publicly available.

Plus, we do more with additional address data enrichment. We provide over 55 data points for addresses such as time zone, latitude, longitude, congressional district, ZIP Code type, county FIPS Code can be appended to your database of addresses. The additional insights gained can be used in hundreds of ways to benefit your organization and your users.

We also offer address validation for international addresses, and our prices are easier to stomach than many other companies. Most of all, though, we put a lot of effort into getting you off the ground quickly and keeping you running reliably.

Smarty is despicably reliable at stomach-turning speeds, and we can still make the Kessel Run in under 12 parsecs.

If you can't tell, Smarty is passionate about address validation. We're passionate because clean address data is the key to unlocking latent revenue and boosting ROI within organizations. Our ebook shows how top-tier address validation can benefit every part of your organization. Check it out to see how:

Resources, examples and tutorials

Okay, the poor uptime and lackluster documentation of the USPS APIs didn't deter you. You aren't worried about the restrictive Terms of Service or Missing-In-Action support either. The abundant available alternatives didn't persuade you. You still plan to use the USPS API? Great! At least you are going into this with both eyes open. Here are some resources to help you get started:

USPS web tools resources:

Tutorials & examples:

All the APIs offered by the USPS function similarly. We created some quick tutorials to show you how to use the USPS APIs in C#, Python and PHP just to get you started. As a fair warning, all the USPS APIs are XML based. These are not our words, but they describe our feelings about XML succinctly.

"Some languages can be read by humans, but not by machines, while others can be read by machines but not by humans. XML solves this problem by being readable to neither."-Unknown

Here we have video tutorials playlist on using the USPS APIs in C#, Python and PHP to get you started.

Click the playlist icon in the corner of the video to see the rest of the tutorials in the USPS API series.

If you don't want to use the http equivalent of faxing, we get it. We don't love XML either. If you prefer a faster, easier, address validation APIs, that were written in Go and respond in JSON, Smarty Address Validation APIs have you covered.

Plus, you get a ton of Software Development Kits (SDKs) including .NET, Go, Python, JavaScript, iOS, Java, PHP, Ruby, Rust with example code snippets that go on for days. Here are some snippets for our Python SDK on GitHub. And there's more where that comes from. Lots more.

Each Smarty API:

is fully documented
has live support
is famously easy to integrate.
has 100% uptime
features generous Terms of Service

The best address verification software?

So which of these companies has the best address verification software? I think we have made our biases pretty clear by now. But really, as with many things in life, there's no one-size-fits-all answer here.

This article has included a brief sampling of some of the more prominent address cleansing service providers. There are other, more obscure providers, and if none of us on this list fit your needs, hopefully you can still use our information and examples to hunt down one that does. Each business is going to have areas where they've sacrificed a little to be the best in their particular area of focus.

The best thing to do is visit each provider's free trial pages and try out their APIs for yourself.

And, if you're still not sold on the benefits of address validation, you should check out our ebook here: