Shell geocoder PHP
Need help with Geocoder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.
geocoder-php

Description

The most featured Geocoder library written in PHP.

3.7K Stars 489 Forks MIT License 1.4K Commits 36 Opened issues

Services available

Need anything else?

Geocoder

Build Status Software License

Important: You are browsing the documentation of Geocoder 4.x.

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.

Installation

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

1) What Geocoder provider you want to use 2) What HTTP client/adapter you want to use.

Geocoder providers

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

HTTP Clients

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.

Summary (Just give me the command)

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 as

nyholm/psr7
if not using guzzle)
$ composer require geocoder-php/google-maps-provider php-http/curl-client nyholm/psr7

Framework integration

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

Framework

Package Stats
Laravel

geocoder-php/GeocoderLaravel
GitHub release Packagist
Symfony
geocoder-php/BazingaGeocoderBundle
Latest Stable Version Total Downloads

Cookbook

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

Usage

In the code snippet below we use GoogleMaps and Guzzle6.

use Geocoder\Query\GeocodeQuery;
use Geocoder\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(...));

The

Provider
interface has three methods:
  • geocodeQuery(GeocodeQuery $query):AddressCollection
  • reverseQuery(ReverseQuery $query):AddressCollection
  • getName():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

Providers perform the geocoding black magic for you (talking to the APIs, fetching results, dealing with errors, etc.) and are highly configurable.

Special providers

Provider

Package Features Stats
Cache

geocoder-php/cache-provider
Wraps a provider and cached the results Latest Stable Version
Total Downloads
Chain
geocoder-php/chain-provider
Iterates over multiple providers Latest Stable Version
Total Downloads

Address

World

Provider

Package Features Stats
Algolia Places

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

Local

Region

Provider Package Features Stats
:belgium: bpost (third-party package)
geo6/geocoder-php-bpost-provider
address
Website
Latest Stable Version
Total Downloads
:belgium: GeoPunt (third-party package)

geo6/geocoder-php-geopunt-provider
address, reverse
Website
Latest Stable Version
Total Downloads
:belgium: Service Public de Wallonie (third-party package)
geo6/geocoder-php-spw-provider
address, reverse
Website
Latest Stable Version
Total Downloads
:belgium: UrbIS (third-party package)
geo6/geocoder-php-urbis-provider
address, reverse
Website
Latest Stable Version
Total Downloads
:fr: Addok (third-party package)
geo6/geocoder-php-addok-provider
address, reverse
Website
Latest Stable Version
Total Downloads
:luxembourg: Geoportail.lu (third-party package)
frantzmicccoli/geocoder-php-geoportail-lu
address, reverse
Website
Latest Stable Version
Total Downloads
:netherlands: Nationaal Georegister (third-party package*)
swisnl/geocoder-php-nationaal-georegister-provider
address, reverse
Website
Latest Stable Version
Total Downloads

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

IP

Provider

Package Features Stats
FreeGeoIp

geocoder-php/free-geoip-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
GeoIP
geocoder-php/geoip-provider
IPv4, local
Website
Latest Stable Version
Total Downloads
GeoIP2
geocoder-php/geoip2-provider
IPv4
Website
Latest Stable Version
Total Downloads
GeoPlugin
geocoder-php/geo-plugin-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
HostIp
geocoder-php/host-ip-provider
IPv4
Website
Latest Stable Version
Total Downloads
IP2Location
geocoder-php/ip2location-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
IP2Location Binary
geocoder-php/ip2location-binary-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
IpInfo
geocoder-php/ip-info-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
IpInfoDB
geocoder-php/ip-info-db-provider
IPv4
Website
Latest Stable Version
Total Downloads
ipstack
geocoder-php/ipstack-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
MaxMind
geocoder-php/maxmind-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads
MaxMind Binary
geocoder-php/maxmind-binary-provider
IPv4, IPv6
Website
Latest Stable Version
Total Downloads

Other packages

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

Name

Package Features Stats
PHP common

willdurand/geocoder
Models, interfaces, exceptions etc Latest Stable Version
Total Downloads
HTTP common
geocoder-php/common-http
AbstractHttpProvider
, HTTPlug
Latest Stable Version
Total Downloads
Plugin
geocoder-php/plugin
Plugin provider Latest Stable Version
Total Downloads

Special Geocoders and Providers

The Chain Provider

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.
use Geocoder\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, ''), // ... ]);

$geocoder->registerProvider($chain);

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

Everything is ok, enjoy!

The ProviderAggregator

The

ProviderAggregator
is used to register several providers so that you can decide which provider to use later on.
use Geocoder\Query\GeocodeQuery;
use Geocoder\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, ''), new \Geocoder\Provider\Yandex\Yandex($adapter), new \Geocoder\Provider\MaxMind\MaxMind($adapter, ''), 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));

The

ProviderAggregator
's API is fluent, meaning you can write:
use Geocoder\Query\GeocodeQuery;

$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.

TimedGeocoder

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.
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

We 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.

StatefulGeocoder

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.
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

Dumpers

Geocoder provides dumpers that aim to transform a

Location
object in standard formats.

GPS eXchange Format (GPX)

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:

    
    
        
        
    

GeoJSON

GeoJSON is a format for encoding a variety of geographic data structures.

GeoArray

Simple PHP array format for using with your own encoders.

Keyhole Markup Language (KML)

Keyhole Markup Language is an XML notation for expressing geographic annotation and visualization within Internet-based, two-dimensional maps and three-dimensional Earth browsers.

Well-Known Binary (WKB)

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

Well-Known Text (WKT)

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.

Formatters

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, '

%S %n, %z %L

'); // '

Badenerstrasse 120, 8001 Zuerich

'

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

Versioning

Geocoder follows Semantic Versioning.

End Of Life

1.x

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.

2.x

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.

3.x

As of January 2017, version 3.x is in a feature frozen state. All new features should be contributed to version 4.0 and upper. Last version is: 3.3.2.

Major version

3
will reach end of life on October 2017.

Stable Version

Version

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

Next version

There is no new major version planned at this time.

Contributing

See

CONTRIBUTING
file.

Unit Tests

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:
    
    
    
    
    
    
    
    
    
    
    

You're done.

Credits

License

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.