Geocoder

https://geocoder-php.org/docs/
Admin
Geocoder is a PHP library that provides a powerful abstraction layer for geocoding manipulations,...
Tokens:12,404
Snippets:206
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Photon Provider

Source: https://geocoder-php.org/docs/providers/Photon

Use Composer to install the Photon provider package.

```bash
composer require geocoder-php/photon-provider
```

--------------------------------

### Install Nominatim Provider

Source: https://geocoder-php.org/docs/providers/Nominatim

Install the Nominatim provider using Composer.

```bash
composer require geocoder-php/nominatim-provider
```

--------------------------------

### Install HostIp Provider

Source: https://geocoder-php.org/docs/providers/HostIp

Use Composer to install the HostIp provider package.

```bash
composer require geocoder-php/host-ip-provider
```

--------------------------------

### Install Here Geocoder Provider

Source: https://geocoder-php.org/docs/providers/Here

Install the Here provider using Composer.

```bash
composer require geocoder-php/here-provider
```

--------------------------------

### Install IpInfo Provider

Source: https://geocoder-php.org/docs/providers/IpInfo

Use Composer to install the IpInfo provider package.

```bash
composer require geocoder-php/ip-info-provider
```

--------------------------------

### Install MaxMind Provider with Composer

Source: https://geocoder-php.org/docs/providers/MaxMind

Use this command to install the MaxMind provider using Composer. Ensure you have Composer installed and configured for your project.

```bash
composer require geocoder-php/maxmind-provider
```

--------------------------------

### Install PickPoint Provider

Source: https://geocoder-php.org/docs/providers/PickPoint

Use Composer to install the PickPoint provider package.

```bash
composer require geocoder-php/pickpoint-provider
```

--------------------------------

### Install Google Places Provider

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Install the Google Places provider using Composer.

```bash
composer require geocoder-php/google-maps-places-provider
```

--------------------------------

### Install Chain Provider

Source: https://geocoder-php.org/docs/providers/Chain

Use Composer to install the Chain provider package.

```bash
composer require geocoder-php/chain-provider
```

--------------------------------

### Install Ipstack Provider with Composer

Source: https://geocoder-php.org/docs/providers/Ipstack

Use Composer to install the Ipstack provider package.

```bash
composer require geocoder-php/ipstack-provider
```

--------------------------------

### Install LocationIQ Provider

Source: https://geocoder-php.org/docs/providers/LocationIQ

Use Composer to install the LocationIQ provider package.

```bash
composer require geocoder-php/locationiq-provider
```

--------------------------------

### Install Cache Provider

Source: https://geocoder-php.org/docs/providers/Cache

Install the cache provider package using Composer.

```bash
composer require geocoder-php/cache-provider
```

--------------------------------

### Install Algolia Places Provider

Source: https://geocoder-php.org/docs/providers/AlgoliaPlaces

Install the Algolia Places provider using Composer.

```bash
composer require geocoder-php/algolia-places-provider
```

--------------------------------

### Install Geoip Provider

Source: https://geocoder-php.org/docs/providers/Geoip

Use Composer to install the Geoip provider package.

```bash
composer require geocoder-php/geoip-provider
```

--------------------------------

### Install OpenCage Provider

Source: https://geocoder-php.org/docs/providers/OpenCage

Use Composer to install the OpenCage provider package.

```bash
composer require geocoder-php/open-cage-provider
```

--------------------------------

### Install MaxMind Binary Provider

Source: https://geocoder-php.org/docs/providers/MaxMindBinary

Use Composer to install the MaxMind Binary provider package.

```bash
composer require geocoder-php/maxmind-binary-provider
```

--------------------------------

### Install Pelias Provider

Source: https://geocoder-php.org/docs/providers/Pelias

Use Composer to install the Pelias provider package.

```bash
composer require geocoder-php/pelias-provider
```

--------------------------------

### Install TomTom Provider with Composer

Source: https://geocoder-php.org/docs/providers/TomTom

Use Composer to install the TomTom provider package.

```bash
composer require geocoder-php/tomtom-provider
```

--------------------------------

### Full Example: Geocode with Exact Address using MapQuest Provider

Source: https://geocoder-php.org/docs/providers/MapQuest

A comprehensive example demonstrating how to initialize the MapQuest provider, build an Address object, create a GeocodeQuery with specific address data, and execute the geocoding request.

```php
use Geocoder\Model\AddressBuilder;
use Geocoder\Provider\MapQuest\MapQuest;
use Geocoder\Query\GeocodeQuery;

$provider = new MapQuest($httpClient, $apiKey);

$addressBuilder = new AddressBuilder('Address provided by me');
$addressBuilder
  ->setStreetNumber(4868)
  ->setStreetName('Payne Rd');
  ->setLocality('Nashville');
  ->setSubLocality('Antioch');
  ->setAdminLevels([
      new AdminLevel(1, 'Tennessee', 'TN')
  ])
  ->setPostalCode('37013');
  ->setCountry('USA');
  ->setCountryCode('US');
$address = $addressBuilder->build();

$query = GeocodeQuery::create('dummy data');
$query = $query->withData(MapQuest::DATA_KEY_ADDRESS, $address);

$results = $provider->geocodeQuery($query);
```

--------------------------------

### Install Mapbox Provider

Source: https://geocoder-php.org/docs/providers/Mapbox

Install the Mapbox provider using Composer. A valid Access Token is required for Mapbox.

```bash
composer require geocoder-php/mapbox-provider
```

--------------------------------

### Install FreeGeoIp Provider via Composer

Source: https://geocoder-php.org/docs/providers/FreeGeoIp

Install the FreeGeoIp provider package using Composer.

```bash
composer require geocoder-php/free-geoip-provider
```

--------------------------------

### Install Geonames Provider

Source: https://geocoder-php.org/docs/providers/Geonames

Use Composer to install the Geonames provider package.

```bash
composer require geocoder-php/geonames-provider
```

--------------------------------

### Install Development Dependencies

Source: https://geocoder-php.org/docs

Installs the necessary development dependencies for running the test suite using Composer.

```bash
composer install --dev
```

--------------------------------

### Install GeoPlugin Provider

Source: https://geocoder-php.org/docs/providers/GeoPlugin

Use Composer to install the GeoPlugin provider package.

```bash
composer require geocoder-php/geo-plugin-provider
```

--------------------------------

### Install IP2Location Binary Provider

Source: https://geocoder-php.org/docs/providers/IP2LocationBinary

Use Composer to install the IP2Location Binary provider package.

```bash
composer require geocoder-php/ip2location-binary-provider
```

--------------------------------

### Install ArcGIS Online Provider

Source: https://geocoder-php.org/docs/providers/ArcGISOnline

Install the ArcGIS Online provider using Composer.

```bash
composer require geocoder-php/arcgis-online-provider
```

--------------------------------

### Install Google Maps Provider Package

Source: https://geocoder-php.org/docs/providers/GoogleMaps

Install the Google Maps provider using Composer by running the provided command in your project directory.

```bash
composer require geocoder-php/google-maps-provider
```

--------------------------------

### Install Azure Maps Provider

Source: https://geocoder-php.org/docs/providers/AzureMaps

Use Composer to install the Azure Maps provider package.

```bash
composer require geocoder-php/azure-maps-provider
```

--------------------------------

### Install MapQuest Provider

Source: https://geocoder-php.org/docs/providers/MapQuest

Install the MapQuest provider using Composer. This command adds the necessary package to your project.

```bash
composer require geocoder-php/mapquest-provider
```

--------------------------------

### Install Bing Maps Provider

Source: https://geocoder-php.org/docs/providers/BingMaps

Use Composer to install the Bing Maps provider package.

```bash
composer require geocoder-php/bing-maps-provider
```

--------------------------------

### Install IpInfoDb Provider

Source: https://geocoder-php.org/docs/providers/IpInfoDb

Use Composer to install the IpInfoDb provider for the PHP Geocoder library.

```bash
composer require geocoder-php/ip-info-db-provider
```

--------------------------------

### Install OpenRouteService Provider

Source: https://geocoder-php.org/docs/providers/OpenRouteService

Install the OpenRouteService provider using Composer. This command adds the necessary package to your project.

```bash
composer require geocoder-php/openrouteservice-provider
```

--------------------------------

### Install Google Maps Provider with Curl Client

Source: https://geocoder-php.org/docs

Use this command to install the Google Maps provider with the Curl HTTP client. A PSR7 implementation like nyholm/psr7 is required if not using Guzzle.

```bash
composer require geocoder-php/google-maps-provider php-http/curl-client nyholm/psr7
```

--------------------------------

### Install Google Maps Provider with Guzzle 7

Source: https://geocoder-php.org/docs

Use this command to install the Google Maps provider along with the Guzzle 7 HTTP client.

```bash
composer require geocoder-php/google-maps-provider guzzlehttp/guzzle
```

--------------------------------

### Install GraphHopper Provider

Source: https://geocoder-php.org/docs/providers/GraphHopper

Use Composer to install the GraphHopper provider for the PHP Geocoder library.

```bash
composer require geocoder-php/graphhopper-provider
```

--------------------------------

### Install Yandex Provider

Source: https://geocoder-php.org/docs/providers/Yandex

Install the Yandex provider using Composer. This command adds the necessary package to your project.

```bash
composer require geocoder-php/yandex-provider
```

--------------------------------

### Install GeoIP2 Provider via Composer

Source: https://geocoder-php.org/docs/providers/GeoIP2

Use Composer to install the GeoIP2 provider package for your PHP project.

```bash
composer require geocoder-php/geoip2-provider
```

--------------------------------

### Install MapTiler Provider

Source: https://geocoder-php.org/docs/providers/MapTiler

Use Composer to install the MapTiler provider package for Geocoder PHP.

```bash
composer require geocoder-php/maptiler-provider
```

--------------------------------

### Install Geocode Earth Provider

Source: https://geocoder-php.org/docs/providers/GeocodeEarth

Install the Geocode Earth provider using Composer. This command adds the necessary package to your project dependencies.

```bash
composer require geocoder-php/geocode-earth-provider
```

--------------------------------

### Install IP2Location Provider

Source: https://geocoder-php.org/docs/providers/IP2Location

Use Composer to install the IP2Location provider for the PHP Geocoder library. This command adds the necessary package to your project.

```bash
composer require geocoder-php/ip2location-provider
```

--------------------------------

### Initialize Algolia Places Provider

Source: https://geocoder-php.org/docs/providers/AlgoliaPlaces

Initialize the Algolia Places provider, demonstrating both unauthenticated and authenticated setups. Ensure to replace placeholders with your actual key and app ID for authenticated access.

```php
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;

$httpClient = new \GuzzleHttp\Client();

// Unauthenticated
$provider = new \Geocoder\Provider\AlgoliaPlaces\AlgoliaPlaces($httpClient);
// Authenticated
$provider = new \Geocoder\Provider\AlgoliaPlaces\AlgoliaPlaces($httpClient, '<your-key>', '<your-app-id>');

$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Paris')->withLocale('fr-FR'));
```

--------------------------------

### Manage State with StatefulGeocoder

Source: https://geocoder-php.org/docs

StatefulGeocoder allows maintaining state like locale, limit, or bounds across multiple queries. This example shows changing the locale and observing the effect on results.

```php
use Geocoder\Query\GeocodeQuery;

// configure your provider
$provider = // ...
$geocoder = new \Geocoder\StatefulGeocoder($provider);

$geocoder->setLocale('en');
$results = $geocoder->geocodeQuery(GeocodeQuery::create('London'));
echo $results->first()->getLocality(); // London

$geocoder->setLocale('es');
$results = $geocoder->geocodeQuery(GeocodeQuery::create('London'));
echo $results->first()->getLocality(); // Londres
```

--------------------------------

### Basic Geocoding and Reverse Geocoding Usage

Source: https://geocoder-php.org/docs

Example demonstrating how to use the StatefulGeocoder with Google Maps provider and Guzzle 7 for geocoding and reverse geocoding. Requires an API key for the provider.

```php
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;

$httpClient = new \GuzzleHttp\Client();
$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient, null, 'your-api-key');
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
$result = $geocoder->reverseQuery(ReverseQuery::fromCoordinates(...));
```

--------------------------------

### Register Multiple Providers with ProviderAggregator

Source: https://geocoder-php.org/docs

The ProviderAggregator allows registering multiple providers and selecting one to use later. This example registers GoogleMaps, GoogleMapsBusiness, Yandex, MaxMind, and ArcGISOnline.

```php
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;

$client  = new \GuzzleHttp\Client();
$geocoder = new \Geocoder\ProviderAggregator();

$geocoder->registerProviders([
    new \Geocoder\Provider\GoogleMaps\GoogleMaps($client),
    new \Geocoder\Provider\GoogleMaps\GoogleMapsBusiness($client, '<CLIENT_ID>'),
    new \Geocoder\Provider\Yandex\Yandex($client),
    new \Geocoder\Provider\MaxMind\MaxMind($client, '<MAXMIND_API_KEY>'),
    new \Geocoder\Provider\ArcGISOnline\ArcGISOnline($client),
]);

$geocoder->registerProvider(new \Geocoder\Provider\Nominatim\Nominatim($adapter, 'https://your.nominatim.server'));

$geocoder
    ->using('google_maps')
    ->geocodeQuery(GeocodeQuery::create( ... ));

$geocoder
    ->limit(10)
    ->reverseQuery(ReverseQuery::fromCoordinates($lat, $lng));
```

--------------------------------

### Use Chain Provider for Geocoding

Source: https://geocoder-php.org/docs

The Chain provider iterates over a list of providers, stopping when a result is returned. This example shows how to chain FreeGeoIp, HostIp, GoogleMaps, and BingMaps providers.

```php
use Geocoder\Query\GeocodeQuery;

$geocoder = new \Geocoder\ProviderAggregator();
$client  = new \GuzzleHttp\Client();

$chain = new \Geocoder\Provider\Chain\Chain([
    new \Geocoder\Provider\FreeGeoIp\FreeGeoIp($client),
    new \Geocoder\Provider\HostIp\HostIp($client),
    new \Geocoder\Provider\GoogleMaps\GoogleMaps($client, 'France'),
    new \Geocoder\Provider\BingMaps\BingMaps($client, '<API_KEY>'),
    // ...
]);

$geocoder->registerProvider($chain);

$result = $geocoder->geocodeQuery(GeocodeQuery::create('10 rue Gambetta, Paris, France'));
var_export($result);
```

--------------------------------

### Initialize Google Maps Provider for Business

Source: https://geocoder-php.org/docs/providers/GoogleMaps

Use the static `business` method to create a provider instance for Google Maps for Business, requiring a Client ID and optionally a private key.

```php
$httpClient = new \GuzzleHttp\Client();

// Client ID is required. Private key is optional.
$provider = \Geocoder\Provider\GoogleMaps\GoogleMaps::business($httpClient, 'your-client-id', 'your-private-key');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Use Default Nominatim Server

Source: https://geocoder-php.org/docs/providers/Nominatim

Instantiate the Nominatim provider using the default OpenStreetMap server. Ensure you have an HTTP client and user agent configured.

```php
$provider = \Geocoder\Provider\Nominatim\Nominatim::withOpenStreetMapServer($httpClient, $userAgent);
```

--------------------------------

### Initialize Google Maps Provider with API Key

Source: https://geocoder-php.org/docs/providers/GoogleMaps

Instantiate the Google Maps provider by providing an HTTP client and your API key. All requests require a valid API key.

```php
$httpClient = new \GuzzleHttp\Client();

// You must provide an API key
$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient, null, 'your-api-key');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Use Custom Nominatim Server

Source: https://geocoder-php.org/docs/providers/Nominatim

Instantiate the Nominatim provider with a custom server URL. Provide the HTTP client, server address, and user agent.

```php
$provider = new \Geocoder\Provider\Nominatim($httpClient, 'https://nominatim.openstreetmap.org', $userAgent);
```

--------------------------------

### Using Here Geocoder with API Key

Source: https://geocoder-php.org/docs/providers/Here

Instantiate the Here provider using an API key for authentication. This is the recommended method for new applications.

```php
$httpClient = new \GuzzleHttp\Client();

// You must provide an API key
$provider = \Geocoder\Provider\Here\Here::createUsingApiKey($httpClient, 'your-api-key');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Run Unit Tests

Source: https://geocoder-php.org/docs

Executes the project's unit tests using Composer.

```bash
composer test
```

--------------------------------

### Initialize and Use Azure Maps Provider

Source: https://geocoder-php.org/docs/providers/AzureMaps

Instantiate the Azure Maps provider with an HTTP client and subscription key, then use it to geocode a query.

```php
$httpClient = new \GuzzleHttp\Client();

// You must provide a subscription key
$provider = new \Geocoder\Provider\AzureMaps\AzureMaps($httpClient, 'your-subscription-key');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Yehuda Hamaccabi 15, Tel aviv'));
```

--------------------------------

### Use GeoIP2 Precision Web Service with PHP Geocoder

Source: https://geocoder-php.org/docs/providers/GeoIP2

Instantiate the GeoIP2 adapter using MaxMind's GeoIP2 Web Service client with your account ID and license key, then use it with the GeoIP2 provider to geocode an IP address.

```php
// Use the Maxmind GeoIP2 API:
$reader = new \GeoIp2\WebService\Client(<account_id>, '<licence_key>');

$adapter = new \Geocoder\Provider\GeoIP2\GeoIP2Adapter($reader);
$geocoder = new \Geocoder\Provider\GeoIP2\GeoIP2($adapter);

$address = $geocoder->geocodeQuery(\Geocoder\Query\GeocodeQuery::create('74.200.247.59'))->first();
```

--------------------------------

### Initialize and Use Yandex Geocoder

Source: https://geocoder-php.org/docs/providers/Yandex

Initialize the Yandex provider with an HTTP client and your API key. Then, use it to perform geocoding and reverse geocoding queries.

```php
$httpClient = new \GuzzleHttp\Client();
$provider = new \Geocoder\Provider\Yandex\Yandex($httpClient, null, '<your-api-key>);

$result = $geocoder->geocodeQuery(GeocodeQuery::create('ул.Ленина, 19, Минск 220030, Республика Беларусь'));
$result = $geocoder->reverseQuery(ReverseQuery::fromCoordinates(...));
```

--------------------------------

### Geocode with a token (geocodeAddresses)

Source: https://geocoder-php.org/docs/providers/ArcGISOnline

Provide a token to use the `geocodeAddresses` operation, which permits result storage. The provider is instantiated using the static `token` method.

```php
$httpClient = new \GuzzleHttp\Client();

// Your token is required.
$provider = \Geocoder\Provider\ArcGISList\ArcGISList::token($httpClient, 'your-token');

// Uses the `geocodeAddresses` operation. Result storage is permitted.
$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Using Here Geocoder with App ID and App Code

Source: https://geocoder-php.org/docs/providers/Here

Instantiate the Here provider using legacy app ID and app code for authentication. This method is for older applications.

```php
$httpClient = new \GuzzleHttp\Client();

// You must provide both the app_id and app_code
$provider = new \Geocoder\Provider\Here\Here($httpClient, 'app-id', 'app-code');

$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Fluent API for ProviderAggregator

Source: https://geocoder-php.org/docs

Demonstrates the fluent API of ProviderAggregator, allowing chaining of registration, provider selection, limit setting, and query execution.

```php
use Geocoder\Query\GeocodeQuery;

$locations = $geocoder
    ->registerProvider(new \My\Provider\Custom($adapter))
    ->using('custom')
    ->limit(10)
    ->geocodeQuery(GeocodeQuery::create( ... ));
```

--------------------------------

### Use GeoIP2 Database with PHP Geocoder

Source: https://geocoder-php.org/docs/providers/GeoIP2

Instantiate the GeoIP2 adapter using a MaxMind GeoIP2 database file (e.g., geolite2.mmdb) and then use it with the GeoIP2 provider to geocode an IP address.

```php
//Use a Maxmind GeoIP2 Database:
$reader = new \GeoIp2\Database\Reader('/path/to/geolite2.mmdb');

$adapter = new \Geocoder\Provider\GeoIP2\GeoIP2Adapter($reader);
$geocoder = new \Geocoder\Provider\GeoIP2\GeoIP2($adapter);

$address = $geocoder->geocodeQuery(\Geocoder\Query\GeocodeQuery::create('74.200.247.59'))->first();
```

--------------------------------

### Configure API Keys for Unit Tests

Source: https://geocoder-php.org/docs

Renames the default PHPUnit configuration file and uncomment lines to add API keys for various services. This is required to run all unit tests.

```xml
<php>
    <!-- <server name="IPINFODB_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="BINGMAPS_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="GEOIPS_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="MAXMIND_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="GEONAMES_USERNAME" value="YOUR_USERNAME" /> -->
    <!-- <server name="TOMTOM_MAP_KEY" value="YOUR_MAP_KEY" /> -->
    <!-- <server name="GOOGLE_GEOCODING_KEY" value="YOUR_GEOCODING_KEY" /> -->
    <!-- <server name="OPENCAGE_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="PICKPOINT_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="LOCATIONIQ_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="IPSTACK_API_KEY" value="YOUR_API_KEY" /> -->
</php>
```

--------------------------------

### Instantiate FreeGeoIp Provider

Source: https://geocoder-php.org/docs/providers/FreeGeoIp

Instantiate the FreeGeoIp provider using a Guzzle HTTP client. You can use the default endpoint or specify a custom endpoint for a self-hosted instance.

```php
$httpClient = new 
GuzzleHttp
Client();

// Use the default provider (https://freegeoip.app)
$provider = new 
Geocoder
\
Provider
\
FreeGeoIp
\
FreeGeoIp($httpClient);
// Or provide the endpoint of your instance
$provider = new 
Geocoder
\
Provider
\
FreeGeoIp
\
FreeGeoIp($httpClient, 'http://my.internal.geocoder/json/%s');
```

--------------------------------

### Create GeocodeQuery with Address String and Object

Source: https://geocoder-php.org/docs/providers/MapQuest

Create a GeocodeQuery with both an address string and an Address object. This ensures compatibility with other providers while still using the specific MapQuest data format.

```php
$query = GeocodeQuery::create($addressAsString);
$query = $query->withData(MapQuest::DATA_KEY_ADDRESS, $address);
```

--------------------------------

### Usage of ProviderCache

Source: https://geocoder-php.org/docs/providers/Cache

Demonstrates how to use the ProviderCache with a PSR-6 cache pool and set a cache expiry time. The first geocode query will fetch data from the API, while subsequent identical queries will be served from the cache.

```php
$httpClient = new \GuzzleHttp\Client();
$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient);

$psr6Cache = new ArrayCachePool(); // Requires `cache/array-adapter` package

$cachedProvider = new \Geocoder\Provider\Cache\ProviderCache(
    $provider, // Provider to cache
    $psr6Cache, // PSR-6 compatible cache
    600 // Cache expiry, in seconds
);

$geocoder = new \Geocoder\StatefulGeocoder($cachedProvider, 'en');

// Will come from Google Maps API
$result1 = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
// Will come from the cache
$result2 = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Format Location as String

Source: https://geocoder-php.org/docs

Formats a Location object into a human-readable string using custom placeholders. The available placeholders include street number, name, city, zipcode, country, and more.

```php
// $location is an instance of Location
$formatter = new \Geocoder\Formatter\StringFormatter();

$formatter->format($location, '%S %n, %z %L');
// 'Badenerstrasse 120, 8001 Zuerich'

$formatter->format($location, '<p>%S %n, %z %L</p>');
// '<p>Badenerstrasse 120, 8001 Zuerich</p>'
```

--------------------------------

### Create GeocodeQuery with Address Object

Source: https://geocoder-php.org/docs/providers/MapQuest

Create a GeocodeQuery using an Address object. This method utilizes MapQuest's 5-box Input format for more specific geocoding.

```php
$query = GeocodeQuery::create('foobar');
$query = $query->withData(MapQuest::DATA_KEY_ADDRESS, $address);
```

--------------------------------

### Dump Location to GPX Format

Source: https://geocoder-php.org/docs

Converts a Location object into a GPX compliant XML string. Ensure you have a Location object instance before using this dumper.

```php
$dumper = new \Geocoder\Dumper\Gpx();
$strGpx = $dumper->dump($location);

echo $strGpx;
```

```xml
<gpx
    version="1.0"
    creator="Geocoder" version="1.0.1-dev"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.topografix.com/GPX/1/0"
    xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
    <bounds minlat="2.388911" minlon="48.863151" maxlat="2.388911" maxlon="48.863151"/>
    <wpt lat="48.8631507" lon="2.3889114">
        <name><![CDATA[Paris]]></name>
        <type><![CDATA[Address]]></type>
    </wpt>
</gpx>
```

--------------------------------

### Geocode without a token (findAddressCandidates)

Source: https://geocoder-php.org/docs/providers/ArcGISOnline

Use this when result storage is prohibited. The `geocodeQuery` method automatically selects the `findAddressCandidates` operation if no token is provided.

```php
$httpClient = new \GuzzleHttp\Client();

$provider = new \Geocoder\Provider\ArcGISList\ArcGISList($httpClient);

// Uses the `findAddressCandidates` operation. Result storage is prohibited.
$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
```

--------------------------------

### Geocode Query: Find Mode

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Use the default 'Find' mode for geocoding with an exact place name. This mode is strict and typically returns a single result.

```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('Museum of Contemporary Art Australia')
);
```

--------------------------------

### Geocoding - Search Mode

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

This mode performs a search based on input text, offering more flexibility but potentially higher billing due to returning all fields.

```APIDOC
## Geocoding - Search Mode

### Description
This mode performs a search based on the input text. It is more forgiving than 'find' mode but results contain all fields and are billed at the highest rate.

### Method
`geocodeQuery`

### Parameters
- `query` (GeocodeQuery): An object containing the query details.
  - `text` (string) - Required - The text to search for.
  - `data` (array) - Optional - Additional data for the query.
    - `mode` (string) - Optional - Set to `GoogleMapsPlaces::GEOCODE_MODE_SEARCH` for search mode.
    - `location` (string) - Optional - Coordinates to search around (e.g., '-32.926642, 151.783026').
    - `components` (string) - Optional - Country filtering (e.g., 'country:FR').

### Request Example (Basic Search)
```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('art museum sydney')
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
);
```

### Request Example (Search Around Location)
```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('bar')
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
        ->withData('location', '-32.926642, 151.783026')
);
```

### Request Example (Country Filter)
```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('montpellier')
        ->withData('components', 'country:FR');
);
```

### Response
- `results` (array): An array of geocoding results.
```

--------------------------------

### Geocode Query: Search Mode

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Utilize 'Search' mode for geocoding based on input text. This mode is more flexible but may incur higher billing rates due to returning all fields.

```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('art museum sydney')
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
);
```

--------------------------------

### Geocoding - Find Mode

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

This is the default geocoding mode, requiring an exact place name and typically returning a single result.

```APIDOC
## Geocoding - Find Mode

### Description
This is the default mode for geocoding. It requires an exact place name and is generally forgiving, returning a single result.

### Method
`geocodeQuery`

### Parameters
- `query` (GeocodeQuery): An object containing the query details.
  - `text` (string) - Required - The exact name of the place to geocode.

### Request Example
```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('Museum of Contemporary Art Australia')
);
```

### Response
- `results` (array): An array of geocoding results.
```

--------------------------------

### Reverse Geocoding - Nearby Mode (Prominence)

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Uses Google Place API Nearby search with 'prominence' ranking, requiring a 'radius'.

```APIDOC
## Reverse Geocoding - Nearby Mode (Prominence)

### Description
This mode uses the Google Place API Nearby search, ranking results by prominence. It requires a `radius` parameter and returns `vicinity`.

### Method
`reverseQuery`

### Parameters
- `query` (ReverseQuery): An object containing the query details.
  - `coordinates` (array) - Required - Latitude and longitude coordinates (e.g., `[-33.892674, 151.200727]`).
  - `data` (array) - Optional - Additional data for the query.
    - `mode` (string) - Optional - Set to `GoogleMapsPlaces::GEOCODE_MODE_NEARBY`.
    - `rankby` (string) - Optional - Set to `prominence` (default for nearby mode).
    - `radius` (integer) - Required - The radius in meters to search within.

### Request Example
```php
$results = $provider->reverseQuery(
    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_NEARBY)
        ->withData('radius', 500)
);
$vicinity = $results->first()->getVicinity();
```

### Response
- `results` (array): An array of reverse geocoding results.
```

--------------------------------

### Reverse Geocoding - Nearby Mode (Distance)

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Uses Google Place API Nearby search with 'distance' ranking, requiring a 'type', 'keyword', or 'name'.

```APIDOC
## Reverse Geocoding - Nearby Mode (Distance)

### Description
This mode uses the Google Place API Nearby search, ranking results by distance. It requires a `type`, `keyword`, or `name` parameter and returns `vicinity`.

### Method
`reverseQuery`

### Parameters
- `query` (ReverseQuery): An object containing the query details.
  - `coordinates` (array) - Required - Latitude and longitude coordinates (e.g., `[-33.892674, 151.200727]`).
  - `data` (array) - Optional - Additional data for the query.
    - `mode` (string) - Optional - Set to `GoogleMapsPlaces::GEOCODE_MODE_NEARBY`.
    - `rankby` (string) - Optional - Set to `distance`.
    - `keyword` (string) - Required - A keyword or name to search for (e.g., 'bar').
    - `type` (string) - Required - The type of place to search for (e.g., 'bar').
    - `name` (string) - Required - The name of the place to search for (e.g., 'bar').

### Request Example
```php
$results = $provider->reverseQuery(
    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_NEARBY)
        ->withData('rankby','distance')
        ->withData('keyword', 'bar')
);
```

### Response
- `results` (array): An array of reverse geocoding results.
```

--------------------------------

### Reverse Geocoding: Nearby Mode with Distance and Keyword

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Reverse geocode coordinates using 'Nearby' mode, ranking results by distance. This requires a 'keyword' (or 'type'/'name') and uses the Places API Nearby Search.

```php
$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
    );
```

--------------------------------

### Reverse Geocoding: Nearby Mode with Radius

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Perform reverse geocoding using 'Nearby' mode with a specified radius. This uses the Places API Nearby Search and returns 'vicinity'. Requires 'radius' in meters.

```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();
```

--------------------------------

### Profile Geocoding Calls with TimedGeocoder

Source: https://geocoder-php.org/docs

The TimedGeocoder profiles geocode and reverse calls using Symfony's Stopwatch component, allowing you to measure time and memory usage for each call.

```php
use Geocoder\Query\GeocodeQuery;

// configure your provider
$provider = // ...

$stopwatch = new \Symfony\Component\Stopwatch\Stopwatch();
$geocoder = new \Geocoder\TimedGeocoder($provider, $stopwatch);

$geocoder->geocodeQuery(GeocodeQuery::create('Paris, France'));

// Now you can debug your application
```

--------------------------------

### Reverse Geocoding - Search Mode

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Performs reverse geocoding using Google Place API Text search, requiring a 'type' parameter.

```APIDOC
## Reverse Geocoding - Search Mode

### Description
This mode uses the Google Place API Text search for reverse geocoding. It requires a `type` parameter and returns `formatted_address`.

### Method
`reverseQuery`

### Parameters
- `query` (ReverseQuery): An object containing the query details.
  - `coordinates` (array) - Required - Latitude and longitude coordinates (e.g., `[-33.892674, 151.200727]`).
  - `data` (array) - Optional - Additional data for the query.
    - `mode` (string) - Optional - Set to `GoogleMapsPlaces::GEOCODE_MODE_SEARCH` (default).
    - `type` (string) - Required - The type of place to search for (e.g., 'bar').

### Request Example
```php
$results = $provider->reverseQuery(
    ReverseQuery::fromCoordinates(-33.892674, 151.200727)
        ->withData('type', 'bar')
);
$address = $results->first()->getFormattedAddress();
```

### Response
- `results` (array): An array of reverse geocoding results.
```

--------------------------------

### Reverse Geocoding: Search Mode with Type

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Reverse geocode coordinates using 'Search' mode, requiring a 'type' parameter. This uses the Places API Text Search and returns 'formatted_address'.

```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();
```

--------------------------------

### Geocode Query: Search Mode Around Location

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Perform a 'Search' mode geocoding query for a specific type of place around a given geographical location.

```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('bar')
        ->withData('mode', GoogleMapsPlaces::GEOCODE_MODE_SEARCH)
        ->withData('location', '-32.926642, 151.783026')
);
```

--------------------------------

### Geocode Query: Country Component Restriction

Source: https://geocoder-php.org/docs/providers/GoogleMapsPlaces

Geocode a location while restricting results to a specific country using the 'components' data. The country can be specified by name or ISO 3166-1 code.

```php
$results = $provider->geocodeQuery(
    GeocodeQuery::create('montpellier')
        ->withData('components', 'country:FR');
);
```
Tokens:
Raw