Google Maps Places Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/google-maps-provider
   

   (Note: The package is likely geocoder-php/google-maps-provider, not google-maps-places-provider—verify the correct package name in your project.)

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\GoogleMaps\GoogleMapsProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new GoogleMapsProvider('YOUR_GOOGLE_API_KEY'));
   
   // Example: Search for places
   $results = $geocoder->geocodeQuery('1600 Amphitheatre Parkway, Mountain View, CA');
   foreach ($results as $result) {
       echo $result->getCoordinates(); // Lat/Lng
   }
   

3. First Use Case

   • Reverse Geocoding: Convert coordinates to an address.

     $results = $geocoder->reverseQuery(37.422, -122.084);
     

Implementation Patterns

Common Workflows

1. Place Autocomplete Use the GoogleMapsProvider to fetch suggestions as users type:

   $provider = $geocoder->provider('google_maps');
   $predictions = $provider->autocomplete('San Fran');
   

2. Place Details Fetch detailed info (e.g., opening hours, photos) for a specific place ID:

   $details = $provider->placeDetails('ChIJD4pP5NIi4okR5383L3FrYWw');
   

3. Nearby Search Find places within a radius:

   $nearby = $provider->nearbySearch(37.422, -122.084, 'restaurant', 1000);
   

4. Integration with Laravel

   • Service Provider: Bind the geocoder in AppServiceProvider:

     $this->app->singleton(Geocoder::class, function () {
         $geocoder = new Geocoder();
         $geocoder->registerProvider(new GoogleMapsProvider(config('services.google_maps.key')));
         return $geocoder;
     });
     

   • Config: Add to config/services.php:

     'google_maps' => [
         'key' => env('GOOGLE_MAPS_API_KEY'),
     ],
     

5. Caching Responses Cache frequent queries (e.g., autocomplete) to reduce API calls:

   $cacheKey = 'places_autocomplete_' . md5($query);
   $predictions = Cache::remember($cacheKey, now()->addMinutes(5), function () use ($provider, $query) {
       return $provider->autocomplete($query);
   });
   

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Ensure your Google API key has Places API enabled in the Google Cloud Console.
   • Avoid hardcoding keys; use Laravel’s .env:

     GOOGLE_MAPS_API_KEY=your_key_here
     

2. Rate Limits

   • Google Maps API has usage limits. Monitor your quota in the Google Cloud Console.
   • Implement retries for OVER_QUERY_LIMIT errors:

     try {
         $results = $provider->geocodeQuery($address);
     } catch (\Geocoder\Exception\UnsupportedProviderException $e) {
         // Fallback to another provider or retry later
     }
     

3. Place ID vs. Reference

   • Confuse place_id (stable) with reference (temporary). Always use place_id for placeDetails().

4. Language/Region Bias

   • Specify language and region parameters to avoid unexpected results:

     $provider->autocomplete('Paris', ['language' => 'en', 'region' => 'fr']);
     

Debugging

1. Enable Debugging Set the debug option to log HTTP requests:

   $provider = new GoogleMapsProvider($apiKey, [
       'debug' => true,
       'http_client' => new \GuzzleHttp\Client(['debug' => true]),
   ]);
   

2. Handle Missing Data Google’s responses may omit fields (e.g., opening_hours). Use null checks:

   $hours = $details->getOpeningHours() ?? 'Not available';
   

Extension Points

1. Custom Providers Extend the base GoogleMapsProvider to add domain-specific logic:

   class CustomGoogleMapsProvider extends GoogleMapsProvider {
       public function searchByType($type, $location) {
           return $this->client->request('GET', '/maps/api/place/nearbysearch/json', [
               'query' => [
                   'location' => $location,
                   'keyword' => $type,
               ],
           ]);
       }
   }
   

2. Event Listeners Listen for geocoding events (e.g., Geocoder\Event\GeocodeEvent) to log or transform results:

   $geocoder->addListener(function ($event) {
       if ($event->getResult()->getType() === 'Feature') {
           // Custom logic
       }
   });
   

3. Fallback Providers Register multiple providers and fall back gracefully:

   $geocoder->registerProvider(new GoogleMapsProvider($apiKey));
   $geocoder->registerProvider(new \Geocoder\Provider\OpenStreetMapProvider());
   

Performance Tips

• Batch Requests: Use PlaceDetailsBatch for multiple place IDs:

  $batch = new \Geocoder\Provider\GoogleMaps\PlaceDetailsBatch($provider);
  $batch->addPlaceId('ChIJD4pP5NIi4okR5383L3FrYWw');
  $batch->addPlaceId('ChIJD4pP5NIi4okR5383L3FrYWx');
  $details = $batch->getDetails();
  

• Async Processing: Offload geocoding to a queue (e.g., Laravel Queues) for non-critical paths.