Arcgis Online Provider Laravel Package

Getting Started

First Steps

1. Installation Add the provider to your Laravel project via Composer:

   composer require geocoder-php/arcgis-online-provider
   

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

2. Basic Setup Register the provider in your config/geocoder.php:

   'providers' => [
       'arcgis_online' => [
           'key' => env('ARCGIS_ONLINE_API_KEY'),
           'url' => env('ARCGIS_ONLINE_URL', 'https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer'),
       ],
   ],
   

3. First Use Case: Geocoding an Address Use the Geocoder facade to query ArcGIS Online:

   use Geocoder\Geocoder;
   use Geocoder\Provider\ArcgisOnline\ArcgisOnlineProvider;
   
   $geocoder = new Geocoder();
   $results = $geocoder->geocode('1600 Pennsylvania Ave, Washington, DC');
   dd($results->first()->getPosition());
   

Implementation Patterns

Common Workflows

1. Reverse Geocoding Convert coordinates to an address:

   $results = $geocoder->reverse('40.7128° N, 74.0060° W');
   dd($results->first()->getFormattedAddress());
   

2. Batch Processing Use geocodeQuery() for bulk operations:

   $query = $geocoder->query('New York, NY');
   $results = $query->get();
   

3. Custom Provider Configuration Extend the provider for retries or custom headers:

   $provider = new ArcgisOnlineProvider([
       'key' => env('ARCGIS_API_KEY'),
       'url' => env('ARCGIS_URL'),
       'timeout' => 10,
       'headers' => ['User-Agent' => 'MyApp/1.0'],
   ]);
   

4. Integration with Laravel Models Add geocoding to a User model:

   public function resolveAddressAttribute()
   {
       $results = $geocoder->geocode($this->address);
       return $results->first()?->getFormattedAddress();
   }
   

Gotchas and Tips

Pitfalls & Debugging

1. API Key Restrictions

   • ArcGIS Online enforces usage limits (e.g., 500 requests/day for free tiers).
   • Monitor usage via ArcGIS Developer Dashboard.
   • Tip: Cache responses aggressively (e.g., Cache::remember()).

2. Rate Limiting & Throttling

   • Default timeout is 30s; increase if responses are slow:

     'timeout' => 60,
     

   • Tip: Use retry() in queries:

     $query->retry(3, 1000); // Retry 3 times with 1s delay
     

3. URL & Endpoint Quirks

   • The provider defaults to geocode.arcgis.com, but custom endpoints (e.g., enterprise ArcGIS) require explicit URL config.
   • Gotcha: Some endpoints (e.g., World_Street_Map) may return null for non-English addresses.

4. Error Handling

   • ArcGIS returns HTTP 400 for invalid queries. Validate inputs:

     try {
         $results = $geocoder->geocode($request->address);
     } catch (\Geocoder\Exception\UnsupportedOperationException $e) {
         return back()->withError('Invalid address format');
     }
     

5. Extension Points

   • Custom Response Parsing: Override ArcgisOnlineProvider::parse() to handle non-standard responses.
   • Logging: Enable Guzzle logging for debugging:

     $provider->setClient(new \GuzzleHttp\Client(['debug' => true]));
     

6. Environment-Specific Config

   • Use Laravel’s config() helper to switch providers dynamically:

     $geocoder = new Geocoder();
     $geocoder->registerProvider('arcgis_online', config('geocoder.providers.arcgis_online'));