The USPS API and address validation
The USPS API isn't a single API, but rather, it's 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
For the purposes of this article, we’re going to hone in on the USPS address validation API and how Smarty® enhances USPS’s address records 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 |
|---|---|---|
In this article, we'll cover:
- The USPS address database
- USPS address validation APIs
- Is the USPS address verification API free? Are there limitations?
- USPS address validation API & Smarty
- USPS address validation API examples and tutorials
The USPS address database
The United States Postal Service maintains an official address database of 163 million standardized addresses in the United States. It’s updated monthly. They have come to be known as the setters of industry standards for addresses in the US. Their database contains business, residential, and post office box delivery points. Metadata points, such as county, delivery point code, and vacancy status, are available on each.
Sure, the USPS address database is a thing of beauty, but the Postal Service doesn’t hand their data out to just anyone who asks. However, they do give everyone access to check domestic addresses against their data through the official USPS address APIs and web forms. The USPS data is also accessible through third-party providers willing to jump through all the hoops and abide by their strict agreements to become CASS Certified vendors. Did we mention that we’re really good hoop jumpers?
Being a CASS Certified vendor permits Smarty 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, a boatload of cash, or violating the USPS Terms and Conditions.
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 and the option to add 20 million verified non-USPS 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’ll tell you if the matched address is a USPS address or a non-USPS address.
The USPS address validation API
USPS’s address validation tool is limited to 5 address lookups per request. It verifies that addresses are real and mailable and returns addresses in the USPS standardized format. The USPS address verification API doesn't just make sure an address is valid; it is also an address standardization API that changes an address to match the accepted USPS standardized 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 a street address that looks like this:
If the postal service finds an exact match in their database, they’ll return a response that the address is valid and considered a valid address. And just like that, your address is verified. Ka-ching!
If the address you provided doesn't quite match a standard 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 what USPS decided is an accurate address:
To match the USPS address records, “ST” has been added, Suite changed to STE, the ZIP Code has been corrected, and finally, the +4 Code has been added to make a more valid 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 tools include some form of standardization. At least, any worth their salt should.
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 are also returned:
There are even a few additional points provided in the output that can be used creatively.
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 limitations of the USPS address validation API fall under Terms of Service, completeness, uptime, documentation.
USPS address validation API price & limitations
We love the USPS, so discussing its API limitations is as awkward for us as the classic handshake-hug-high-five mix-up.
Despite the awkwardness... If you’re planning to use the postal service's APIs, you need to know where you might run into problems.
Is the USPS address verification 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 should 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. If you're working with a large volume of addresses, there's a tremendous opportunity to unlock revenue and drive ROI in your business operations. You might want to check out our ebook to learn more:
Or, you can continue to learn about the limitations of the USPS address verification API with documentation and support.
USPS address validation API documentation &support
Do you:
- Want oodles and oodles of delicious, tried-and-true example code provided by the same 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 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?
- Want access to international address verification capabilities?
- 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 address verification API features 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.
As if that weren’t enough, 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 address validation API is fully XML. So, to prepare for your XML adventure, 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.
This is just stop number one on the bus line, Limitation Station. Let's talk about USPS’s address validation API uptime.
USPS address validation 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’s address verification API is free to use, but it comes at a price: reliability.
Besides being notorious for poor documentation and weak support, the USPS’s address validation API is well-known among developers for having chronic downtime issues.
You made it to stop number 2 at Limitation Station. 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 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, even if you pay extra for Priority Mail or Priority Mail Express. 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 address validation API lacks reliability, its documentation falls flat, and its Terms of Service are restrictive. So, what's the solution for getting every single deliverable address?
Enter Smarty, the aggregate-level player.
USPS address verification API & Smarty
When it comes to software for USPS address validation, the postal service focuses on organizing address data, NOT on sharing it. Therefore, external parties and companies create the best address validation services and software, allowing you to use the USPS database information more effectively and less restrictively than the USPS. Smarty combines the data from the USPS with supplemental information they feel would be helpful to you and your organization, making this augmented data available through APIs.
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 alone
The proud men and women in blue shorts are the authority on 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 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 individually and gives you a quick thumbs-up/thumbs-down for validation.
The USPS solutions (their Web Interface and API) would be well suited for anyone with an address validation job that's not system-critical, time-sensitive, or 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 do this 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 how Smarty makes the USPS's blood, sweat, and tears more accessible and user-friendly.
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 online APIs and Command-Line Interface (CLI) can process hundreds of thousands of addresses in minutes (single-digit minutes) instead of the days of turnaround some companies take to get your data back to you. Our enterprise customers routinely run 10,000 addresses per second!
At speeds like that, your validation is nearly instantaneous. 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.
Smarty's 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 (not at you. We don't do scripts here).
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, and 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 the other guys'. Most of all, though, we put a lot of effort into getting you off the ground quickly and keeping you running reliably.
Smarty is loyally 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 address validation API didn't deter you. You aren't worried about the restrictive Terms of Service or MIA support either. The abundant available alternatives didn't persuade you. You still plan to use the USPS address validation API?
Great! At least you're 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. Again, fair warning, all of 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's a video tutorial 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 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 faster, easier address validation APIs written in Go and responding 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, and 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 company has the best address verification software? I think we have made our biases pretty clear by now. Smarty provides the best address verification service around. But really, as with many things in life, there's no one-size-fits-all answer here.
The best thing to do is visit any provider's pricing page or check if they have one of those sweeeeeeet free trials. In fact feel free to check out our pricing page, or check out our free trial here.