Google Places Integration

Interface to Google Places API (New) for searching places, retrieving details, and importing POIs. Provides caching, automatic photo downloads, and smart type mapping to internal POI types.

When to Use

Import attractions, landmarks, or cities from Google Places
Search for POIs in the admin panel
Auto-fill POI forms with Google Places data
Download and store place photos locally

Configuration

Environment Variables (.env)

GOOGLE_PLACES_API_KEY=your_api_key
GOOGLE_PLACES_TIMEOUT=30        # Optional, default: 30 seconds
GOOGLE_PLACES_MAX_RETRIES=3     # Optional, default: 3 retries

Config File: config/services.php -> google_places

Key Methods

searchPlaces

Search for places using text query. Returns array of place results with basic info.

$service = app(GooglePlacesService::class);

$results = $service->searchPlaces('Sagrada Familia Barcelona');
// Returns: [{ id, displayName, formattedAddress, types, location, photos }]

// With type filter
$results = $service->searchPlaces('Barcelona', 'museum');

Source: backend/app/Services/GooglePlacesService.php:99

getPlaceDetails

Get detailed information for a specific place. Results cached for 24 hours.

$details = $service->getPlaceDetails('ChIJk_s92NyipBIRUMnDG8Kq2Js');
// Returns: displayName, formattedAddress, types, location, photos,
//          editorialSummary, addressComponents, rating, etc.

Source: backend/app/Services/GooglePlacesService.php:168

findOrCreatePoi

Find existing POI by Google Places ID or create new one. Downloads first photo automatically.

$poi = $service->findOrCreatePoi('ChIJk_s92NyipBIRUMnDG8Kq2Js');
// Returns: Poi model (existing or newly created)

Source: backend/app/Services/GooglePlacesService.php:313

downloadPlacePhoto

Download a place photo and store locally in pois/images/.

$imagePath = $service->downloadPlacePhoto($photoName, $poiId);
// Returns: "pois/images/123_1735123456.jpg" or null on failure

Source: backend/app/Services/GooglePlacesService.php:241

Type Mapping

Google Places types are mapped to internal PoiType values:

Google Type	PoiType
locality, sublocality, administrative_area_level_3	City
church, mosque, city_hall, embassy, university	Landmark
natural_feature, park, national_park	NaturalFeature
tourist_attraction, museum, zoo, amusement_park	Attraction
(default)	Attraction

Source: backend/app/Services/GooglePlacesService.php:40-77

Caching

Data	TTL	Key Pattern
Place details	24 hours	`google_places_details_{placeId}`
POI select options	1 hour	`poi_select_options_*`

Admin Panel Usage

The POI form includes Google Places search integration:

Type in the “Search Google Places” field
Select a result from dropdown
Form fields auto-fill (name, type, country, coordinates, description)
Save to download photo and create POI

Source: backend/app/Filament/Resources/Pois/Schemas/PoiForm.php

Error Handling

Exception	Cause
`Exception("API key not configured")`	Missing `GOOGLE_PLACES_API_KEY`
`Exception("Google Places search failed: ...")`	API request failed
`Exception("Could not retrieve details...")`	Place not found

All errors are logged with [GooglePlacesService] prefix for filtering.

API Costs

Google Places API charges per request:

Endpoint	Cost
Text Search	$0.032 per request
Place Details	$0.017 per request
Place Photo	$0.007 per request

Caching reduces costs for repeated lookups.

POI System - POI data model and usage
Products Admin - Product itinerary configuration