Geocoder Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require antwebes/geocoder
   

   Add the service provider in config/app.php:

   'providers' => [
       // ...
       Antwebes\Geocoder\GeocoderServiceProvider::class,
   ],
   

2. Basic Usage Locate the package’s config file at config/geocoder.php and set your preferred provider (e.g., OpenStreetMap or GoogleMaps). Example:

   'providers' => [
       'openstreetmap' => [
           'enabled' => true,
           'host' => 'nominatim.openstreetmap.org',
       ],
   ],
   

3. First Use Case Resolve an address to coordinates in a controller:

   use Antwebes\Geocoder\Facades\Geocoder;
   
   public function getCoordinates()
   {
       $result = Geocoder::geocode('1600 Amphitheatre Parkway, Mountain View, CA');
       return $result->getCoordinates(); // Returns [lat, lng]
   }
   

Implementation Patterns

Common Workflows

1. Geocoding (Address → Coordinates)

   $coordinates = Geocoder::geocode('Paris, France')->getCoordinates();
   

2. Reverse Geocoding (Coordinates → Address)

   $address = Geocoder::reverse('48.8566', '2.3522')->getAddress();
   

3. Batch Processing Use collect() to process multiple addresses efficiently:

   $addresses = ['New York', 'London', 'Tokyo'];
   $results = collect($addresses)->map(fn($addr) => Geocoder::geocode($addr));
   

4. Fallback Providers Configure multiple providers in config/geocoder.php and let the package auto-fallback:

   'providers' => [
       'openstreetmap' => ['enabled' => true],
       'googlemaps' => ['enabled' => true, 'api_key' => env('GOOGLE_MAPS_API_KEY')],
   ],
   

Integration Tips

• Laravel Models Add accessors/mutators to models for seamless geocoding:

  class Location extends Model
  {
      public function getCoordinatesAttribute()
      {
          return Geocoder::geocode($this->address)->getCoordinates();
      }
  }
  

• Caching Cache geocoding results to avoid rate limits (e.g., OpenStreetMap’s 1 request/sec):

  $coordinates = Cache::remember("geo_{$address}", now()->addHours(1), function() use ($address) {
      return Geocoder::geocode($address)->getCoordinates();
  });
  

• Queue Jobs Offload geocoding to a queue for long-running tasks:

  GeocodeJob::dispatch($address)->onQueue('geocoding');
  

  class GeocodeJob implements ShouldQueue
  {
      public function handle()
      {
          $this->coordinates = Geocoder::geocode($this->address)->getCoordinates();
      }
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limits

   • OpenStreetMap enforces 1 request/second. Use caching or batch processing.
   • Google Maps has strict quotas (free tier: 40,000 requests/month). Monitor usage via Google Cloud Console.

2. Provider-Specific Quirks

   • OpenStreetMap: Requires user_agent in requests. Configure in config/geocoder.php:

     'openstreetmap' => [
         'user_agent' => 'my-app/1.0 (your-email@example.com)',
     ],
     

   • GoogleMaps: Mandatory api_key and billing setup. Avoid hardcoding keys in config.

3. Data Inconsistencies

   • Geocoding results may vary by provider. Validate outputs (e.g., check getConfidence()):

     if (Geocoder::geocode($address)->getConfidence() < 80) {
         throw new \Exception('Low-confidence result');
     }
     

4. Timeouts

   • Some providers (e.g., OpenStreetMap) may timeout. Increase PHP’s max_execution_time or use async processing.

Debugging

• Enable Logging Add to config/geocoder.php:

  'log' => true,
  

  Check storage/logs/laravel.log for API responses/errors.

• Mock Providers for Testing Use the MockProvider in tests:

  Geocoder::setProvider('mock');
  Geocoder::mockResponse(['lat' => 40.7128, 'lng' => -74.0060]);
  

Extension Points

1. Custom Providers Extend Antwebes\Geocoder\Providers\ProviderInterface to add new geocoding services (e.g., Mapbox, HERE Maps).

2. Response Parsing Override default response handling by binding a custom ResponseParser:

   Geocoder::setResponseParser(new CustomParser());
   

3. Middleware Add middleware to validate/transform requests/responses globally:

   Geocoder::extend(function ($geocoder) {
       $geocoder->getProvider()->addMiddleware(new ValidateAddressMiddleware());
   });