Here Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/here-provider
   

   Ensure geocoder-php/geocoder is also installed (required dependency).

2. First Use Case: Reverse Geocoding

   use Geocoder\Geocoder;
   use Geocoder\Provider\Here\HereProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new HereProvider('YOUR_HERE_API_KEY'));
   
   $result = $geocoder->reverseQuery('52.5170365,13.3888601');
   dd($result->getCoordinates(), $result->getDescription());
   

3. Where to Look First

   • Provider Documentation (core Geocoder package)
   • Here API Docs (for rate limits, response formats, and edge cases)
   • HereProvider class source: Focus on query(), reverseQuery(), and geocodeQuery() methods.

Implementation Patterns

Common Workflows

1. Geocoding (Address → Coordinates)

   $result = $geocoder->geocodeQuery('100 Broadway, New York, NY');
   $coordinates = $result->getCoordinates(); // [lat, lng]
   

2. Reverse Geocoding (Coordinates → Address)

   $result = $geocoder->reverseQuery('52.5170365,13.3888601');
   $address = $result->getDescription(); // "Brandenburg Gate, Berlin, Germany"
   

3. Batch Processing

   $addresses = ['100 Broadway', '221B Baker St'];
   $results = $geocoder->batchGeocodeQuery($addresses);
   

4. Fallback Providers

   $geocoder->registerProvider(new HereProvider('API_KEY'));
   $geocoder->registerProvider(new \Geocoder\Provider\GoogleMaps\GoogleMapsProvider('GOOGLE_API_KEY'));
   $result = $geocoder->geocodeQuery('Invalid Address'); // Falls back to Google if Here fails.
   

Integration Tips

• Caching Responses Use Laravel’s cache to avoid hitting API limits:

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

• Rate Limiting Here’s API has strict limits (e.g., 100,000 requests/month for free tier). Log requests and monitor usage:

  $geocoder->registerProvider(new HereProvider('API_KEY', [
      'logger' => new \Monolog\Logger('here'),
  ]));
  

• Customizing HTTP Client Override the default Guzzle client for retries/timeouts:

  $client = new \GuzzleHttp\Client([
      'timeout' => 10,
      'connect_timeout' => 5,
  ]);
  $provider = new HereProvider('API_KEY', ['client' => $client]);
  

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Here’s API keys are tied to specific domains. Test in a staging environment first.
   • Fix: Use a wildcard (*) in the allowed domains during development, then restrict to production domains.

2. Response Parsing Errors

   • Here’s API returns nested JSON. Malformed responses (e.g., missing items array) can break parsing.
   • Debug: Check the raw response with:

     $provider->getClient()->getConfig('debug');
     

3. Coordinate Order

   • Here’s API returns [longitude, latitude] by default, but Geocoder expects [latitude, longitude].
   • Workaround: Use Geocoder\Provider\Normalizer\Normalizer to standardize coordinates.

4. Rate Limit Headers

   • Ignoring X-RateLimit-* headers can lead to sudden API failures.
   • Tip: Log headers and implement exponential backoff:

     $response = $provider->getClient()->request('GET', $url);
     $remainingRequests = $response->getHeader('X-RateLimit-Remaining')[0];
     

Debugging

• Enable Debug Mode

  $provider = new HereProvider('API_KEY', ['debug' => true]);
  

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

• Common HTTP Errors

  Error Code	Cause	Solution
  401	Invalid API key	Regenerate key in Here’s Developer Portal.
  403	IP/domain not whitelisted	Update allowed domains in API settings.
  429	Rate limit exceeded	Wait or upgrade plan.
  500	Internal server error	Retry with exponential backoff.

Extension Points

1. Custom Response Normalization Extend HereProvider to handle non-standard responses:

   class CustomHereProvider extends HereProvider {
       protected function parseResponse($data) {
           // Override to handle custom Here API response formats.
       }
   }
   

2. Adding Custom Fields Extract additional fields from Here’s response (e.g., houseNumber, postalCode):

   $result = $geocoder->reverseQuery('52.5170365,13.3888601');
   $address = $result->getAddress();
   $postalCode = $address->getPostalCode(); // Default
   $houseNumber = $data['items'][0]['result']['address']['houseNumber']; // Custom
   

3. Mocking for Tests Use a mock HTTP client to avoid real API calls:

   $mockHandler = new \GuzzleHttp\Handler\MockHandler([
       new \GuzzleHttp\Psr7\Response(200, [], file_get_contents('tests/fixtures/here_response.json'))
   ]);
   $client = new \GuzzleHttp\Client(['handler' => $mockHandler]);
   $provider = new HereProvider('API_KEY', ['client' => $client]);