Important: You are browsing the documentation of Geocoder 4.x (not released yet).
Documentation for version 3.x is available here: Geocoder 3.x documentation.
Documentation for version 2.x is available here: Geocoder 2.x documentation.
Geocoder is a PHP library which helps you build geo-aware applications by providing a powerful abstraction layer for geocoding manipulations.
To install a Geocoder there are two things you need to know:
- What Geocoder provider you want to use
- What HTTP client/adapter you want to use.
Since 4.0 we do not include providers by default. You need to select a geocoder provider. You will see a list of providers at Packagist
In order to talk to geocoding APIs, you need HTTP adapters. While it was part of the library in Geocoder before, Geocoder 4.x and upper now relies on HTTPlug which defines how HTTP message should be sent and received. You can use any library to send HTTP messages that implements php-http/client-implementation.
Here is a list of all officially supported clients and adapters by HTTPlug: http://docs.php-http.org/en/latest/clients.html
Read more about HTTPlug in their docs.
To install Google Maps geocoder with Guzzle 6 you may run the following command:
$ composer require geocoder-php/google-maps-provider:@beta php-http/guzzle6-adapter php-http/message geocoder-php/common-http:@beta willdurand/geocoder:@beta
We have a small cookbook where you can find examples on common use cases:
In the code snippet below we use GoogleMaps and Guzzle6.
$adapter = new \Http\Adapter\Guzzle6\Client();
$provider = new \Geocoder\Provider\GoogleMaps($adapter);
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');
$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
$result = $geocoder->reverseQuery(ReverseQuery::fromCoordinates(...));The Provider interface has three methods:
geocodeQuery(GeocodeQuery $query):AddressCollectionreverseQuery(ReverseQuery $query):AddressCollectiongetName():string
The Geocoder interface extends the Provider interface and exposes two additional methods. They will
make migration from 3.x smoother.
geocode($streetOrIpAddress)reverse($latitude, $longitude)
Providers perform the geocoding black magic for you (talking to the APIs, fetching results, dealing with errors, etc.) and are highly configurable.
| Provider | Package | Features | Stats |
|---|---|---|---|
| ArcGIS Online | geocoder-php/arcgis-online-provider |
address, reverse Website |
|
| Bing Maps | geocoder-php/bing-maps-provider |
address, reverse Website |
|
| Chain | geocoder-php/chain-provider |
Interates over multiple providers | |
| FreeGeoIp | geocoder-php/free-geoip-provider |
IPv4, IPv6 Website |
|
| GeoIPs | geocoder-php/geoip-provider |
IPv4, local Website |
|
| GeoIP2 | geocoder-php/geoip2-provider |
IPv4 Website |
|
| GeoIPs | geocoder-php/geoips-provider |
IPv4 |
|
| Geonames | geocoder-php/geonames-provider |
address, reverse Website |
|
| GeoPlugin | geocoder-php/geo-plugin-provider |
IPv4, IPv6 Website |
|
| Google Maps Google Maps for business |
geocoder-php/google-maps-provider |
address, reverse Website |
|
| HostIp | geocoder-php/host-ip-provider |
IPv4 Website |
|
| IpInfoDB | geocoder-php/ip-info-db-provider |
IPv4 Website |
|
| MapQuest | geocoder-php/mapquest-provider |
address, reverse Website |
|
| Mapzen | geocoder-php/mapzen-provider |
address, reverse Website |
|
| MaxMind | geocoder-php/maxmind-provider |
IPv4, IPv6 Website |
|
| MaxMind Binary | geocoder-php/maxmind-binary-provider |
IPv4, IPv6 Website |
|
| Nominatim (OpenStreetMap) |
geocoder-php/nominatim-provider |
address, reverse, IPv4 Website |
|
| OpenCage | geocoder-php/open-cage-provider |
address, reverse Website |
|
| TomTom | geocoder-php/tomtom-provider |
address, reverse Website |
|
| Yandex | geocoder-php/yandex-provider |
address, reverse Website |
The Chain provider is a special provider that takes a list of providers and
iterates over this list to get information. Note that it stops its iteration
when a provider returns a result. The result is returned by GoogleMaps because
FreeGeoIp and HostIp cannot geocode street addresses. BingMaps is ignored.
$geocoder = new \Geocoder\ProviderAggregator();
$adapter = new \Http\Adapter\Guzzle6\Client();
$chain = new \Geocoder\Provider\Chain([
new \Geocoder\Provider\FreeGeoIp($adapter),
new \Geocoder\Provider\HostIp($adapter),
new \Geocoder\Provider\GoogleMaps($adapter, 'France'),
new \Geocoder\Provider\BingMaps($adapter, '<API_KEY>'),
// ...
]);
$geocoder->registerProvider($chain);
$result = $geocoder->geocodeQuery(GeocodeQuery::create('10 rue Gambetta, Paris, France'));
var_export($result);Everything is ok, enjoy!
The ProviderAggregator is used to register several providers so that you can
decide which provider to use later on.
$adapter = new \Http\Adapter\Guzzle6\Client();
$geocoder = new \Geocoder\ProviderAggregator();
$geocoder->registerProviders([
new \Geocoder\Provider\GoogleMaps($adapter),
new \Geocoder\Provider\GoogleMapsBusiness($adapter, '<CLIENT_ID>'),
new \Geocoder\Provider\Yandex($adapter),
new \Geocoder\Provider\MaxMind($adapter, '<MAXMIND_API_KEY>'),
new \Geocoder\Provider\ArcGISOnline($adapter),
]);
$geocoder->registerProvider(new \Geocoder\Provider\Nominatim($adapter, 'https://your.nominatim.server'));
$geocoder
->using('google_maps')
->geocodeQuery(GeocodeQuery::create( ... ));
$geocoder
->limit(10)
->reverseQuery(ReverseQuery::fromCoordinates($lat, $lng));The ProviderAggregator's API is fluent, meaning you can write:
$locations = $geocoder
->registerProvider(new \My\Provider\Custom($adapter))
->using('custom')
->limit(10)
->geocodeQuery(GeocodeQuery::create( ... ));The using() method allows you to choose the provider to use by its name.
When you deal with multiple providers, you may want to choose one of them. The
default behavior is to use the first one but it can be annoying.
The limit() method allows you to configure the maximum number of results being
returned. Depending on the provider you may not get as many results as expected,
it is a maximum limit, not the expected number of results.
The TimedGeocoder class profiles each geocode and reverse call. So you can
easily figure out how many time/memory was spent for each geocoder/reverse call.
// 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 applicationWe use the symfony/stopwatch component under the hood. Which means, if you use the Symfony framework the geocoder calls will appear in your timeline section in the Web Profiler.
The StatefulGeocoder class is great when you want your Geocoder to hold state. Say you want to configure locale,
limit or bounds in runtime. The StatefulGeocoder will append these values on each query.
// 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(); // LondresGeocoder provides dumpers that aim to transform a Location object in
standard formats.
The GPS eXchange format is designed to share geolocated data like point of
interests, tracks, ways, but also coordinates. Geocoder provides a dumper to
convert a Location object in an GPX compliant format.
Assuming we got a $location object as seen previously:
$dumper = new \Geocoder\Dumper\Gpx();
$strGpx = $dumper->dump($location);
echo $strGpx;It will display:
<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>GeoJSON is a format for encoding a variety of geographic data structures.
Simple PHP array format for using with your own encoders.
Keyhole Markup Language is an XML notation for expressing geographic annotation and visualization within Internet-based, two-dimensional maps and three-dimensional Earth browsers.
The Well-Known Binary (WKB) representation for geometric values is defined by the OpenGIS specification.
Well-known text (WKT) is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects and transformations between spatial reference systems.
A common use case is to print geocoded data. Thanks to the StringFormatter
class, it's simple to format a Location object as a string:
// $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>'Here is the mapping:
- Street Number:
%n - Street Name:
%S - City:
%L - City District:
%D - Zipcode:
%z - Admin Level Name:
%A1,%A2,%A3,%A4,%A5 - Admin Level Code:
%a1,%a2,%a3,%a4,%a5 - Country:
%C - Country Code:
%c - Timezone:
%T
Geocoder follows Semantic Versioning.
As of December 2014, branch 1.7 is not officially supported anymore, meaning
major version 1 reached end of life. Last version is:
1.7.1.
As of December 2014, version 2.x is in a feature frozen state. All new features should be contributed to version 3.0 and upper. Last version is: 2.8.1.
Major version 2 will reach end of life on December 2015.
Version 3.x is the current major stable version of Geocoder.
The next version is 4.0 which is currently in beta.
See CONTRIBUTING file.
In order to run the test suite, install the development dependencies:
$ composer install --dev
Then, run the following command:
$ composer test
You'll obtain some skipped unit tests due to the need of API keys.
Rename the phpunit.xml.dist file to phpunit.xml, then uncomment the
following lines and add your own API keys:
<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" /> -->
</php>You're done.
- William Durand [email protected]
- Tobias Nyholm [email protected]
- All contributors
As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at http://contributor-covenant.org/version/1/0/0/
Geocoder is released under the MIT License. See the bundled LICENSE file for details.