Address Validation Flow

Overview

The resolve_address tool resolves free-text addresses through a 4-source cascade, returning ranked candidates with full address details including coordinates.

Cascade Order

1. Saved addresses    (confidence: 0.95)  -- member's home and frequent addresses
2. Trip history       (confidence: 0.85)  -- addresses from previous trips
3. Facilities DB      (confidence: 0.80)  -- medical facilities via Spanner FORCE_INDEX
4. Google Maps        (confidence: 0.70)  -- geocoding fallback

graph TD Q["Free-text query"] --> S1["1. Saved Addresses"] Q --> S2["2. Trip History"] Q --> S3["3. Facility Database
(Spanner FORCE_INDEX)"] Q --> S4["4. Google Maps
(Geocoding fallback)"] S1 --> R["Rank & Deduplicate"] S2 --> R S3 --> R S4 --> R R --> C["Top 5 Candidates
with confidence scores"] style S1 fill:#48bb78,color:#fff style S2 fill:#4299e1,color:#fff style S3 fill:#ed8936,color:#fff style S4 fill:#9f7aea,color:#fff

Type-Aware Ranking

The type parameter influences candidate ranking:

Type	Boosted Sources
pickup	saved_address, trip_history
dropoff	facility

Input

Field	Type	Required	Description
session_id	string	yes	Active session
address	string	yes	Free-text address to resolve
type	string	no	pickup or dropoff hint

Output: Candidate

Each candidate includes:

Field	Type	Description
street	string	Street address
street2	string	Apt/suite (optional)
city	string	City
state	string	State (2-letter)
zip_code	string	ZIP code
latitude	float	Latitude
longitude	float	Longitude
facility_name	string	Facility name (if source=facility)
facility_id	string	Facility UUID (if source=facility)
phone	string	Facility phone (if available)
source	string	saved_address, trip_history, facility, google_maps
confidence	float	0.0 to 1.0

Coordinate Passthrough

Address coordinates flow end-to-end:

resolve_address --> returns candidates with lat/lng
set_booking_details --> accepts lat/lng on pickup/dropoff address objects
confirm_trip --> passes coordinates to nemt-trip-service for distance/ETA

This avoids redundant geocoding at trip creation time.

Facility Search

The facility search uses Spanner FORCE_INDEX hints for efficient lookups:

• Name search: facilities@{FORCE_INDEX=idx_facilities_name} with LOWER(name) LIKE @search
• Address search: facility_addresses@{FORCE_INDEX=idx_facility_addresses_address_search} with LOWER(address) LIKE @search

Sub-500ms facility lookups even with large datasets.