Repository files navigation

Important: You are browsing the documentation of Geocoder4.x.

Documentation for version3.x is available here:Geocoder 3.xdocumentation.

Documentation for version2.x is available here:Geocoder 2.xdocumentation.

Geocoder is a PHP library which helps you build geo-aware applications byproviding a powerful abstraction layer for geocoding manipulations.

• Installation
• Cookbook
• Usage
• Providers
• Special Geocoders and Providers
• Dumpers
• Formatters
• Versioning

To install a Geocoder there are two things you need to know:

1. WhatGeocoder provider you want to use
2. WhatHTTP client/adapter you want to use.

Since 4.0 we do not include providers by default. You need to select ageocoder provider. You will see a list ofprovidersat Packagist

In order to talk to geocoding APIs, you need HTTP adapters. While it was part ofthe library in Geocoder before, Geocoder 4.x and upper now relies on HTTPlugwhich defines how HTTP message should be sent and received. You can use any library to send HTTP messagesthat implementsphp-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 intheir docs.

To install Google Maps geocoder with Guzzle 6 you may run the following command:

$ composer require geocoder-php/google-maps-provider php-http/guzzle6-adapter

Or using the curl client (you'll need to provide a PSR7 implementation such asnyholm/psr7 if not using guzzle)

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

If you are using a framework then you may be interested in our excellent framework integrations.

Framework	Package	Stats
Laravel	geocoder-php/GeocoderLaravel
Symfony	geocoder-php/BazingaGeocoderBundle

We have a small cookbook where you can find examples on common use cases:

• Caching responses
• Configuring the HTTP client
• Rate limiting API requests

In the code snippet below we use GoogleMaps and Guzzle6.

useGeocoder\Query\GeocodeQuery;useGeocoder\Query\ReverseQuery;$httpClient =new \Http\Adapter\Guzzle6\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(...));

TheProvider interface has three methods:

• geocodeQuery(GeocodeQuery $query):AddressCollection
• reverseQuery(ReverseQuery $query):AddressCollection
• getName():string

TheGeocoder interface extends theProvider interface and exposes two additional methods. They willmake 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
Cache	geocoder-php/cache-provider	Wraps a provider and cached the results
Chain	geocoder-php/chain-provider	Iterates over multiple providers

Provider	Package	Features	Stats
Algolia Places	geocoder-php/algolia-places-provider	address Website
ArcGIS Online	geocoder-php/arcgis-online-provider	address, reverse Website
Bing Maps	geocoder-php/bing-maps-provider	address, reverse Website
Geocode Earth	geocoder-php/geocode-earth-provider	address, reverse Website
Geonames	geocoder-php/geonames-provider	address, reverse Website
Google Maps Google Maps for business	geocoder-php/google-maps-provider	address, reverse Website
Google Maps Places	geocoder-php/google-maps-places-provider	address, reverse Website
GraphHopper	geocoder-php/graphhopper-provider	address, reverse Website
Here	geocoder-php/here-provider	address, reverse Website
LocationIQ	geocoder-php/locationiq-provider	address, reverse Website
Mapbox	geocoder-php/mapbox-provider	address, reverse Website
MapQuest	geocoder-php/mapquest-provider	address, reverse Website
Nominatim (OpenStreetMap)	geocoder-php/nominatim-provider	address, reverse Website
OpenCage	geocoder-php/open-cage-provider	address, reverse Website
OpenRouteService	geocoder-php/openrouteservice-provider	address, reverse Website
Pelias	geocoder-php/pelias-provider	address, reverse Website
Photon	geocoder-php/photon-provider	address, reverse Website
PickPoint	geocoder-php/pickpoint-provider	address, reverse Website
TomTom	geocoder-php/tomtom-provider	address, reverse Website
Yandex	geocoder-php/yandex-provider	address, reverse Website

Region	Provider	Package	Features	Stats
🇧🇪	bpost (third-party package*)	geo6/geocoder-php-bpost-provider	address Website
🇧🇪	GeoPunt (third-party package*)	geo6/geocoder-php-geopunt-provider	address, reverse Website
🇧🇪	Service Public de Wallonie (third-party package*)	geo6/geocoder-php-spw-provider	address, reverse Website
🇧🇪	UrbIS (third-party package*)	geo6/geocoder-php-urbis-provider	address, reverse Website
🇫🇷	Addok (third-party package*)	geo6/geocoder-php-addok-provider	address, reverse Website
🇱🇺	Geoportail.lu (third-party package*)	frantzmicccoli/geocoder-php-geoportail-lu	address, reverse Website
🇳🇱	Nationaal Georegister (third-party package*)	swisnl/geocoder-php-nationaal-georegister-provider	address, reverse Website

*Third-party package: Those providers are not official, i.e. not from the Geocoder core team.

Provider	Package	Features	Stats
FreeGeoIp	geocoder-php/free-geoip-provider	IPv4, IPv6 Website
GeoIP	geocoder-php/geoip-provider	IPv4, local Website
GeoIP2	geocoder-php/geoip2-provider	IPv4 Website
GeoPlugin	geocoder-php/geo-plugin-provider	IPv4, IPv6 Website
HostIp	geocoder-php/host-ip-provider	IPv4 Website
IP2Location	geocoder-php/ip2location-provider	IPv4, IPv6 Website
IP2Location Binary	geocoder-php/ip2location-binary-provider	IPv4, IPv6 Website
IpInfo	geocoder-php/ip-info-provider	IPv4, IPv6 Website
IpInfoDB	geocoder-php/ip-info-db-provider	IPv4 Website
ipstack	geocoder-php/ipstack-provider	IPv4, IPv6 Website
MaxMind	geocoder-php/maxmind-provider	IPv4, IPv6 Website
MaxMind Binary	geocoder-php/maxmind-binary-provider	IPv4, IPv6 Website

There are two "abstract" or "base" packages that most providers depend on.

Name	Package	Features	Stats
PHP common	willdurand/geocoder	Models, interfaces, exceptions etc
HTTP common	geocoder-php/common-http	AbstractHttpProvider, HTTPlug
Plugin	geocoder-php/plugin	Plugin provider

TheChain provider is a special provider that takes a list of providers anditerates over this list to get information. Note that itstops its iterationwhen a provider returns a result. The result is returned byGoogleMaps becauseFreeGeoIp andHostIp cannot geocode street addresses.BingMaps is ignored.

useGeocoder\Query\GeocodeQuery;$geocoder =new \Geocoder\ProviderAggregator();$adapter  =new \Http\Adapter\Guzzle6\Client();$chain =new \Geocoder\Provider\Chain\Chain([new \Geocoder\Provider\FreeGeoIp\FreeGeoIp($adapter),new \Geocoder\Provider\HostIp\HostIp($adapter),new \Geocoder\Provider\GoogleMaps\GoogleMaps($adapter,'France'),new \Geocoder\Provider\BingMaps\BingMaps($adapter,'<API_KEY>'),// ...]);$geocoder->registerProvider($chain);$result =$geocoder->geocodeQuery(GeocodeQuery::create('10 rue Gambetta, Paris, France'));var_export($result);

Everything is ok, enjoy!

TheProviderAggregator is used to register several providers so that you candecide which provider to use later on.

useGeocoder\Query\GeocodeQuery;useGeocoder\Query\ReverseQuery;$adapter  =new \Http\Adapter\Guzzle6\Client();$geocoder =new \Geocoder\ProviderAggregator();$geocoder->registerProviders([new \Geocoder\Provider\GoogleMaps\GoogleMaps($adapter),new \Geocoder\Provider\GoogleMaps\GoogleMapsBusiness($adapter,'<CLIENT_ID>'),new \Geocoder\Provider\Yandex\Yandex($adapter),new \Geocoder\Provider\MaxMind\MaxMind($adapter,'<MAXMIND_API_KEY>'),new \Geocoder\Provider\ArcGISOnline\ArcGISOnline($adapter),]);$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));

TheProviderAggregator's API is fluent, meaning you can write:

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

Theusing() method allows you to choose theprovider to use by its name.When you deal with multiple providers, you may want to choose one of them. Thedefault behavior is to use the first one but it can be annoying.

Thelimit() method allows you to configure the maximum number of results beingreturned. Depending on the provider you may not get as many results as expected,it is a maximum limit, not the expected number of results.

TheTimedGeocoder class profiles eachgeocode andreverse call. So you caneasily figure out how many time/memory was spent for each geocoder/reverse call.

useGeocoder\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

We use thesymfony/stopwatchcomponent under the hood. Which means, if you use the Symfony framework thegeocoder calls will appear in your timeline section in the Web Profiler.

TheStatefulGeocoder class is great when you want your Geocoder to hold state. Say you want to configure locale,limit or bounds in runtime. TheStatefulGeocoder will append these values on each query.

useGeocoder\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

Geocoder provides dumpers that aim to transform aLocation object instandard formats.

TheGPS eXchange format is designed to share geolocated data like point ofinterests, tracks, ways, but also coordinates.Geocoder provides a dumper toconvert aLocation 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:

<gpxversion="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">    <boundsminlat="2.388911"minlon="48.863151"maxlat="2.388911"maxlon="48.863151"/>    <wptlat="48.8631507"lon="2.3889114">        <name><![CDATA[Paris]]></name>        <type><![CDATA[Address]]></type>    </wpt></gpx>

GeoJSON is a format for encoding a variety of geographicdata structures.

Simple PHP array format for using with your own encoders.

Keyhole Markup Languageis an XML notation for expressing geographic annotation and visualization withinInternet-based, two-dimensional maps and three-dimensional Earth browsers.

The Well-Known Binary (WKB) representation for geometric values is defined bythe OpenGIS specification.

Well-known text (WKT) is a text markup language for representing vector geometryobjects on a map, spatial reference systems of spatial objects andtransformations between spatial reference systems.

A common use case is to print geocoded data. Thanks to theStringFormatterclass, it's simple to format aLocation 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 (Locality):%L
• City District (Sub-Locality):%D
• Zipcode (Postal Code):%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 followsSemantic Versioning.

As of December 2014, branch1.7 is not officially supported anymore, meaningmajor version1 reached end of life. Last version is:1.7.1.

As of December 2014, version2.xis in afeature frozen state. All new features should be contributed to version 3.0and upper. Last version is:2.8.1.

Major version2 will reachend of life on December 2015.

As of January 2017, version3.xis in afeature frozen state. All new features should be contributed to version 4.0and upper. Last version is:3.3.2.

Major version3 will reachend of life on October 2017.

Version4.x is the current major stable version of Geocoder.

There is no new major version planned at this time.

SeeCONTRIBUTING 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 someskipped unit tests due to the need of API keys.

Rename thephpunit.xml.dist file tophpunit.xml, then uncomment thefollowing 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" />--><!-- <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>

You're done.

• William Durandwill+git@drnd.me
• Tobias Nyholmtobias.nyholm@gmail.com
• All contributors

Geocoder is released under the MIT License. See the bundled LICENSE file for details.