Google Maps Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/google-maps-provider
   

   Requires geocoder-php/geocoder (≥v3.0) as a dependency.

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\GoogleMaps\GoogleMaps;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new GoogleMaps('YOUR_API_KEY'));
   
   // Geocode an address
   $results = $geocoder->geocode('1600 Amphitheatre Parkway, Mountain View, CA');
   foreach ($results as $hit) {
       echo $hit->getCoordinates(); // Lat/Lng
   }
   

3. First Use Case

   • Reverse Geocoding (coords → address):

     $results = $geocoder->reverseGeocode([37.422, -122.084]);
     

Implementation Patterns

Common Workflows

1. Address Validation

   $geocoder->geocode('Invalid Address')->isEmpty() // true/false
   

2. Batch Processing

   $addresses = ['addr1', 'addr2'];
   $results = $geocoder->geocodeBatch($addresses);
   

3. Caching Responses (via Geocoder\Provider\Cache)

   $cache = new \Geocoder\Provider\Cache\DoctrineCache();
   $geocoder->registerProvider(new GoogleMaps('API_KEY', [], $cache));
   

4. Integration with Laravel

   // In a service provider
   $this->app->singleton(Geocoder::class, function ($app) {
       $geocoder = new Geocoder();
       $geocoder->registerProvider(new GoogleMaps(config('services.google_maps.key')));
       return $geocoder;
   });
   

Provider-Specific Features

• Custom Request Options (e.g., language, region bias):

  $provider = new GoogleMaps('API_KEY', [
      'language' => 'fr',
      'region' => 'fr'
  ]);
  

• Place Autocomplete (via GoogleMaps::autocomplete()):

  $results = $geocoder->autocomplete('Paris', ['types' => 'geocode']);
  

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Ensure your Google Cloud API key has Geocoding API enabled.
   • Restrict the key to your app’s domain/IP to avoid abuse.

2. Rate Limits

   • Google’s free tier allows $200/month (~40,000 requests). Monitor usage via Google Cloud Console.
   • Implement retries with exponential backoff for OVER_QUERY_LIMIT errors.

3. Deprecated Methods

   • Avoid GoogleMaps::geocodeQuery() (use geocode() directly).
   • Prefer getCoordinates() over getPosition() (deprecated in v4+).

4. SSL Requirements

   • Google Maps Provider requires HTTPS for requests. Configure Laravel’s APP_URL accordingly.

Debugging

• Enable Debug Mode to log raw API responses:

  $provider = new GoogleMaps('API_KEY', [], [], true); // $debug = true
  

• Handle Exceptions:

  try {
      $results = $geocoder->geocode('...');
  } catch (\Geocoder\Exception\UnsupportedProviderException $e) {
      // Fallback to another provider
  }
  

Extension Points

1. Custom Response Parsing Override GoogleMaps::parse() to handle non-standard API responses.

2. Middleware for Requests Extend GoogleMaps and inject middleware (e.g., for auth headers):

   class CustomGoogleMaps extends GoogleMaps {
       protected function createClient() {
           $client = parent::createClient();
           $client->setDefaultOption('headers', ['X-Custom-Header' => 'value']);
           return $client;
       }
   }
   

3. Laravel Service Provider Bind the provider to the container with config:

   $this->app->bind(GoogleMaps::class, function ($app) {
       return new GoogleMaps(config('services.google_maps.key'));
   });
   

Performance Tips

• Batch Requests: Use geocodeBatch() for >10 addresses (reduces overhead).
• Cache Aggressively: Set a short TTL (e.g., 1 hour) for static addresses.
• Async Processing: Offload geocoding to a queue (e.g., Laravel Queues) for user-uploaded data.