Get a Demo

API directory · Google Maps Platform

Address Validation API: catch bad addresses before they become failed deliveries

The Address Validation API verifies, standardizes and geocodes an address in a single call and returns a per-component verdict so your product knows exactly which part of the address is missing or unrecognized. For India delivery and e-commerce teams, catching a bad address at checkout is significantly cheaper than a return-to-origin on the ground.

Get a demo →

What the API does

Per-component verdict, standardization and geocoding in one call

The Address Validation API accepts an address string and returns three things in a single response: a standardized form of the address, a latitude/longitude geocode and a per-component verdict. The verdict covers each address component (street number, route, locality, postal code, subpremise and more) and classifies it as confirmed, unconfirmed, suspicious or missing.

This means a product can show the user exactly which part of their address is problematic before the order is placed, not after the delivery fails. A US and Puerto Rico USPS CASS option is available for US-addressed workflows.

Google Maps Platform · Address Validation API
POST v1:validateAddress · a Pune flat with no house number and a landmark
host addressvalidation.googleapis.com · auth X-Goog-Api-Key · enableUspsCass is US and Puerto Rico only
200 OK
possibleNextAction FIX

Request headers and JSON body

POST https://addressvalidation.googleapis.com/v1:validateAddress
Content-Type: application/json
X-Goog-Api-Key: <your key>

{
  "address": {
    "regionCode": "IN",
    "locality": "Pune",
    "addressLines": [
      "Flat 402, Sai Residency, Baner Rd",
      "nr Balewadi Phata"
    ]
  }
}
Read the verdict before the address. possibleNextAction is the branch your checkout takes, and addressComplete is absent here, which means false: the API omits a boolean when it is false rather than sending it. The reason is one line further down in missingComponentTypes. This is what lets a form say which field is wrong instead of rejecting the whole address.

Response application/json

{
  "result": {
    "verdict": {
      "inputGranularity": "SUB_PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "hasUnconfirmedComponents": true,
      "hasInferredComponents": true,
      "possibleNextAction": "FIX"
    },
    "address": {
      "formattedAddress": "Flat 402, Sai Residency, Baner Road, Baner, Pune, Maharashtra 411045, India",
      "addressComponents": [
        { "componentName": { "text": "402" },
          "componentType": "subpremise",
          "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE" },
        { "componentName": { "text": "Sai Residency" },
          "componentType": "premise",
          "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE" },
        { "componentName": { "text": "Baner Road" },
          "componentType": "route", "confirmationLevel": "CONFIRMED" },
        { "componentName": { "text": "Baner" },
          "componentType": "sublocality_level_1", "confirmationLevel": "CONFIRMED" },
        { "componentName": { "text": "Pune" },
          "componentType": "locality", "confirmationLevel": "CONFIRMED" },
        { "componentName": { "text": "Maharashtra" },
          "componentType": "administrative_area_level_1", "confirmationLevel": "CONFIRMED" },
        { "componentName": { "text": "411045" },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED", "inferred": true },
        { "componentName": { "text": "India" },
          "componentType": "country", "confirmationLevel": "CONFIRMED" }
      ],
      "missingComponentTypes": ["street_number"],
      "unconfirmedComponentTypes": ["subpremise", "premise"],
      "unresolvedTokens": ["nr Balewadi Phata"]
    },
    "geocode": {
      "location": { "latitude": 18.55912, "longitude": 73.78684 },
      "placeId": "ChIJXXXXXXXXXXXXXXXXXXXXXXX",
      "placeTypes": ["premise"]
    },
    "metadata": { "residential": true }
  },
  "responseId": "9f2c1b7a-4e10-4d63-9a1e-2b6f0c7d5e84"
}
hasUnconfirmedComponentstrue, and exactly 2 components sit at UNCONFIRMED_BUT_PLAUSIBLE: the 2 in unconfirmedComponentTypeshasInferredComponentstrue, and exactly 1 component carries inferred: the pincode the input never gaveformattedAddresscarries all 8 components; the landmark is the one input token it drops, into unresolvedTokens
Fig. · One validateAddress call, trimmed for the page. The endpoint, the request fields, every response field and the verdict, granularity and confirmation-level values are the documented Address Validation API surface. The address, Place ID, coordinates and response ID are illustrative and describe no real address, order or customer.

Use cases

Where the Address Validation API prevents downstream failure

  1. 01

    E-commerce · Validate at checkout before the order leaves the warehouse

    An unconfirmed pin code or a missing subpremise flagged at checkout can be corrected by the customer in real time. The same correction at the point of delivery requires a rider phone call, a failed attempt and a potential return-to-origin.

  2. 02

    Last mile · Gate dispatch on address confidence score

    Dispatch systems use the Address Validation response to score addresses before assigning them to a rider, routing low-confidence addresses through a manual review queue rather than dispatching them to fail.

  3. 03

    Fintech · KYC address verification

    BFSI and lending platforms use Address Validation to verify that a customer-submitted address matches a recognized, geocodable location, as part of the KYC data quality layer.

  4. 04

    Data · Address database hygiene at scale

    Teams with large historical address records use the API to run a quality pass, flagging and correcting problematic components before the records are used for routing or analytics.

Where Lepton comes in

Checkout integration, confidence thresholding and the India addressing stack

Address Validation is most effective when combined with the rest of the India addressing surface: Autocomplete at entry, Descriptors for last-mile landmark resolution and Geocoding for batch historical records. We design the stack and integrate each API at the right point in the flow.

  1. 01

    Integration · Checkout and dispatch flow wiring

    We wire Address Validation into the checkout form, registration flow or dispatch API at the right point, including the confidence threshold logic that decides when to prompt the user versus auto-correct versus flag for review.

  2. 02

    Stack · The full India addressing architecture

    Address Validation catches errors at entry. Address Descriptors add landmark context for Indian pins. Geocoding resolves historical batches. We integrate all three as a coordinated layer, not three separate implementations.

  3. 03

    GCP · GCP project setup and API enablement

    Service accounts, API key configuration, billing setup and the GCP project plumbing so the Address Validation API is callable, accountable and quota-managed from day one.

Get started

Run your addresses through it.

Bring a sample of your hardest Indian delivery addresses. We will show you where Address Validation moves accuracy and how it fits into the checkout or dispatch stack.

Get a demo →