Locationiq Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/geocoder geocoder-php/locationiq-provider
   

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\LocationIQ\LocationIQProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new LocationIQProvider('YOUR_LOCATIONIQ_API_KEY'));
   
   // Geocode an address
   $results = $geocoder->geocode('1600 Amphitheatre Parkway, Mountain View, CA');
   foreach ($results as $result) {
       echo $result->getCoordinates(); // Output: lat, lng
   }
   
   // Reverse geocode coordinates
   $coordinates = new \Geocoder\Model\Coordinates(-33.8688, 151.2093);
   $results = $geocoder->reverse($coordinates);
   foreach ($results as $result) {
       echo $result->getAddress(); // Output: formatted address
   }
   

3. First Use Case

   • Address Validation: Quickly validate if an address exists and return structured data.
   • Lat/Lng Lookup: Convert human-readable addresses to coordinates for mapping (e.g., Google Maps API integration).

Implementation Patterns

Common Workflows

1. Batch Geocoding

   $addresses = ['1600 Amphitheatre Parkway', '1 Infinite Loop', '1 Hacker Way'];
   $results = $geocoder->geocodeBatch($addresses);
   

2. Reverse Geocoding with Custom Fields

   $coordinates = new \Geocoder\Model\Coordinates(37.7749, -122.4194);
   $result = $geocoder->reverse($coordinates)->first();
   echo $result->getStreetNumber(); // e.g., "1600"
   echo $result->getPostcode();     // e.g., "94043"
   

3. Integration with Laravel Requests

   use Illuminate\Http\Request;
   
   public function store(Request $request) {
       $geocoder = app(Geocoder::class);
       $results = $geocoder->geocode($request->address);
       $coordinates = $results->first()->getCoordinates();
       // Save to DB: $coordinates->getLatitude(), $coordinates->getLongitude()
   }
   

4. Caching Results

   $geocoder->registerProvider(
       new LocationIQProvider('API_KEY', ['cache' => new \Geocoder\Cache\FileCache('/path/to/cache')])
   );
   

Provider-Specific Patterns

• Rate Limiting: LocationIQ has usage limits. Implement retries or queue jobs for bulk operations.

  use Illuminate\Support\Facades\Queue;
  
  Queue::later(now()->addMinutes(1), function () use ($geocoder, $addresses) {
      $geocoder->geocodeBatch($addresses);
  });
  

• Fallback Providers: Combine with other providers (e.g., NominatimProvider) for redundancy.

  $geocoder->registerProvider(new LocationIQProvider('API_KEY'));
  $geocoder->registerProvider(new \Geocoder\Provider\Nominatim\NominatimProvider());
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode API keys in version control. Use Laravel's .env:

     LOCATIONIQ_API_KEY=your_key_here
     

   • Restrict the key to your app’s IP/domain in LocationIQ dashboard.

2. Rate Limits

   • Free tier: 1,000 requests/day. Exceeding this returns 429 Too Many Requests.
   • Fix: Implement exponential backoff or use a queue system.

3. Precision of Results

   • LocationIQ may return partial addresses (e.g., missing street numbers). Validate responses:

     if (!$result->getStreetNumber()) {
         // Handle incomplete data (e.g., retry with a different provider)
     }
     

4. Timeouts

   • Default HTTP client timeout (30s) may be too short for slow responses. Configure Guzzle:

     $provider = new LocationIQProvider('API_KEY', [
         'http_client' => new \GuzzleHttp\Client(['timeout' => 60])
     ]);
     

Debugging

• Enable Debug Mode

  $geocoder->registerProvider(new LocationIQProvider('API_KEY', ['debug' => true]));
  

  Logs HTTP requests/responses to storage/logs/geocoder.log.

• Check HTTP Status Codes

  • 400: Invalid API key or malformed request.
  • 404: Address not found.
  • 500: LocationIQ server error (retry later).

Extension Points

1. Custom Response Mapping Override default field mappings (e.g., rename display_name to formatted_address):

   $provider = new LocationIQProvider('API_KEY', [
       'mapping' => [
           'lat' => 'lat',
           'lng' => 'lon',
           'address' => 'display_name',
       ]
   ]);
   

2. Add Headers Include custom headers (e.g., for authentication):

   $provider = new LocationIQProvider('API_KEY', [
       'http_options' => [
           'headers' => ['X-Custom-Header' => 'value']
       ]
   ]);
   

3. Mocking for Tests Use Geocoder\Provider\MockProvider to simulate responses:

   $geocoder->registerProvider(new \Geocoder\Provider\MockProvider([
       '1600 Amphitheatre Parkway' => new \Geocoder\Model\Coordinates(37.422, -122.084)
   ]));