Kart- och geokod-integrationer
En resumen
Kart- och geokod-integrationer wraps Google Maps, Mapbox, OpenStreetMap, and HERE behind a unified MapEmbedConfig per venue, a tenant-scoped GeocodingResult cache with confidence scoring, and a RouteCalculation cache with multiple travel modes; it then exposes a public radius-based klubb-finder at GET /public/clubs/nearby that returns nearby clubs sorted by haversine distance — cross-tenant by default and tenant-scoped on demand, with a bounding-box pre-filter for performance.
Cómo funciona
Each venue can declare a MapEmbedConfig with embed_type (google_maps_embed, google_maps_static, mapbox_gl, mapbox_static, openstreetmap), a MapEmbedStyle block (zoom, map_type, dimensions, marker label, custom style URL), a reference to the underlying MappingIntegration in F14.04, and per-venue toggles for nearby clubs, directions link, Street View, and a custom marker icon URL. GET /geo/venues/{venue_id}/embed assembles the final embed URL from the venue's address, coordinates, and configuration, with a parallel /embed-config endpoint plus PATCH for runtime updates. Mapbox alternatives are first-class: generate_mapbox_embed_config() returns a complete Mapbox GL JS client config (style_url like mapbox://styles/mapbox/streets-v12, center, zoom, markers) and generate_mapbox_static_url() produces signed Mapbox Static Images URLs; OpenStreetMap is supported as a free fallback that requires no API key.
Geocoding is centralised through GeocodingResult, a tenant-scoped cache keyed on direction (forward or reverse), provider (google_maps, mapbox, openstreetmap, here), input address, and a normalised coordinate window; results carry a confidence score (0.0–1.0), a structured GeocodedAddress (formatted, street, city, postal_code, country, country_code, region), and TTL. POST /geo/geocode dispatches to the configured provider; POST /geo/reverse-geocode does the inverse with ~100 m bounding-box matching to maximise cache hit rate. Route planning uses RouteCalculation with travel_mode (driving, walking, cycling, transit), origin/destination GeoCoordinates, a RouteSummary (total_distance_m, total_duration_s, kilometre/minute conveniences), step list, encoded polyline, and a haversine-based estimator as fallback; the cache tolerates ~500 m drift on either endpoint.
The public /public/clubs/nearby endpoint accepts lat/lng, radius_km (0.5–500), level, and a comma-separated facilities filter; it pre-filters with a bounding box on venue coordinates, computes exact haversine distances, and returns ClubFinderResult rows sorted nearest first — usable from the marketing site without authentication.
Capacidades clave
- MapEmbedConfig per venue across Google, Mapbox, OpenStreetMap, and static formats
- Mapbox GL JS and static-image config generators with signed URLs
- Tenant-scoped GeocodingResult cache with confidence scoring and structured addresses
- Reverse geocoding with ~100 m bounding-box cache matching
- RouteCalculation with multiple travel modes, polylines, and haversine fallback
- Public klubb-finder with bounding-box pre-filter and haversine ranking
- OpenStreetMap as a free, key-less fallback provider
En la práctica
A new player visits petanque.life, clicks Find a club, and shares their location. The marketing site calls GET /public/clubs/nearby?lat=59.33&lng=18.07&radius_km=10&facilities=indoor,outdoor with no auth. The bounding-box pre-filter narrows the candidate set, haversine ranks the rest, and the response lists 14 clubs sorted by distance with venue details.
The user picks one and lands on the club page; the venue's MapEmbedConfig (mapbox_gl with the federation's branded style_url) renders an interactive map with a marker at the club, a directions link, and a Street View button. When they request driving directions, RouteCalculation hits its 500 m-tolerance cache and returns the route in 30 ms instead of the 600 ms a fresh Mapbox call would have cost.
Funcionalidades de este subsistema
6| ID | Status | Funcionalidades |
|---|---|---|
| F14.11.01 | Entregado | Google Maps embed för venue-sidor — MapEmbedConfig-samling tenant-scopad med venue_id/embed_type (google_maps_embed/google_maps_static/mapbox_gl/mapbox_static/openstreetmap)/style (MapEmbedStyle zoom/map_type/width/height/show_marker/marker_label/custom_style_url)/mapping_integration_id/show_nearby_clubs/nearby_radius_km/show_directions_link/show_street_view/custom_marker_icon_url; GET /geo/venues/{venue_id}/embed genererar embed-URL med adress, koordinater och directions-länk; GET /geo/venues/{venue_id}/embed-config + PATCH för konfigurationshantering ✅ PL-F1411 |
| F14.11.02 | Entregado | Mapbox alternativ med vector tiles — Mapbox GL JS-konfiguration med style_url (mapbox://styles/mapbox/streets-v12), center, zoom, markers; generate_mapbox_embed_config() returnerar fullständig klientkonfiguration; generate_mapbox_static_url() för statiska kartbilder via Mapbox Static Images API; stöd för OpenStreetMap som gratis fallback utan API-nyckel ✅ PL-F1411 |
| F14.11.03 | Entregado | Geocoding för venue-adresser — GeocodingResult-samling tenant-scopad med direction (forward/reverse)/provider (google_maps/mapbox/openstreetmap/here)/input_address/coordinates (GeoCoordinates lat/lng)/address (GeocodedAddress formatted_address/street/city/postal_code/country/country_code/region)/confidence 0.0–1.0/cached_at/expires_at/mapping_integration_id; POST /geo/geocode med cachning, provider-val och integration mot MappingIntegration ✅ PL-F1411 |
| F14.11.04 | Entregado | Reverse geocoding för spelarposition — POST /geo/reverse-geocode med lat/lng input, cachning med ~100m bounding-box matchning, returnerar GeocodedAddress med strukturerad adress; stöd för Google Maps och Mapbox providers; tenant-scopad cachning med TTL ✅ PL-F1411 |
| F14.11.05 | Entregado | Route-beräkning till tävlingsvenues — RouteCalculation-samling tenant-scopad med provider/travel_mode (driving/walking/cycling/transit)/origin (GeoCoordinates)/destination (GeoCoordinates)/venue_id/status (ok/not_found/zero_results/error)/summary (RouteSummary total_distance_m/total_duration_s/total_distance_km/total_duration_min)/steps[RouteStep]/polyline/cached_at/expires_at; POST /geo/route med haversine-baserad uppskattning, cachning med ~500m tolerans ✅ PL-F1411 |
| F14.11.06 | Entregado | Klubb-finder med radius-sökning — GET /public/clubs/nearby publik endpoint utan autentisering med lat/lng/radius_km (0.5–500)/level/facilities (kommaseparerad)/skip/limit (1–100); bounding-box pre-filter på venue-koordinater sedan exakt haversine-avstånd; resultat sorterade efter avstånd (närmast först); ClubFinderResult med club_id/club_name/club_code/distance_km/location/address/city/facilities/level/venue_id/venue_name; cross-tenant som standard, tenant-scopad med valfri tenant_id-parameter ✅ PL-F1411 |