Validate a US address
validate_addressValidate and standardise a US street address and return its ZIP+4. US ONLY — unlike the postal-code tools, this does not cover Canada. Send the address on one line in mailing order: number and street, then any unit (APT 4, STE 900, #9), then city, state and ZIP. It tolerates ordinary slips (a misspelling, a missing ZIP, state or directional), but it is not a puzzle to solve: a unit placed after the city or ZIP ("Pensacola FL #9") is ambiguous, a unit or a floor. Send what the user gave you, in proper order, once. If it does not match, report that; do not keep trying rewrites. Returns the address in USPS standard form split into its parts, the 5-digit ZIP and the +4 add-on, a confidence level of high, medium or low (low: the +4 may be withheld), and the county, carrier route, congressional district and census block group for the match, all for one credit. include appends more, one credit each: coordinates, the census geographies the address sits inside, its congressional and state legislative districts (now or as of any TIGER/Line year served), its school district, its time zone, and American Community Survey profiles for its census tract. The congressional district already in details is USPS's own code for the record; the cd append is the mapped district, with its number, name and the congress it belongs to. Always read notices. ZIP_CORRECTED means the match is in a different ZIP than the one supplied. SECONDARY_NEEDED means the building has multiple units and an apartment or suite number should be requested. SECONDARY_NOT_VERIFIED means a supplied unit could not be confirmed against known ranges. PARTIAL_MATCH means some details are unverified. A failed match returns success false, sometimes with no notice explaining why, so check success rather than assuming the data block is populated. Without an API key the standardised address is returned with the +4 masked.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"address": "<address>"
},
"name": "validate_address"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The address on one line. A city and state, or a ZIP Code, helps but neither is required — '1600 Pennsylvania Ave NW, Washington DC' and '1600 Pennsylvania Ave NW 20500' both resolve. Between 9 and 300 characters once spacing is normalised. | |
| api_key | No | Your ZIP-Codes.com API key, only when you cannot send it as the X-Api-Key or Authorization: Bearer header (for example a key bought with buy_credits in this conversation). Leave it out to use the free tier. It is never shown back in a response. | |
| include | No | Data to append to the match, spelled exactly as the REST API's /v2/address include flags, each costing one extra credit. 'coordinates' adds the latitude and longitude. 'census' adds the county, county subdivision, place, tract, block group and CBSA the address falls in; 'cd' adds its congressional district; 'state_leg' adds its upper and lower state legislative districts; 'school_district' adds its school district; 'timezone' adds the time zone at the matched point. census_YYYY, cd_YYYY and state_leg_YYYY add those boundaries as of a TIGER/Line year (the bare flag is the newest year, answered under `current`; other years under their own key). The 'acs_tract_*' values add an American Community Survey 5-year profile for the address's census tract: four profiles (demographic, social, economic, housing), unsuffixed for the current release or acs_tract_PROFILE_YYYY for an earlier one, in one schema, so a tract can be compared across years. At most 16 ACS profile-years per call (one profile for one year is one); split a larger request into several calls. Accepted: coordinates, census, cd, state_leg, school_district, timezone, acs_tract_demographic, acs_tract_social, acs_tract_economic, acs_tract_housing; census_YYYY, cd_YYYY, state_leg_YYYY for YYYY 2010-2026; acs_tract_demographic_YYYY, acs_tract_social_YYYY, acs_tract_economic_YYYY, acs_tract_housing_YYYY for YYYY 2011-2024. A bare flag is its newest year. |