[Photon] Reverse Geocoding with query filters (#1195)

* Add ability to filter reverse query on osm data

* Add osm tag filter feature & limit filter

* Clean cached results from Photon API

* Some documentation about Photon Geocoder

* Add support of osm tag filter for geocode query

* CS fix

* Add compatibility for multiple osm tag filters

* More documentation about multiple osm tag filters

* Fix array type for phpstan analyse

* Fix CS

* Update tests for multiple osm tags

* Documentation for multiple osm tags

src/Provider/Photon/Photon.php

@@ -71,6 +71,10 @@ public function geocodeQuery(GeocodeQuery $query): Collection
                 'limit' => $query->getLimit(),
                 'lang' => $query->getLocale(),
             ]);
+        $osmTagFilters = $this->buildOsmTagFilterQuery($query->getData('osm_tag'));
+        if (!empty($osmTagFilters)) {
+            $url .= $osmTagFilters;
+        }
 
         $json = $this->executeQuery($url);
 
@@ -98,8 +102,13 @@ public function reverseQuery(ReverseQuery $query): Collection
             .http_build_query([
                 'lat' => $latitude,
                 'lon' => $longitude,
+                'limit' => $query->getLimit(),
                 'lang' => $query->getLocale(),
             ]);
+        $osmTagFilters = $this->buildOsmTagFilterQuery($query->getData('osm_tag'));
+        if (!empty($osmTagFilters)) {
+            $url .= $osmTagFilters;
+        }
 
         $json = $this->executeQuery($url);
 
@@ -158,6 +167,25 @@ public function getName(): string
         return 'photon';
     }
 
+    /**
+     * @param string|array<int, string>|null $filters
+     */
+    private function buildOsmTagFilterQuery($filters): string
+    {
+        $query = '';
+        if (null === $filters) {
+            return $query;
+        }
+        if (is_string($filters)) {
+            return '&osm_tag='.urlencode($filters);
+        }
+        foreach ($filters as $filter) {
+            $query .= '&osm_tag='.urlencode($filter);
+        }
+
+        return $query;
+    }
+
     private function executeQuery(string $url): \stdClass
     {
         $content = $this->getUrlContents($url);

src/Provider/Photon/Readme.md

@@ -10,13 +10,56 @@
 This is the photon 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
-
+## Install
 ```bash
 composer require geocoder-php/photon-provider
 ```
 
-### Contribute
+## API Documentation
+https://photon.komoot.io
+https://github.com/komoot/photon
+
+## Usage
+
+### Basic usage
+You can use your own photon instance :
+```php
+// New instance of the provider :
+$provider = new Geocoder\Provider\Photon\Photon($httpClient, 'https://your-photon-root-url');
+// Run geocode or reverse query
+$query = $provider->geocodeQuery(\Geocoder\Query\GeocodeQuery::create('Paris'));
+$reverseQuery = $provider->reverseQuery(\Geocoder\Query\ReverseQuery::fromCoordinates(48.86036 ,2.33852));
+```
+
+### OSM Tag Feature
+You can search for location data based on osm tag filters.
+
+For example, you can filter a geocode query to only include results of type 'place'. You can even restrict it to only have places of type 'city'.
+In the reverse geocoding context you can search for the 3 pharmacies closest to a location.
+
+To see what you can do with this feature, check [the official photon documentation](https://github.com/komoot/photon#filter-results-by-tags-and-values)
+
+Below is an example to query the 3 pharmacies closest to a location :
+```php
+$provider = new Geocoder\Provider\Photon\Photon($httpClient, 'https://your-photon-root-url');
+$reverseQuery = \Geocoder\Query\ReverseQuery::fromCoordinates(52.51644, 13.38890)
+    ->withData('osm_tag', 'amenity:pharmacy')
+    ->withLimit(3);
+
+$results = $provider->reverseQuery($reverseQuery);
+```
+
+You can combine multiple osm tag filters :
+```php
+$provider = new Geocoder\Provider\Photon\Photon($httpClient, 'https://your-photon-root-url');
+$reverseQuery = \Geocoder\Query\GeocodeQuery::create('Paris')
+    ->withData('osm_tag', ['tourism:museum', 'tourism:gallery'])
+    ->withLimit(5);
+// Here we get 5 tourism results in Paris which are either museum or art gallery
+$results = $provider->reverseQuery($reverseQuery);
+```
+
 
-Contributions are very welcome! Send a pull request to the [main repository](https://github.com/geocoder-php/Geocoder) or 
+## Contribute
+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).

src/Provider/Photon/Tests/.cached_responses/photon.komoot.io_3c362ba852ee2323f9f25ca02c28cc5238959dbc

@@ -0,0 +1 @@
+s:1219:"{"features":[{"geometry":{"coordinates":[13.3879579,52.5185603],"type":"Point"},"type":"Feature","properties":{"osm_id":380498298,"country":"Deutschland","city":"Berlin","countrycode":"DE","postcode":"10117","locality":"Dorotheenstadt","type":"house","osm_type":"N","osm_key":"amenity","housenumber":"151","street":"Friedrichstraße","district":"Mitte","osm_value":"pharmacy","name":"Dorotheenstadt Apotheke"}},{"geometry":{"coordinates":[13.3874475,52.5196854],"type":"Point"},"type":"Feature","properties":{"osm_id":3331787468,"country":"Deutschland","city":"Berlin","countrycode":"DE","postcode":"10117","locality":"Dorotheenstadt","type":"house","osm_type":"N","osm_key":"amenity","housenumber":"25","street":"Georgenstraße","district":"Mitte","osm_value":"pharmacy","name":"Aschenbachs Apotheke"}},{"geometry":{"coordinates":[13.3903812,52.5122639],"type":"Point"},"type":"Feature","properties":{"osm_id":956306643,"country":"Deutschland","city":"Berlin","countrycode":"DE","postcode":"10117","locality":"Dorotheenstadt","type":"house","osm_type":"N","osm_key":"amenity","housenumber":"68","street":"Friedrichstraße","district":"Mitte","osm_value":"pharmacy","name":"Apotheke Q205"}}],"type":"FeatureCollection"}";

src/Provider/Photon/Tests/.cached_responses/photon.komoot.io_77590bd663047da83d48c67d9101f04a82e48976

@@ -0,0 +1 @@
+s:2127:"{"features":[{"geometry":{"coordinates":[-77.0372192,38.9002248],"type":"Point"},"type":"Feature","properties":{"osm_type":"W","osm_id":1049842804,"extent":[-77.0372192,38.9002248,-77.0370581,38.9002243],"country":"United States","osm_key":"highway","city":"Washington","countrycode":"US","osm_value":"secondary","postcode":"20006","name":"H Street Northwest","state":"District of Columbia","type":"street"}},{"geometry":{"coordinates":[-77.0366811,38.9002231],"type":"Point"},"type":"Feature","properties":{"osm_type":"W","osm_id":589539534,"extent":[-77.0370581,38.9002243,-77.0365521,38.9002187],"country":"United States","osm_key":"highway","city":"Washington","countrycode":"US","osm_value":"secondary","postcode":"20006","name":"H Street Northwest","state":"District of Columbia","type":"street"}},{"geometry":{"coordinates":[-77.03689992471391,38.90050395],"type":"Point"},"type":"Feature","properties":{"osm_id":55326891,"extent":[-77.0371738,38.9006934,-77.0367231,38.9003173],"country":"United States","city":"Washington","countrycode":"US","postcode":"20006","locality":"Golden Triangle","type":"house","osm_type":"W","osm_key":"tourism","housenumber":"800","street":"Black Lives Matter Plaza Northwest","osm_value":"hotel","name":"Hay-Adams Hotel","state":"District of Columbia"}},{"geometry":{"coordinates":[-77.0374769,38.9003895],"type":"Point"},"type":"Feature","properties":{"osm_type":"N","osm_id":367142942,"country":"United States","osm_key":"building","city":"Washington","street":"H Street Northwest","countrycode":"US","osm_value":"public","postcode":"20006","name":"United States Chamber of Commerce Building","state":"District of Columbia","type":"house"}},{"geometry":{"coordinates":[-77.0364753,38.9003613],"type":"Point"},"type":"Feature","properties":{"osm_id":4957653991,"country":"United States","city":"Washington","countrycode":"US","postcode":"20062","locality":"Golden Triangle","type":"house","osm_type":"N","osm_key":"tourism","street":"Black Lives Matter Plaza Northwest","osm_value":"information","name":"16th Street Meridian","state":"District of Columbia"}}],"type":"FeatureCollection"}";

src/Provider/Photon/Tests/.cached_responses/photon.komoot.io_8cd3447834c3ae8316dda602714b4ca4959eae65

@@ -0,0 +1 @@
+s:2187:"{"features":[{"geometry":{"coordinates":[2.2978602225671843,48.8643133],"type":"Point"},"type":"Feature","properties":{"osm_id":79219308,"extent":[2.2971088,48.8647083,2.2984772,48.8639024],"country":"France","city":"Paris","countrycode":"FR","postcode":"75116","locality":"Quartier de Chaillot","type":"house","osm_type":"W","osm_key":"tourism","street":"Rue Gaston de Saint-Paul","district":"Paris","osm_value":"museum","name":"Musée d'Art Moderne de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3518758,48.850724],"type":"Point"},"type":"Feature","properties":{"osm_id":237003117,"country":"France","city":"Paris","countrycode":"FR","postcode":"75005","locality":"Quartier Saint-Victor","type":"house","osm_type":"N","osm_key":"tourism","street":"Quai de la Tournelle","district":"Paris","osm_value":"museum","name":"Musée de l'Assistance Publique Hôpitaux de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3450724,48.8640506],"type":"Point"},"type":"Feature","properties":{"osm_id":3087374948,"country":"France","city":"Paris","countrycode":"FR","postcode":"75001","locality":"Les Halles","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue du Jour","district":"Paris","osm_value":"museum","name":"Musée du Barreau de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3153496472839956,48.866042],"type":"Point"},"type":"Feature","properties":{"osm_id":2778854,"extent":[2.3143339,48.866628,2.3156049,48.8654594],"country":"France","city":"Paris","countrycode":"FR","postcode":"75008","locality":"Quartier des Champs-Élysées","type":"house","osm_type":"R","osm_key":"tourism","street":"Avenue Winston Churchill","district":"Paris","osm_value":"museum","name":"Petit Palais","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3453019,48.8625016],"type":"Point"},"type":"Feature","properties":{"osm_id":1028569468,"country":"France","city":"Paris","countrycode":"FR","postcode":"75001","locality":"Les Halles","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue du Cinéma","district":"Paris","osm_value":"museum","name":"Salle des collections","state":"Île-de-France"}}],"type":"FeatureCollection"}";

src/Provider/Photon/Tests/.cached_responses/photon.komoot.io_f02c930445a15eb88482c0cc3c22a782c9ee6005

@@ -0,0 +1 @@
+s:4208:"{"features":[{"geometry":{"coordinates":[2.2978602225671843,48.8643133],"type":"Point"},"type":"Feature","properties":{"osm_id":79219308,"extent":[2.2971088,48.8647083,2.2984772,48.8639024],"country":"France","city":"Paris","countrycode":"FR","postcode":"75116","locality":"Chaillot","type":"house","osm_type":"W","osm_key":"tourism","street":"Rue Gaston de Saint-Paul","district":"Paris","osm_value":"museum","name":"Musée d'Art Moderne de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3153496472839956,48.866042],"type":"Point"},"type":"Feature","properties":{"osm_id":2778854,"extent":[2.3143339,48.866628,2.3156049,48.8654594],"country":"France","city":"Paris","countrycode":"FR","postcode":"75008","locality":"Quartier des Champs-Élysées","type":"house","osm_type":"R","osm_key":"tourism","street":"Avenue Winston Churchill","district":"Paris","osm_value":"museum","name":"Musée des beaux-arts de la Ville de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3518758,48.850724],"type":"Point"},"type":"Feature","properties":{"osm_id":237003117,"country":"France","city":"Paris","countrycode":"FR","postcode":"75005","locality":"Quartier Saint-Victor","type":"house","osm_type":"N","osm_key":"tourism","street":"Quai de la Tournelle","district":"Paris","osm_value":"museum","name":"Musée de l'Assistance Publique Hôpitaux de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3450724,48.8640506],"type":"Point"},"type":"Feature","properties":{"osm_id":3087374948,"country":"France","city":"Paris","countrycode":"FR","postcode":"75001","locality":"Les Halles","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue du Jour","district":"Paris","osm_value":"museum","name":"Musée du Barreau de Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3453019,48.8625016],"type":"Point"},"type":"Feature","properties":{"osm_id":1028569468,"country":"France","city":"Paris 1er Arrondissement","countrycode":"FR","postcode":"75001","locality":"Les Halles","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue du cinéma","district":"Paris","osm_value":"museum","name":"Salle des collections","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3587471,48.865943],"type":"Point"},"type":"Feature","properties":{"osm_id":5275610309,"country":"France","city":"Paris","countrycode":"FR","postcode":"75003","locality":"Quartier des Arts-et-Métiers","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue de Turbigo","district":"Paris","osm_value":"gallery","name":"Paris-B","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3314642,48.881227],"type":"Point"},"type":"Feature","properties":{"osm_id":10677716841,"country":"France","city":"Paris","countrycode":"FR","postcode":"75009","locality":"Quartier Saint-Georges","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue Blanche","district":"Paris","osm_value":"gallery","name":"Mu Gallery Paris","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3736064,48.8623128],"type":"Point"},"type":"Feature","properties":{"osm_id":10130759032,"country":"France","city":"Paris","countrycode":"FR","postcode":"75011","locality":"Quartier Saint-Ambroise","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue Saint-Sébastien","district":"Paris","osm_value":"gallery","name":"Paris-New York","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3644211,48.8602831],"type":"Point"},"type":"Feature","properties":{"osm_id":3210924575,"country":"France","city":"Paris","countrycode":"FR","postcode":"75003","locality":"Quartier des Archives","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue Debelleyme","district":"Le Marais","osm_value":"gallery","name":"lecœur-paris.com","state":"Île-de-France"}},{"geometry":{"coordinates":[2.3525427,48.86361],"type":"Point"},"type":"Feature","properties":{"osm_id":10744217145,"country":"France","city":"Paris","countrycode":"FR","postcode":"75003","locality":"Quartier Sainte-Avoye","type":"house","osm_type":"N","osm_key":"tourism","street":"Rue Saint-Martin","district":"Paris","osm_value":"gallery","name":"Galerie Paris Horizon","state":"Île-de-France"}}],"type":"FeatureCollection"}";