address_verify
Verify Address
Verifies an address against the USPS Coding Accuracy Support System (CASS) and returns it standardized and corrected.
Submit the whole address in query, or the first address line in query with either zip_code, or city and state. A freeform query is parsed into those components before the search runs.
A match returns the standardized address lines, city, state and ZIP+4, scored by fit and confidence. It also carries the CASS record behind the match: delivery point, DPV flags, carrier route, eLOT, county, congressional district, RDI, time zone and coordinates. No match returns 200 with a count of 0, a null match and empty address fields.
Only a match draws on your balance. A key without address verification enabled returns 401. A verification still running after 9.5 seconds aborts with 429.
Countries
Verify defaults to the United States, where it is CASS certified. Pass context with an ISO 3166-1 alpha-3 country code to verify an address elsewhere, e.g. context=GBR or context=FRA. The address datasets your key is licensed for decide which countries it can verify.
Outside the United States there is no CASS record to return, so match carries the standardized address from that country's dataset instead. The top-level fields (address_line_one, city, state, zip_code, country_iso_2) are populated for every country, along with confidence and fit.
Endpoint
POST /verify/addresses
See the API reference for this endpoint.
Import
from addresszen import AddressZen
Call address_verify on the AddressZen client. Path parameters are positional; query and body parameters are keyword-only.
Path Parameters
None.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tags | str | no | Tags A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". |
context | str | no | Identify the country of the address to verify. Defaults to United States (USA) |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
query | str | yes | Address input to verify. If submitting a freeform address verification query, enter the full address. E.g. query=123 Main St, Springfield, CO, 81073 Otherwise, query can be accompanied with the following address components: - zip_code - city and state If you supply zip_code, or city and state, omit that information from query and use it for the first address line only. E.g. query=123 Main St |
zip_code | str | no | Specify the ZIP code of an address. The following formats are accepted: 81073-1119, 810731119, 81073. |
city | str | no | City of an address. |
state | str | no | State of an address. For the US, use the 2 letter state abbreviation. |
Response Type
from addresszen.types import AddressVerifyResult
Errors
Unsuccessful HTTP responses raise APIError or a subclass, with the HTTP status and the API error code and message. Connection failures and timeouts raise TransportError. Unexpected responses raise ProtocolError. All derive from ClientError. See error handling.
Example
from addresszen import AddressZen
with AddressZen("ak_test") as client:
result = client.address_verify(query="123 Main St, Springfield, CO 81073")