Mapquest Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/mapquest-provider
   

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

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\MapQuest\MapQuest;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new MapQuest('YOUR_MAPQUEST_API_KEY'));
   
   // Geocode an address
   $results = $geocoder->geocode('1600 Amphitheatre Parkway, Mountain View, CA');
   foreach ($results as $result) {
       echo $result->getCoordinates(); // Output: [37.422, -122.084]
   }
   

3. First Use Case

   • Reverse Geocoding: Fetch address details from coordinates.

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

Where to Look First

• Documentation: Check the Geocoder PHP docs for provider-specific details.
• Provider Class: MapQuest class in src/Provider/MapQuest/MapQuest.php for API specifics.
• Configuration: Review config/geocoder.php if using Laravel’s geocoder package.

Implementation Patterns

Common Workflows

1. Batch Geocoding

   $addresses = ['Address 1', 'Address 2'];
   $results = $geocoder->geocodeBatch($addresses);
   

2. Error Handling

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

3. Laravel Integration

   • Publish config:

     php artisan vendor:publish --provider="Geocoder\Laravel\GeocoderServiceProvider"
     

   • Configure in .env:

     GEOCODER_MAPQUEST_KEY=your_api_key_here
     

4. Caching Responses Use Laravel’s cache or Geocoder’s built-in caching:

   $geocoder->registerProvider(new MapQuest('key', ['cache' => true]));
   

Integration Tips

• Rate Limiting: MapQuest has API limits (e.g., 15,000 requests/day). Implement retries or queue jobs for bulk operations.
• Fallback Providers: Register multiple providers for redundancy:

  $geocoder->registerProvider(new MapQuest('key'));
  $geocoder->registerProvider(new \Geocoder\Provider\GoogleMaps\GoogleMaps('google_key'));
  

• Custom Responses: Extend the Result class to parse MapQuest-specific fields (e.g., adminArea5 for county).

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode keys in version-controlled files. Use Laravel’s .env or a secrets manager.
   • Fix: Validate keys via middleware or environment checks.

2. Rate Limits

   • Exceeding limits returns 429 Too Many Requests. Implement exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     $client = new RetryableHttpClient(null, [
         'max_retries' => 3,
         'delay' => 1000,
     ]);
     

3. Deprecated Endpoints

   • MapQuest may deprecate endpoints silently. Test with their API sandbox.
   • Fix: Subscribe to their developer newsletter.

4. Coordinate Precision

   • MapQuest returns coordinates with 6 decimal places. Round for storage:

     $lat = round($result->getLatitude(), 4);
     

Debugging

• Enable Debugging

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

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

• Check HTTP Status Codes MapQuest returns:

  • 200: Success.
  • 400: Invalid request (e.g., malformed address).
  • 401: Invalid API key.
  • 500: Server error.

Extension Points

1. Custom Provider Logic Override the MapQuest class to modify request/response handling:

   class CustomMapQuest extends \Geocoder\Provider\MapQuest\MapQuest {
       protected function createClient() {
           return new \GuzzleHttp\Client(['timeout' => 30]);
       }
   }
   

2. Add New Fields Extend the Result class to include MapQuest-specific data:

   class MapQuestResult extends \Geocoder\Model\Result {
       public function getAdminArea5() {
           return $this->getExtraProperties()['adminArea5'] ?? null;
       }
   }
   

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

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

Configuration Quirks

• Default Options The provider uses these defaults:

  [
      'key' => null, // Required
      'host' => 'www.mapquestapi.com',
      'timeout' => 10,
      'locale' => 'en-US',
      'cache' => false,
  ]
  

  Override via constructor or registerProvider():

  $geocoder->registerProvider(new MapQuest('key', ['locale' => 'es-ES']));