Mapbox Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/mapbox-provider
   

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

2. Basic Usage

   use Geocoder\Geocoder;
   use Geocoder\Provider\MapBoxProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new MapBoxProvider('YOUR_MAPBOX_ACCESS_TOKEN'));
   
   // Geocode an address
   $results = $geocoder->geocode('1600 Pennsylvania Ave NW, Washington, DC');
   foreach ($results as $hit) {
       echo $hit->getCoordinates(); // Output: [lat, lng]
   }
   

3. First Use Case

   • Reverse geocoding (coordinates → address):

     $results = $geocoder->reverse('38.9072', '-77.0369');
     

Where to Look First

• Provider Documentation (core Geocoder package).
• MapBox API Docs (for rate limits, response formats).
• MapBoxProvider class in src/Provider/MapBoxProvider.php (for customization hooks).

Implementation Patterns

Common Workflows

1. Batch Geocoding

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

2. Customizing HTTP Client (for retries, middleware):

   $client = new \GuzzleHttp\Client(['timeout' => 10]);
   $provider = new MapBoxProvider('TOKEN', [], $client);
   $geocoder->registerProvider($provider);
   

3. Caching Responses (avoid rate limits):

   use Geocoder\Cache\DoctrineCache;
   
   $cache = new DoctrineCache();
   $geocoder->registerCache($cache);
   

4. Handling Pagination (for large datasets):

   $provider->setOptions(['limit' => 50]); // MapBox API limit per request
   

Integration Tips

• Laravel Service Provider:

  public function register()
  {
      $this->app->singleton(Geocoder::class, function ($app) {
          $geocoder = new Geocoder();
          $geocoder->registerProvider(new MapBoxProvider(config('services.mapbox.token')));
          return $geocoder;
      });
  }
  

• Queue Jobs for Async Geocoding:

  // Dispatch a job to process addresses in bulk
  GeocodeAddresses::dispatch($addresses)->onQueue('geocoding');
  

• Fallback Providers (if MapBox fails):

  $geocoder->registerProvider(new \Geocoder\Provider\GoogleMapsProvider('GOOGLE_KEY'));
  

Gotchas and Tips

Pitfalls

1. Rate Limits

   • MapBox free tier: 100,000 requests/month (shared across all apps).
   • Solution: Cache aggressively or upgrade to a paid plan.
   • Debugging: Check X-RateLimit-Limit and X-RateLimit-Remaining headers.

2. Token Leaks

   • Never hardcode tokens in version control. Use .env:

     MAPBOX_TOKEN=your_token_here
     

   • Tip: Use Laravel’s config('services.mapbox.token').

3. Response Parsing

   • MapBox returns feature collections (GeoJSON). Ensure your code handles:

     {
       "type": "FeatureCollection",
       "features": [...]
     }
     

   • Gotcha: Empty responses may return null or an empty FeatureCollection.

4. Coordinate Order

   • MapBox returns [lng, lat] by default. Convert to [lat, lng]:

     [$lat, $lng] = [$hit->getCoordinates()[1], $hit->getCoordinates()[0]];
     

Debugging

• Enable Debug Mode:

  $provider->setOptions(['debug' => true]);
  

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

• Common HTTP Errors:

  Error	Cause	Fix
  401 Unauthorized	Invalid token	Verify MAPBOX_TOKEN
  400 Bad Request	Malformed query	URL-encode addresses
  429 Too Many Requests	Rate limit exceeded	Implement caching/retries

Extension Points

1. Custom Response Handling Override MapBoxProvider::createResultFromData() to transform responses:

   protected function createResultFromData($data)
   {
       // Add custom fields (e.g., MapBox's `place_name`)
       $result = parent::createResultFromData($data);
       $result->setAdditionalData($data['features'][0]['properties']);
       return $result;
   }
   

2. Mocking for Tests

   $provider = new MapBoxProvider('TOKEN');
   $provider->setClient(new \GuzzleHttp\HandlerStack());
   $provider->setMockResponse(file_get_contents('tests/fixtures/mapbox_response.json'));
   

3. Geofencing Use MapBox’s Geocoding API with bounding boxes:

   $provider->setOptions([
       'bbox' => [-74.2591, 40.4774, -73.7002, 40.9176] // NYC bounds
   ]);
   

4. Performance

   • Batch requests: Use geocodeBatch() for >50 addresses.
   • Parallelize: Dispatch jobs with Laravel\Bus\Queueable.