[Google Places] fix + support both reverse modes: Search & Nearby (#1070)

* fix + support both reverse modes: Search & Nearby

* style fix

* clarifications of mode + defaults

* updated for 1.1.0

* Update CHANGELOG.md

Co-authored-by: wivaku <wivaku@gmail.com>

Author: wivaku

src/Provider/GoogleMapsPlaces/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 The change log describes what is "Added", "Removed", "Changed" or "Fixed" between each release.
 
+## 1.2.0
+
+### Added
+
+- Adds support for reverse query `Nearby` mode (rankby `prominence` + `radius`, or `distance` + `type/keyword/name`)
+
+### Fixed
+
+- reverse query w/ `Search` mode checked for `type/keyword/name`, but only `type` is allowed
+
 ## 1.1.0
 
 ### Removed
@@ -16,4 +26,4 @@ The change log describes what is "Added", "Removed", "Changed" or "Fixed" betwee
 
 ## 1.0.0
 
-First release of this library. 
+First release of this library.

src/Provider/GoogleMapsPlaces/GoogleMapsPlaces.php

@@ -62,6 +62,11 @@ final class GoogleMapsPlaces extends AbstractHttpProvider implements Provider
      */
     const GEOCODE_MODE_SEARCH = 'search';
 
+    /**
+     * @var string
+     */
+    const GEOCODE_MODE_NEARBY = 'nearby';
+
     /**
      * @var string
      */
@@ -110,7 +115,7 @@ public function geocodeQuery(GeocodeQuery $query): Collection
             return $this->fetchUrl(self::SEARCH_ENDPOINT_URL_SSL, $this->buildPlaceSearchQuery($query));
         }
 
-        throw new InvalidArgument('Mode must be one of `%s, %s`', self::GEOCODE_MODE_FIND, self::GEOCODE_MODE_SEARCH);
+        throw new InvalidArgument(sprintf('Mode must be one of `%s, %s`', self::GEOCODE_MODE_FIND, self::GEOCODE_MODE_SEARCH));
     }
 
     /**
@@ -122,7 +127,14 @@ public function geocodeQuery(GeocodeQuery $query): Collection
      */
     public function reverseQuery(ReverseQuery $query): Collection
     {
-        return $this->fetchUrl(self::SEARCH_ENDPOINT_URL_SSL, $this->buildNearbySearchQuery($query));
+        // for backward compatibility: use SEARCH as default mode (includes formatted_address)
+        if (self::GEOCODE_MODE_SEARCH === $query->getData('mode', self::GEOCODE_MODE_SEARCH)) {
+            $url = self::SEARCH_ENDPOINT_URL_SSL;
+        } else {
+            $url = self::NEARBY_ENDPOINT_URL_SSL;
+        }
+
+        return $this->fetchUrl($url, $this->buildNearbySearchQuery($query));
     }
 
     /**
@@ -212,35 +224,65 @@ private function buildPlaceSearchQuery(GeocodeQuery $geocodeQuery): array
      */
     private function buildNearbySearchQuery(ReverseQuery $reverseQuery): array
     {
+        // for backward compatibility: use SEARCH as default mode (includes formatted_address)
+        $mode = $reverseQuery->getData('mode', self::GEOCODE_MODE_SEARCH);
+
         $query = [
             'location' => sprintf(
                 '%s,%s',
                 $reverseQuery->getCoordinates()->getLatitude(),
                 $reverseQuery->getCoordinates()->getLongitude()
             ),
-            'rankby' => 'distance',
+            'rankby' => 'prominence',
         ];
 
         if (null !== $reverseQuery->getLocale()) {
             $query['language'] = $reverseQuery->getLocale();
         }
 
-        $query = $this->applyDataFromQuery($reverseQuery, $query, [
+        $validParameters = [
             'keyword',
             'type',
             'name',
             'minprice',
             'maxprice',
             'name',
             'opennow',
-        ]);
+            'radius',
+        ];
+
+        if (self::GEOCODE_MODE_NEARBY === $mode) {
+            $validParameters[] = 'rankby';
+        }
 
-        $requiredParameters = array_filter(array_keys($query), function (string $key) {
-            return in_array($key, ['keyword', 'type', 'name'], true);
-        });
+        $query = $this->applyDataFromQuery($reverseQuery, $query, $validParameters);
 
-        if (1 !== count($requiredParameters)) {
-            throw new InvalidArgument('One of `type`, `keyword`, `name` is required to be set in the Query data for Reverse Geocoding');
+        if (self::GEOCODE_MODE_NEARBY === $mode) {
+            // mode:nearby, rankby:prominence, parameter:radius
+            if ('prominence' === $query['rankby'] && !isset($query['radius'])) {
+                throw new InvalidArgument('`radius` is required to be set in the Query data for Reverse Geocoding when ranking by prominence');
+            }
+
+            // mode:nearby, rankby:distance, parameter:type/keyword/name
+            if ('distance' === $query['rankby']) {
+                if (isset($query['radius'])) {
+                    unset($query['radius']);
+                }
+
+                $requiredParameters = array_intersect(['keyword', 'type', 'name'], array_keys($query));
+
+                if (1 !== count($requiredParameters)) {
+                    throw new InvalidArgument('One of `type`, `keyword`, `name` is required to be set in the Query data for Reverse Geocoding when ranking by distance');
+                }
+            }
+        }
+
+        if (self::GEOCODE_MODE_SEARCH === $mode) {
+            // mode:search, parameter:type
+
+            if (!isset($query['type'])) {
+                throw new InvalidArgument('`type` is required to be set in the Query data for Reverse Geocoding when using search mode');
+            }
         }
 
         return $query;
@@ -309,6 +351,10 @@ private function fetchUrl(string $url, array $query): AddressCollection
                 $address = $address->withFormattedAddress($result->formatted_address);
             }
 
+            if (isset($result->vicinity)) {
+                $address = $address->withVicinity($result->vicinity);
+            }
+
             if (isset($result->types)) {
                 $address = $address->withType($result->types);
             }

src/Provider/GoogleMapsPlaces/Model/GooglePlace.php

@@ -39,6 +39,11 @@ final class GooglePlace extends Address
      */
     private $formattedAddress;
 
+    /**
+     * @var string|null
+     */
+    private $vicinity;
+
     /**
      * @var string|null
      */
@@ -175,6 +180,27 @@ public function withFormattedAddress(string $formattedAddress = null)
         return $new;
     }
 
+    /**
+     * @return null|string
+     */
+    public function getVicinity()
+    {
+        return $this->vicinity;
+    }
+
+    /**
+     * @param string|null $vicinity
+     *
+     * @return GooglePlace
+     */
+    public function withVicinity(string $vicinity = null)
+    {
+        $new = clone $this;
+        $new->vicinity = $vicinity;
+
+        return $new;
+    }
+
     /**
      * @return string|null
      */

src/Provider/GoogleMapsPlaces/README.md

@@ -1,4 +1,4 @@
-# Google Maps Geocoder provider
+# Google Places Geocoder provider
 [![Build Status](https://travis-ci.org/geocoder-php/google-maps-places-provider.svg?branch=master)](http://travis-ci.org/geocoder-php/google-maps-places-provider)
 [![Latest Stable Version](https://poser.pugx.org/geocoder-php/google-maps-places-provider/v/stable)](https://packagist.org/packages/geocoder-php/google-maps-places-provider)
 [![Total Downloads](https://poser.pugx.org/geocoder-php/google-maps-places-provider/downloads)](https://packagist.org/packages/geocoder-php/google-maps-places-provider)
@@ -7,11 +7,10 @@
 [![Quality Score](https://img.shields.io/scrutinizer/g/geocoder-php/google-maps-places-provider.svg?style=flat-square)](https://scrutinizer-ci.com/g/geocoder-php/google-maps-places-provider)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
 
-This is the Google Maps Places provider from the PHP Geocoder. This is a **READ ONLY** repository. See the
-[main repo](https://github.com/geocoder-php/Geocoder) for information and documentation. 
+This is the Google Places provider from the PHP Geocoder. This is a **READ ONLY** repository. See the
+[main repo](https://github.com/geocoder-php/Geocoder) for information and documentation.
 
 ## Install
-
 ```bash
 composer require geocoder-php/google-maps-places-provider
 ```
@@ -20,34 +19,87 @@ composer require geocoder-php/google-maps-places-provider
 https://developers.google.com/places/web-service
 
 ## Usage
-This provider often requires extra data when making queries, due to requirements of the underlying places API.
+This provider often requires extra data when making queries, due to requirements of the underlying Places API.
 
 ### Geocoding
 This provider supports two different modes of geocoding by text.
 
 #### Find Mode
 This is the default mode. It required an exact places name. It's not very forgiving, and generally only returns a single result
 
+```php
+$results = $provider->geocodeQuery(
+    GeocodeQuery::create('Museum of Contemporary Art Australia')
+);
+```
+
 #### Search Mode
-This mode will perform a search based on the input text. 
+This mode will perform a search based on the input text.
 It's a lot more forgiving that the `find` mode, but results will contain all fields and thus be billed at the highest rate.
 
 ```php
-$findResults = $provider->geocodeQuery(GeocodeQuery::create('Museum of Contemporary Art Australia')); // One Result
+$results = $provider->geocodeQuery(
+    GeocodeQuery::create('art museum sydney')
+        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
+);
+```
 
-$searchResults = $provider->geocodeQuery(GeocodeQuery::create('art museum sydney'))
-                    ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH); // 20 Results
+around location (which is similar to reverse geocoding, see below):
+
+```php
+$results = $provider->geocodeQuery(
+    GeocodeQuery::create('bar')
+        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
+        ->withData('location', '-32.926642, 151.783026')
+);
 ```
 
 ### Reverse Geocoding
-When reverse geocoding, you are required to supply either a `keyword`, `type` or `name`.
-See https://developers.google.com/places/web-service/search#PlaceSearchRequests
+Three options available for reverse geocoding of latlon coordinates:
+
+- mode `search` + type (e.g.) `bar`: uses Google Place API [Text search](https://developers.google.com/places/web-service/search#TextSearchRequests), requires `type`
+  - is similar to: Search around location (see previous section)
+- mode `nearby` + rankby `distance`: uses Google Place API [Nearby search](https://developers.google.com/places/web-service/search#PlaceSearchRequests), requires `type/keyword/name`
+- mode `nearby` + rankby `prominence`: uses Google Place API [Nearby search](https://developers.google.com/places/web-service/search#PlaceSearchRequests), requires `radius`
+
+Default mode: `search` (because of backward compatibility). When using mode `nearby` default rankby: `prominence`.
+Mode `search` + type and mode `nearby` + type/keyword/name are very similar.
+Mode `search` gives formatted_address, mode `nearby` gives vicinity instead.  E.g.:
+
+- `search`: has "formatted_address": "7 Cope St, Redfern NSW 2016"
+- `nearby`: has "vicinity" instead: "7 Cope St, Redfern"
+
+Examples
+
+```php
+$results = $provider->reverseQuery(
+    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
+        // ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH) // =default
+        ->withData('type', 'bar') // requires type
+    );
+$address = $results->first()->getFormattedAddress();
+```
+
+```php
+$results = $provider->reverseQuery(
+    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
+        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_NEARBY)
+        //->withData('rankby','prominence'); // =default
+        ->withData('radius', 500) // requires radius (meters)
+    );
+$vicinity = $results->first()->getVicinity();
+```
 
 ```php
-$results = $provider->reverseQuery(ReverseQuery::fromCoordinates(-33.892674, 151.200727)->withData('type', 'bar'));
+$results = $provider->reverseQuery(
+    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
+        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_NEARBY)
+        ->withData('rankby','distance');
+        ->withData('keyword', 'bar') // requires type/keyword/name
+    );
 ```
 
 ### Contribute
 
-Contributions are very welcome! Send a pull request to the [main repository](https://github.com/geocoder-php/Geocoder) or 
+Contributions are very welcome! Send a pull request to the [main repository](https://github.com/geocoder-php/Geocoder) or
 report any issues you find on the [issue tracker](https://github.com/geocoder-php/Geocoder/issues).