Skip to content
Volāre Documentation

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

Section titled “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

Section titled “Configuration”

Environment Variables (.env)

Section titled “Environment Variables (.env)”
Terminal window
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

Section titled “Key Methods”

searchPlaces

Section titled “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:113

getPlaceDetails

Section titled “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:176

findOrCreatePoi

Section titled “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:326

downloadPlacePhoto

Section titled “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:250

Type Mapping

Section titled “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

The table above is a representative subset; the full map is the TYPE_MAPPING constant.

Source: backend/app/Services/GooglePlacesService.php:37-79 (TYPE_MAPPING)

Caching

Section titled “Caching”
Data TTL Key Pattern
Place details 24 hours google_places_details_{placeId}
POI select options 1 hour poi_select_options_*

Admin Panel Usage

Section titled “Admin Panel Usage”

The POI form includes Google Places search integration:

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

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

Error Handling

Section titled “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

Section titled “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.

Section titled “Related”