This would break the "common provider API".. @geocoder-php/geocoder WDYT?

Almost all of the "conventional" street level geocoding services support constraining results via a bounding box. A quick dive through various provider's documentation shows this is supported by ArcGIS, Google, Mapzen, Nominatim, TomTom and Yandex.

So this isn't an unreasonable enhancement IMHO.

We're also coming up to thinking about what Geocoder 4.0 will look like and as we're hiking the major version number, this is a good time to think about expanding the current common provider API.

This will need some thought about how to represent this consistently through the various providers as well as how to handle cases where this isn't supported.

As a concept, I think this is a valid one, but not the way in which it's implemented in this PR though.

+1 to having the bounding box parameter. This can drastically improve search results.

I'm not a big fan of it, as @willdurand said it will break the "common provider API". If you use this feature, you can't change the provider easily.

I agree with both @willdurand and @Baachi. This library is meant to give a "common provider API". That means that a third party library author should be able to write something like this and be confident that the code works no matter what geocoder is provided.

class ThirdPartyCode
  public function __construct(Geocoder $gecoder) {
    $this->geocoder = $geocoder;
  }
  public function bar() {
    $result = $this->geocoder->geocode('foobar');
    // ...
  }

The third party library does not care if you change the geocoder provider. This is called the Liskov substitution principle.

However. A application author should be able to make a decision that he/she never will change the provider. The application code may not type hint for Geocoder but for GoogleMaps or GeocoderThatSupportsBoundsInterface.

class ApplicationCode
  public function __construct(GoogleMaps $gecoder) {
    $this->geocoder = $geocoder;
  }
  public function bar() {
    $this->geocoder->setBounds(/* .. */);
    $result = $this->geocoder->geocode('foobar');
    // ...
  }

My point is that this library should define a contract which all geocoder providers MUST follow. But a specific provider (or a group of providers) may have some extra features. I see to issues with supporting that. I am 👍 for a PR like this.

I just created #576

This is now supported with GeocodeQuery::setBounds

Sorry, it was only the Query that had bounds support. I added a PR to make sure you can use bounds with google. See #627