Some documentation about Photon Geocoder

geocoder-php · jbelien · Feb 9, 2025 · Jul 20, 2023 · Jul 31, 2023 · Jul 31, 2023
commit 9715af77751ba24a897e2a2d8cd38b3e3e238f1f
diff --git a/src/Provider/Photon/Readme.md b/src/Provider/Photon/Readme.md
@@ -10,13 +10,46 @@
 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(new \Geocoder\Query\GeocodeQuery('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 = ReverseQuery::fromCoordinates(52.51644, 13.38890)
+    ->withData('osm_tag', 'amenity:pharmacy')
+    ->withLimit(3);
+
+$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).