The USPS API and Address Validation
The USPS API is an address validation API provided by the United States Postal Service. The USPS address validation API provides developers of web-based applications access to the complete USPS database of postal address information for the United States.
An Address Validation API is an application programming interface (API) that verifies postal addresses to ensure they are valid. In the United States, address validation APIs may also normalize the address to match the standards of the USPS. Validation APIs are able to integrate with websites, databases, CRMs and other systems.
SmartyStreets leverages the USPS address database for ridiculously fast address validation, standardization and autocomplete with a collection of flexible address APIs. Try one of the SmartyStreets address apis here:
|Verify and Standardize Addresses in the US||See address predictions automatically as you type||Enter ZIP / city to find matching cities / ZIPs|
The United States Postal Service also offers a suite of address APIs. Here they are and what they do.
- USPS Address Validation / Standardization API - Verifies that an address you submit is real and mailable and returns it in a standardized format recognized by the USPS.
- 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.
Each of the USPS address lookup APIs perform specific functions such as address validation, address normalization, ZIP+4 appending, and more. Each API also limits you to five lookups per request at a time.
In this article, we will 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. This database contains business, residential and post office box delivery points. Dozens of metadata points such as; congressional district, county information, vacancy status, time zone 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 to check an address against their data through the official USPS address APIs and web forms. The USPS database 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 SmartyStreets) are permitted to use the USPS address database 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.
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.
Maybe you enter an address that looks like this:
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.
If the address you provided doesn’t quite match an existing address in the database, the USPS will 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:
To match the USPS database, “ST” has been added, Suite changed to STE, the ZIP Code has been corrected. 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:
And that is just the tip of the metadata iceberg. There are dozens of additional points that can be used in tons of creative and useful 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.
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. The limitations continue with documentation and support.
USPS API Documentation & Support
- 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 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.
Address Data Completeness
The USPS database exists to support the US mail delivery system. As such, the database does not contain every single address in the United States. Instead the USPS keeps records on about 160 million homes and businesses while leaving out millions of addresses to which they just don't deliver to.
In the US, private delivery companies like FedEx, UPS, DHL and Amazon make up the slack for these non-postal addresses. If you want to be able to validate addresses based on whether they are real, regardless of USPS deliverability, you will need to look for a more complete solution than the USPS.
In summary, the USPS API system lacks reliability, their documentation leaves something to be desired, they feature restrictive Terms of Service, and lack millions of valid addresses. As a developer, what can you do? Fortunately, there are a number of available address validations services a side from the USPS that can provide what you need.
USPS Address Verification API Alternatives
When it comes to address validation software, the USPS focuses on putting address data together, NOT on sharing it. Therefore, third-party companies create address validation software that allows you to use the USPS database info in a more effective and less restrictive ways 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 Data provides the most supplemental information, Loqate has the most widely used international data, and SmartyStreets 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."
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 Data serves a clientele that is 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 Data is a solid choice.
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 more than 240 countries.
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 that the USPS is, just for foreign addresses. So if you’re looking for someone who can get you GPS coordinates accurate enough to find your favorite restaurants from Amsterdam to Zimbabwe, you might consider putting your money on Loqate.
At SmartyStreets, 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.
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). We also provide a fully self-hosted, on-site, on-premises, local solution available to clients. 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 SmartyStreets, the USPS database is just the beginning of our addresses 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 us you get access to one of the most complete address datasets publicly available. Plus, we do more.
We offer validation, geocoding and data enrichment for US and 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.
SmartyStreets is despicably reliable, at stomach-turning speeds and we can still make the Kessel Run in under 12 parsecs.
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, SmartyStreets Address Validation APIs have you covered.
Each SmartyStreets 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 demo pages and try out their APIs for yourself.