The Address Validation API accepts an address, identifies its components and validates them, standardizes the address for mailing, and returns the best known latitude/longitude coordinates for it. For US and Puerto Rico addresses, you can optionally enable USPS CASS processing.
Address Validation API: key facts
- Product: Address Validation API
- Category: Places
- Platform: Web service (REST)
- Runs on: Server (backend code)
- Launch stage: GA
- Lifecycle: Active
- Overview: Address Validation API overview
- Regional availability: Limited. Supported countries and data quality vary by country, and some countries are in Preview. Residential and commercial metadata is returned only for countries flagged on the coverage page. USPS CASS is supported only for US and PR. (coverage details)
Address Validation API: when to use it
Use Address Validation API when:
- You need to check whether an address refers to a real place and find which components are missing or possibly wrong.
- You need to standardize and complete an address for mailing, for example during a checkout flow.
- You need USPS CASS-certified validation and
uspsDatafor addresses in the US or Puerto Rico. - You need residential or commercial address metadata for a country listed on the coverage page.
Don't use Address Validation API when:
- You only need to convert an address to latitude/longitude and don't need to validate individual address components. Use Geocoding API instead.
- You need hyper-local destination details such as building entrances, building outlines, or navigation points. Use Geocoding API instead.
Address Validation API: setup
- Service to enable:
addressvalidation.googleapis.com - Authentication: API key, OAuth 2.0, Service account
- Get started: Set up Address Validation API
- Reference: Address Validation API reference
- Pricing: Address Validation API usage and billing
- Policies: Address Validation API policies
- Release notes: Address Validation API release notes
Official Address Validation API packages:
- npm:
@googlemaps/addressvalidation - pypi:
google-maps-addressvalidation - go:
cloud.google.com/go/maps
Address Validation API: common mistakes
- Problem: The
addressCompleteproperty is omitted from the verdict when its value isfalse, so code that expects the field to be present can misread incomplete addresses. Fix: Treat a missingaddressCompleteproperty asfalse, or check for the presence of the property. See /maps/documentation/address-validation/understand-response. - Problem: If
regionCodeis omitted, the API infers the region from the address, which can give weaker results. Fix: IncluderegionCodein thePostalAddresswhen you know it. See /maps/documentation/address-validation/requests-validate-address. - Problem: The
uspsDataobject isn't guaranteed to be fully populated for every validated US address. Fix: Don't rely onuspsDataas the only validation signal; also use the verdict and address components. See /maps/documentation/address-validation/handle-us-address. - Problem: Feedback sent with
provideValidationFeedbackmust reference theresponseIdfrom the firstvalidateAddresscall in the sequence, not a later one. Fix: Store theresponseIdfrom the firstvalidateAddressresponse and send it in the feedback request. See /maps/documentation/address-validation/handle-updated-address.
What you can do with Address Validation API
See the guides linked below for each task, or compare across products in the Capabilities Explorer.
- Return a validated address for a specified address or partial address.
- Return the latitude/longitude coordinates for a validated address.
- Return the Google place identifier for a validated address.
- Use United States Postal Service (USPS) Coding Accuracy Support System (CASS) certification for address validation.
- Return information about whether a validated address is a business, residence, or PO box.
- Return United States Postal Service (USPS) delivery metadata for a validated address.
- Return an English-language version of a validated address. Preview
- Return the Plus Code for a validated address.