Skip to Content
Odoo 19.0 · Google Maps · Contacts · 2 Modules

Contacts Google Address Validation

Verify every contact address is real and deliverable — one click sends it to the Google Address Validation API, returns a standardized address with component-level confidence scores, and writes the geocoded coordinates back to the record, all without leaving the Odoo Contact form.

Github
Address Validation API USPS CASS™ Contacts Integration LGPL-3

Product Overview

Contacts Google Address Validation adds the Google Address Validation API to the Odoo Contact form. It checks whether an entered address refers to a real, deliverable place, standardizes it for mailing, and geocodes it — directly from the Contact form, without leaving Odoo.

The Google Address Validation API is a Google Maps Platform service that accepts an address, separates it into individual components, and then attempts three operations on those components: corrects — providing component-level validation checks including sub-premises where available; completes — inferring missing or incorrect components; and formats — cleaning up and standardizing the address format. The response includes the complete validated address, the validation status of each individual component, and the best known geocode (latitude/longitude) for the address. Unlike the Geocoding API — which only converts an address into coordinates — the Address Validation API validates addresses for correctness at the component level.

Clicking Validate Address sends the contact's address to the API via a secure server-side POST to https://addressvalidation.googleapis.com/v1:validateAddress — the API key never reaches the browser. A dialog opens immediately with a recommendation (Accept / Confirm / Fix), a side-by-side comparison of the entered and standardized addresses, and a component breakdown showing the confirmation level of every address part. The user chooses to apply Google's standardized address, keep the current address while storing only the verdict, or discard without writing anything.

For US and Puerto Rico addresses, the API's optional USPS CASS™ (Coding Accuracy Support System) processing is enabled automatically. CASS™ is a USPS®-maintained certification program that confirms an address validation provider's ability to fill in missing information, standardize addresses, and deliver the most current and accurate result. The dialog shows the Delivery Point Validation (DPV) confirmation, vacancy and No-Stat indicators, and the CASS-corrected mailing address. The validation status — Validated, Needs Review, or Invalid — is stored on the contact and resets automatically whenever any address field is edited.

Who It's For

Logistics & Delivery Teams Verify delivery addresses before dispatch. Catch incomplete or unrecognized addresses at data-entry time rather than at the warehouse door — before a shipment fails or a driver navigates to the wrong location.
Marketing & Direct Mail Teams Standardize and validate mailing lists to reduce returned mail, improve postage efficiency, and meet USPS CASS™ deliverability standards for US campaigns — before printing labels, not after bounce reports.
Sales & CRM Teams Ensure that customer and prospect addresses are geocoded and standardized so map views, territory assignments, and proximity filters work on clean, verified data from the moment a contact is created.
Operations & Data Quality Teams Use the built-in search filters to audit the contact database — find unvalidated, problematic, or invalid addresses in bulk and prioritize clean-up without writing a custom domain or running an export.

The Problem It Solves

No Feedback at Entry Time

Odoo's address fields are free-text. Typos, incomplete streets, and non-existent postcodes are saved without warning and propagate to every downstream process that reads the contact's address — from shipping labels to invoice footers.

Geocoding Failures on Invalid Addresses

Map views, territory assignment, and proximity filtering all depend on accurate latitude and longitude. An unverified address may geocode to the wrong location — or not at all — leaving markers misplaced or contacts invisible on the map.

Inconsistent Address Formats

Addresses entered by different users follow different conventions. Standardizing them for mailing, reporting, or API submission is a manual and error-prone task without a validation step that enforces a canonical format.

No Visibility Into Data Quality

Without a stored validation status, there is no way to filter or report on which contacts have verified addresses and which need attention — until something breaks downstream and the damage is already done.

What's Inside

One shared foundation module and one Contacts-specific application module — bringing real-time address verification, standardization, and geocoding to every Odoo Contact record.

Module 01 · Foundation

Base Google Map

The core infrastructure module that registers the google_map view type, initialises the Google Maps JavaScript API using the dynamic library import approach, and provides the shared OWL component library used by every other module in this suite. Acts as the single, version-controlled entry point to the Google Maps platform for all downstream modules.

google_map view type google.maps.importLibrary() Dynamic library import OWL components Depends on: base

Why It Exists

Centralising the API initialisation and shared components in one module prevents each downstream module from loading the Maps API independently, ensures a single consistent API key configuration, and makes version upgrades a one-place change.

Module 02 · Application · Contacts

Contacts Google Address Validation

Adds a Validate Address button to the Odoo Contact form. Clicking it sends the address to the Google Address Validation REST API (v1:validateAddress) via a server-side request and opens a review dialog with the verdict, a side-by-side address comparison, and a component breakdown. The API key never reaches the browser.

Address Validation REST API Server-side request OWL widget USPS CASS™ Depends on: contacts, base_google_map

The google.address.validation Model

All API logic lives in the google.address.validation abstract model, keeping the OWL widget thin. It handles the dedicated server key lookup (with fallback to the browser key), the API request with per-status error mapping (PERMISSION_DENIED, RESOURCE_EXHAUSTED, INVALID_ARGUMENT, UNAVAILABLE), response parsing, and the Accept / Confirm / Fix recommendation logic using Google's possibleNextAction field.

Validation Dialog

The dialog presents a recommendation banner, verdict badges (completeness, granularity, unconfirmed / inferred / replaced component flags), a side-by-side comparison of entered vs. standardized address, and a component table listing each address part with its confirmation level (Confirmed / Plausible / Suspicious) and inferred, replaced, or spell-corrected markers.

Applying the Standardized Address

Choosing Apply Google's Address writes the standardized street, street2, city, state, zip, and country plus the geocode latitude/longitude in a single write call. State and country records are resolved server-side by ISO code — no manual ID mapping required.

USPS CASS™ for US & Puerto Rico

CASS processing is gated to US and PR addresses automatically. The dialog shows the DPV confirmation code, vacancy and No-Stat indicators, and the CASS-corrected mailing address. The DPV code is logged in the chatter. Per Google Maps Platform caching terms, the CASS-corrected address is displayed only — never stored on the record.

Stored Verdict & Auto-Reset

Validation status, granularity, validation date, and API response ID are stored on res.partner as readonly, copy=False fields. A write override resets the verdict whenever street, street2, city, zip, state, or country changes outside the validation flow.

API Key Setup

A dedicated server key restricted to the Address Validation API is strongly recommended. HTTP-referrer restrictions on the browser key cause PERMISSION_DENIED for server-side requests. Configure the server key in Settings → General Settings → Google Maps → Address Validation Server Key. On Odoo.sh (no static IP), set Application restrictions to None and rely on API restrictions plus usage quotas.

How It Works

The entire flow — from button click to stored verdict — stays inside Odoo. The API key never leaves the server.

  1. Open a Contact and enter an address. The Validate Address button appears below the address block on the Contact form as soon as the module is installed. No additional configuration is required for the standard use case.
  2. Click Validate Address. Any pending form edits are saved automatically before the request is sent, ensuring the stored verdict always matches the address that was actually validated. Unsupported countries are rejected server-side and the widget disables itself client-side using the same coverage list.
  3. Odoo sends a server-side API request. The address is built from street, street2, and a combined city + state + zip line. The contact's country code is passed as regionCode for more accurate results. USPS CASS™ is enabled automatically for US and PR addresses.
  4. Review the validation dialog. The dialog opens with a recommendation banner, verdict badges, a side-by-side comparison of entered vs. standardized address, and a component breakdown with confirmation levels. For US/PR addresses, the DPV code, vacancy status, and CASS-corrected mailing address are also shown.
  5. Choose an action. Apply Google's Address — writes the standardized address and geocoordinates to the contact and stores the verdict. Keep Current Address — stores only the verdict without changing the address. Discard — closes the dialog without writing anything.
  6. The validation badge reflects the stored status. Validated, Needs Review, or Invalid is shown next to the button. If any address field is later edited, the status resets to Not Validated automatically — stale verdicts never linger after an address change.

Key Features

Real-time address verification with component-level confidence scores, USPS CASS™ processing, and a stored audit trail — all from a single button on the Contact form.

Validation & Dialog

  • Validate Address button — One-click validation from the Contact form; the contact's country is passed as regionCode for more accurate results; pending edits are saved automatically before the request.
  • Recommendation banner — Accept / Confirm / Fix computed from Google's possibleNextAction field, with a documented heuristic fallback.
  • Side-by-side address comparison — Entered address vs. Google's standardized formatted address, shown together so the user can see exactly what would change.
  • Component-level confidence scores — Every address component (street number, route, city, state, postal code) listed with its confirmation level: Confirmed, Plausible, or Suspicious — plus inferred, replaced, and spell-corrected flags.
  • Three dialog actions — Apply Google's Address, Keep Current Address (verdict only), or Discard (no write).

Address Application & Geocoding

  • Apply standardized address in one write — Street, street2, city, state, zip, and country are written in a single operation. State and country records are resolved server-side by ISO code.
  • Geocoordinates from validation response — Latitude and longitude from the API response are written to partner_latitude / partner_longitude in the same call — no separate geocoding step needed.
  • USPS CASS™ for US & PR — DPV confirmation, vacancy and No-Stat indicators, and the CASS-corrected mailing address shown in the dialog; DPV code logged in the chatter. CASS-corrected address is displayed only, never stored, per Google Maps Platform caching terms.

Stored Verdict & Data Quality

  • Stored validation status — Validated / Needs Review / Invalid stored on res.partner alongside granularity, validation date, and API response ID.
  • Automatic status reset — Editing street, street2, city, zip, state, or country resets the status to Not Validated via a server-side write override — stale verdicts never persist after an address change.
  • Search filters by validation status — Built-in filters on the Contacts list for Address Validated, Needs Review, Invalid, and Not Validated — no custom domain required.
  • Coverage guard — Unsupported countries are rejected server-side; the widget disables itself client-side using the same coverage list, giving users a clear error rather than a silent failure.

Use Cases & Benefits

Verified, Deliverable Addresses

Know before shipping, mailing, or visiting whether an address refers to a real, deliverable place — not after a returned shipment or a failed delivery.

Standardized Formats Across Your Database

Applying Google's standardized address normalizes formats across all contacts — consistent spelling, correct postal codes, resolved state and country Many2one records — making reporting, sorting, and downstream API calls reliable.

Accurate Geocoordinates in One Step

Latitude and longitude are written from the validation response alongside the address — no separate geocoding call needed. Map views and territory assignments work immediately on validated contacts.

USPS Deliverability for US Contacts

CASS™ processing confirms whether a US address can receive USPS mail, flags vacant properties and No-Stat addresses, and provides the corrected mailing format — giving you the information needed for compliant direct mail campaigns.

Audit-Ready Validation Status

A stored, searchable validation status on every contact makes it easy to audit data quality, prioritize clean-up, and demonstrate address accuracy — without exporting data or writing custom reports.

No API Key Exposure in the Browser

Validation calls are made from the Odoo server, not the browser. The server key is stored in Odoo system parameters and never sent to the client, keeping API credentials secure even on shared or multi-user instances.

What's in the Bundle

Two modules — one shared foundation and one Contacts-specific application module — delivering real-time address verification and standardization on every Odoo Contact record.

Foundation

  1. base_google_map — Google Maps API loader, OWL component library, and google_map view type declaration

Application · Contacts

  1. contacts_google_address_validation — Validate Address button on the Contact form, validation dialog with recommendation and component breakdown, USPS CASS™ processing for US & PR, stored verdict fields on res.partner, automatic status reset on address change, and search filters by validation status

Contacts Google Address Validation · Real-time address verification, standardization, and geocoding — directly from the Odoo Contact form.