Yandex Provider Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require geocoder-php/yandex-provider
   

   Ensure geocoder-php/geocoder is also installed (core package).

2. First Use Case: Reverse Geocoding

   use Geocoder\Geocoder;
   use Geocoder\Provider\Yandex\YandexProvider;
   
   $geocoder = new Geocoder();
   $geocoder->registerProvider(new YandexProvider('YOUR_API_KEY'));
   
   $result = $geocoder->reverse(55.755826, 37.617698); // Moscow coordinates
   $address = $result->getFirstResult()->getFormatedAddress();
   

3. Where to Look First

   • Provider Documentation (core Geocoder docs).
   • Yandex API Reference (for API-specific quirks).
   • YandexProvider class source: Link (check for undocumented features).

Implementation Patterns

Common Workflows

1. Forward Geocoding (Address → Coordinates)

   $result = $geocoder->geocodeQuery('Красная площадь, Москва');
   $coordinates = $result->getFirstResult()->getCoordinates();
   

2. Batch Processing

   $geocoder->batchGeocodeQuery(['address1', 'address2', 'address3']);
   

3. Customizing Requests

   $provider = new YandexProvider('API_KEY', [
       'language' => 'ru_RU', // Override default language
       'results' => 3,        // Request up to 3 results
   ]);
   

4. Integration with Laravel

   • Service Provider Binding

     // app/Providers/AppServiceProvider.php
     public function register()
     {
         $this->app->singleton(Geocoder::class, function () {
             $geocoder = new Geocoder();
             $geocoder->registerProvider(new YandexProvider(config('services.yandex.key')));
             return $geocoder;
         });
     }
     

   • Config File

     // config/services.php
     'yandex' => [
         'key' => env('YANDEX_GEOCODE_API_KEY'),
         'options' => [
             'language' => 'en_US',
         ],
     ],
     

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

   $geocoder->registerProvider(new YandexProvider('API_KEY', [], new CacheAdapter()));
   

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Yandex may throttle or block requests if:
     • Rate limits are exceeded (default: 100 requests/minute for non-paid plans).
     • IP address is flagged (common in shared hosting).
   • Fix: Implement exponential backoff or use a queue (e.g., Laravel Queues).

2. Character Encoding Issues

   • Cyrillic or special characters may break requests.
   • Fix: Ensure language and address parameters use UTF-8 encoding.

     $result = $geocoder->geocodeQuery(utf8_encode('Манежная площадь, 1'));
     

3. No Direct HTTP Client Control

   • The provider uses Guzzle under the hood, but you cannot easily swap it.
   • Workaround: Extend YandexProvider to inject a custom client:

     $client = new \GuzzleHttp\Client(['timeout' => 30]);
     $provider = new YandexProvider('API_KEY', [], null, $client);
     

4. Result Parsing Quirks

   • Yandex’s response format may vary (e.g., metaData fields).
   • Tip: Inspect raw responses for undocumented fields:

     $rawResponse = $result->getProviderResponse();
     

5. Paid Plan Limitations

   • Free tier has limited daily requests (e.g., 10,000/day).
   • Tip: Monitor usage via Yandex’s API Dashboard.

Debugging Tips

1. Enable Debugging

   $provider->setDebug(true); // Logs raw requests/responses
   

2. Handle Exceptions

   try {
       $result = $geocoder->geocodeQuery('invalid address');
   } catch (\Geocoder\Exception\UnsupportedProviderException $e) {
       // Provider-specific error
   } catch (\Geocoder\Exception\NoResultException $e) {
       // No results found
   }
   

3. Fallback Providers Register multiple providers for redundancy:

   $geocoder->registerProvider(new YandexProvider('API_KEY'));
   $geocoder->registerProvider(new GoogleProvider('GOOGLE_KEY'));
   

Extension Points

1. Custom Response Processing Extend YandexProvider to modify how responses are parsed:

   class CustomYandexProvider extends YandexProvider {
       protected function parseResponse($response) {
           // Override logic here
           return parent::parseResponse($response);
       }
   }
   

2. Add Custom Metadata Yandex returns rich metadata (e.g., boundedBy, kind). Access it via:

   $result->getFirstResult()->getMetaData();
   

3. Geofencing Combine with geocoder-php/geocoder’s filterByCircle for location-based queries:

   $results = $geocoder->geocodeQuery('park');
   $filtered = $geocoder->filterByCircle($results, 55.755826, 37.617698, 1000); // 1km radius