Geonames Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/geonames-provider
   

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

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\GeoNamesProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new GeoNamesProvider('YOUR_GEONAMES_USERNAME'));
   
   // Reverse geocoding (lat/lng → address)
   $results = $geocoder->reverseQuery('40.714224', '-73.961452');
   foreach ($results as $result) {
       echo $result->getStreet() . "\n";
   }
   
   // Forward geocoding (address → lat/lng)
   $results = $geocoder->geocodeQuery('1600 Pennsylvania Ave NW, Washington, DC');
   foreach ($results as $result) {
       echo $result->getCoordinates()->getLatitude() . "\n";
   }
   

3. First Use Case

   • Address Validation: Use geocodeQuery() to verify if an address exists and fetch coordinates.
   • Location Lookup: Use reverseQuery() to display nearby landmarks or services for a given lat/lng.

Implementation Patterns

Common Workflows

1. Batch Processing

   $addresses = ['123 Main St', '456 Oak Ave'];
   foreach ($addresses as $address) {
       $result = $geocoder->geocodeQuery($address)->first();
       if ($result) {
           // Process valid coordinates
       }
   }
   

2. Fallback Strategy Combine with other providers (e.g., Google, OpenStreetMap) for redundancy:

   $geocoder->registerProvider(new GeoNamesProvider('USERNAME'));
   $geocoder->registerProvider(new \Geocoder\Provider\OpenStreetMapProvider());
   

3. Caching Responses Use Laravel’s cache to avoid repeated API calls:

   $cacheKey = 'geonames_' . md5($address);
   $result = Cache::remember($cacheKey, now()->addHours(1), function() use ($geocoder, $address) {
       return $geocoder->geocodeQuery($address)->first();
   });
   

4. Custom Field Extraction Extract specific fields (e.g., country, postal code) from results:

   $result = $geocoder->reverseQuery($lat, $lng)->first();
   $country = $result->getCountry();
   $postalCode = $result->getPostalCode();
   

5. Integration with Laravel Models Add a geocoding trait to Eloquent models:

   use Geocoder\Geocoder;
   
   trait HasGeocode {
       public function getCoordinatesAttribute() {
           $geocoder = new Geocoder();
           $geocoder->registerProvider(new GeoNamesProvider(config('services.geonames.username')));
           return $geocoder->geocodeQuery($this->address)->first()?->getCoordinates();
       }
   }
   

Gotchas and Tips

Pitfalls

1. Rate Limits

   • GeoNames has strict rate limits (e.g., 2,000 requests/day for free accounts).
   • Solution: Implement exponential backoff or use caching aggressively.
   • Debugging: Check HTTP status codes (e.g., 429 Too Many Requests).

2. Incomplete Results

   • Some addresses (e.g., rural or non-Western) may return null or partial data.
   • Solution: Combine with other providers or log failed queries for manual review.

3. Username Sensitivity

   • The GeoNames username is case-sensitive and tied to your account.
   • Solution: Store it in .env:

     GEONAMES_USERNAME=your_username_here
     

     Then load it in config/services.php:

     'geonames' => [
         'username' => env('GEONAMES_USERNAME'),
     ],
     

4. Deprecated Methods

   • Older versions of geocoder-php/geocoder may use getFormattedAddress() instead of getStreet().
   • Solution: Check the Geocoder PHP docs for version-specific changes.

5. Time Zone Handling

   • GeoNames returns times in UTC. Convert to local time if needed:

     $time = $result->getTimezone()->getTimeZone()->getOffset($timestamp);
     

Tips

1. Error Handling Wrap queries in try-catch to handle API failures gracefully:

   try {
       $result = $geocoder->geocodeQuery($address)->first();
   } catch (\Geocoder\Exception\UnsupportedOperationException $e) {
       // Fallback logic
   }
   

2. Testing Use mock providers for unit tests:

   $geocoder->registerProvider(new \Geocoder\Provider\MockProvider());
   

3. Performance

   • Bulk Geocoding: Use geocodeQuery() in batches (e.g., 100 addresses at a time) to avoid rate limits.
   • Async Processing: Offload geocoding to a queue (e.g., Laravel Queues) for background jobs.

4. Custom Providers Extend GeoNamesProvider to add custom parameters:

   class CustomGeoNamesProvider extends GeoNamesProvider {
       public function __construct($username, array $options = []) {
           parent::__construct($username, array_merge([
               'language' => 'en',
               'featureClass' => 'P',
           ], $options));
       }
   }
   

5. Logging Log failed queries to identify patterns (e.g., specific regions or address formats that fail):

   \Log::error('Geocoding failed for: ' . $address, ['exception' => $e]);
   

6. Fallback to Free Tier If using a paid GeoNames account, ensure the free tier (freegeoip.net) is not accidentally triggered by misconfigured endpoints.