@volter/twin-googlemaps

A local Google Maps Platform twin — offline, deterministic replicas of the Maps web-service APIs (maps.googleapis.com, places.googleapis.com, roads.googleapis.com, addressvalidation.googleapis.com) in vendor-faithful response shapes, with the real status semantics and the API-key gate. The unmodified @googlemaps/google-maps-services-js client points at it and gets Maps-correct responses.

world-googlemaps serve [--port N] [--root DIR] [--read-only]
world-googlemaps conformance [--root DIR]

Coverage

The capability manifest (src/googlemaps-capabilities.ts) is an honest partial denominator across the Maps Platform web services. Most of the surface is enumerated as the denominator; a core slice is done (each with a failable, deterministic verify asserting response values plus a negative status path); the long tail (parameters/options like waypoints, travel modes, pagination, field masks, Place Photos, the Routes API) is honest todo.

Deterministic canned data, NOT real geodata. A local twin cannot reproduce Google's geospatial index, road graph, live traffic, or imagery. It returns faithful response shapes with stable, deterministic values: a given query always maps to the same canned result. Known place names (Los Angeles, New York, Mountain View, London, Tokyo) resolve to a small canned dataset; any other well-formed query is synthesized deterministically from its hash so the twin never falsely 404s a valid request.

Modeled (done):

• Auth gate. Legacy web services gate on the key= query parameter → missing/invalid key returns the API's own status:"REQUEST_DENIED" envelope (HTTP 200); sentinel keys exercise OVER_QUERY_LIMIT / OVER_DAILY_LIMIT. The v1 / "New" APIs gate on the X-Goog-Api-Key header → missing key returns a 403 google.rpc.Status PERMISSION_DENIED.
• Geocoding. geocode/json — forward + reverse, by address, components, or place_id; the full real result shape (formatted_address, address_components with long_name/short_name/types, geometry with location, location_type, viewport, place_id, types); OK, ZERO_RESULTS, INVALID_REQUEST; connector-seeded overrides.
• Distance Matrix. distancematrix/json — M×N matrix of OK/NOT_FOUND elements with duration/distance (value + human text), metric/imperial units, origin_addresses/destination_addresses. (Matches the QA-stack contract exactly.)
• Directions. directions/json — routes[] with summary, legs[] (distance/duration/start_address/end_address/start_location/ end_location/steps[]), overview_polyline (real Encoded Polyline), bounds, copyrights, warnings, geocoded_waypoints; ZERO_RESULTS / INVALID_REQUEST.
• Places (legacy). Find Place from Text, Text Search, Nearby Search (radius vs rankby=distance), Place Details, Autocomplete (with structured_formatting), Query Autocomplete — with OK/ZERO_RESULTS/ NOT_FOUND/INVALID_REQUEST.
• Places API (New) — v1. places:searchText, places:searchNearby, places:autocomplete, and GET /v1/places/{id} with the v1 shapes (displayName.text, location.latitude/longitude, formattedAddress, id/name) and google.rpc.Status errors.
• Roads. snapToRoads, nearestRoads (snappedPoints[] with location/placeId/originalIndex), speedLimits.
• Time Zone / Elevation / Geolocation. timezone/json (timeZoneId/rawOffset/dstOffset/timeZoneName), elevation/json (locations + path samples, real haversine-independent deterministic elevations), geolocation/json (location + accuracy).
• Address Validation — v1. :validateAddress with verdict, geocode, responseId.
• Static Maps / Street View Static. Validate parameters and return image metadata (content type, size) + Street View metadata (pano_id, date, copyright); serving the image bytes themselves is a filed todo.
• Audit. A local audit log of requests (GET /twin/audit) — read-only requests are not logged.
• Connector. Injected-client pulls for geocode overrides (pullGoogleMapsGeocodes) and place snapshots (pullGoogleMapsPlaces), idempotent. The kernel adapter performGoogleMapsAction handles supported entries; it does not turn synthetic geocode seeds into writes to the real Maps service.

Not yet modeled (honest todo): Directions/Distance Matrix travel modes, waypoints + optimization, alternatives, departure-time traffic, avoid filters, transit details; Place Photos (binary), search pagination (next_page_token / pageToken), opening hours, reviews, session tokens, field masks; Roads interpolate; Time Zone DST from timestamp; Address Validation USPS/CASS + per-component confirmation; Static Maps styling; the Routes API (New) (computeRoutes / computeRouteMatrix); geocode region/components/language biasing and Plus Codes; and the image bytes — deterministic placeholder bytes at the Static Maps URL, for a Street View pano, and at the Place Photos URL (all three return only metadata today).

Architecture

State lives in the @volter/world-core event/action log (geocode overrides + the audit log); there is no ad-hoc store. The serve path makes no real network calls; connector functions accept injected executors for real Maps I/O and are not used by the local handler. This is an API-first vendor with no operator-facing dashboard, so the pack ships no UI mirror — coverage is API + connector.