Google Maps Platform¶

Google Maps Platform address verification with Street View imagery, USPS DPV/RDI data, and address type classification. Addresses are validated through the Google Address Validation API (with USPS CASS processing for US and US-territory addresses), and verified addresses can additionally get a Street View Static API image URL that is stored with the order's verification metadata for fraud review. Choose it when you already run on Google Cloud, or when you want a photo of the shipping address alongside the validation verdict.

What It Provides¶

• Address validation strategy — GoogleMapsStrategy, registered with the strategy resolver as an AddressValidationStrategy implementation named google_maps when the extension activates (strategy family address_validation).
• Normalization — the validated address is rebuilt from Google's postal-address response (address lines, locality, administrative area, postal code, region code).
• Validity from address granularity — an address counts as valid when Google's verdict granularity is PREMISE, SUB_PREMISE, or PREMISE_PROXIMITY; anything coarser raises an unconfirmed_address warning.
• USPS enrichment — for US-territory addresses (enableUspsCass), deliverability and the DPV match code come from uspsData.dpvConfirmation, vacancy from the USPS vacancy flag, and a residential RDI hint from the carrier route.
• Address type classification — po_box (Google PO Box metadata), government/military (USPS address record type), otherwise residential/commercial from Google's residential flag.
• Street View imagery — when enabled and the address geocodes, the result carries a Street View Static API image URL (used in fraud review; the config field's own description notes this).
• Geocoding — latitude/longitude from Google's geocode, plus the place ID in provider metadata.
• Place name — Google's business name for the address, when present.
• Nothing else — the package contributes no webhook endpoints, Temporal workflows, schedules, admin pages, GraphQL fields, or event subscriptions.

Setup¶

1. Once installed (or dev-linked in development), the extension is discovered at startup; it can be enabled per channel from Settings > Extensions (per-channel activation via ChannelExtension).
2. In the Google Cloud Console, enable the Address Validation API and Street View Static API, then create an API key (the manifest's install hint: "Enable Address Validation and Street View APIs in Google Cloud Console, then configure the API key").
3. Provide the key. The strategy factory reads api_key from a config dict when one is supplied and otherwise falls back to the GOOGLE_MAPS_API_KEY environment variable — the strategy proxy registered at boot calls the factory with no config dict, so in the current code path the environment variable on the API service is what the validation call actually reads.
4. Select the provider for a channel by setting its Address Validation provider to google_maps — from Settings > Channels (edit a channel; saved through the updateChannel mutation), or the Settings > Geocoding & Geolocation page (which drives the configureChannelGeocoding GraphQL mutation); both require the settings.edit permission.
5. Checkout address validation only runs when the channel's Geocoding Enabled toggle is on — the checkout mutation reads geocoding_enabled before validating the shipping/billing addresses.
6. Test with the validateAddress GraphQL query, or the address-validation test panel on the Settings > Geocoding & Geolocation page ("Validate a structured address against configured providers").

Configuration Reference¶

Operational Notes¶

• Fail-open when unconfigured. With no API key the strategy returns the input address unmodified and marked valid. The core GeolocationService is also fail-open: if the provider raises, checkout validation is skipped rather than blocking the order.
• USPS CASS is territory-gated. enableUspsCass is set only for US, PR, VI, GU, AS, and MP; only those requests get DPV/vacancy data. Deliverability maps DELIVERABLE and DELIVERABLE_MISSING_SUBPREMISE to deliverable and UNDELIVERABLE to undeliverable, otherwise unknown.
• RDI is a heuristic here. The residential indicator is derived from the USPS carrier route (routes starting with R); unlike Smarty, this provider never reports a commercial RDI value — commercial classification comes through the address type instead.
• Suspicious components are flagged. Every address component Google marks UNCONFIRMED_AND_SUSPICIOUS raises a suspicious_component warning naming the component.
• Street View URLs embed the API key. The generated image URL is a direct Street View Static API request (location, size, key query parameters), so the API key appears in the URL, which the checkout mutation stores in the order's verification metadata (address_image_url) for fraud review and the order snapshot — alongside address type, RDI, DPV match, place name, and vacancy.
• Provider metadata on the result carries Google's full verdict and uspsData objects plus the geocode place ID.
• HTTP timeout is 10 seconds per API request.
• Alternative providers implementing the same strategy family: Smarty, Radar, and ShipStation Validate Address.