Geocoder is a library which helps you build geo-aware applications. It provides an abstraction layer for geocoding manipulations.
The library is split in two parts: HttpAdapter
and Provider
and is really extensible.
HttpAdapters are responsible to get data from remote APIs.
Currently, there are the following adapters:
BuzzHttpAdapter
to use Buzz, a lightweight PHP 5.3 library for issuing HTTP requests;CurlHttpAdapter
to use cURL;GuzzleHttpAdapter
to use Guzzle, PHP 5.3+ HTTP client and framework for building RESTful web service clients;SocketHttpAdapter
to use a socket;ZendHttpAdapter
to use Zend Http Client.
Providers contain the logic to extract useful information.
Currently, there are many providers for the following APIs:
- FreeGeoIp as IP-Based geocoding provider;
- HostIp as IP-Based geocoding provider;
- IpInfoDB as IP-Based geocoding provider (city precision);
- Google Maps as Address-Based geocoding and reverse geocoding provider;
- Google Maps for Business as Address-Based geocoding and reverse geocoding provider;
- Bing Maps as Address-Based geocoding and reverse geocoding provider;
- OpenStreetMaps as Address-Based geocoding and reverse geocoding provider;
- CloudMade as Address-Based geocoding and reverse geocoding provider;
- Geoip, the PHP extension, as IP-Based geocoding provider;
- ChainProvider is a special provider that takes a list of providers and iterates over this list to get information;
- MapQuest as Address-Based geocoding and reverse geocoding provider;
- OIORest as very accurate Address-Based geocoding and reverse geocoding provider (exclusively in Denmark);
- GeoCoder.ca as Address-Based geocoding and reverse geocoding provider (exclusively in USA & Canada);
- GeoCoder.us as Address-Based geocoding provider (exclusively in USA);
- IGN OpenLS as Address-Based geocoding provider (exclusively in France);
- DataScienceToolkit as IP-Based geocoding provider or an Address-Based provider (exclusively in USA & Canada);
- Yandex as Address-Based geocoding and reverse geocoding provider;
- GeoPlugin as IP-Based geocoding provider;
- GeoIPs as IP-Based geocoding provider;
- MaxMind web service as IP-Based geocoding provider (City/ISP/Org and Omni services);
- MaxMind binary file as IP-Based geocoding provider;
- Geonames as Place-Based geocoding and reverse geocoding provider;
- IpGeoBase as IP-Based geocoding provider (very accurate in Russia);
- Baidu as Address-Based geocoding and reverse geocoding provider (exclusively in China);
- TomTom as Address-Based geocoding and reverse geocoding provider;
- ArcGIS Online as Address-Based geocoding and reverse geocoding provider.
The recommended way to install Geocoder is through composer.
Just create a composer.json
file for your project:
{
"require": {
"willdurand/geocoder": "*"
}
}
And run these two commands to install it:
$ wget https://getcomposer.org/composer.phar
$ php composer.phar install
Now you can add the autoloader, and you will have access to the library:
<?php
require 'vendor/autoload.php';
If you don't use either Composer or a ClassLoader in your application, just require the provided autoloader:
<?php
require_once 'src/autoload.php';
You're done.
First, you need an adapter
to query an API:
<?php
$adapter = new \Geocoder\HttpAdapter\BuzzHttpAdapter();
The BuzzHttpAdapter
is tweakable, actually you can pass a Browser
object to this adapter:
<?php
$buzz = new \Buzz\Browser(new \Buzz\Client\Curl());
$adapter = new \Geocoder\HttpAdapter\BuzzHttpAdapter($buzz);
Now, you have to choose a provider
which is closed to what you want to get.
The FreeGeoIpProvider
named free_geo_ip
is able to geocode IPv4 and IPv6 addresses only.
The HostIpProvider
named host_ip
is able to geocode IPv4 addresses only.
The IpInfoDbProvider
named ip_info_db
is able to geocode IPv4 addresses only.
A valid api key is required.
The GoogleMapsProvider
named google_maps
is able to geocode and reverse geocode street addresses.
The GoogleMapsBusinessProvider
named google_maps_business
is able to geocode and reverse geocode street addresses.
A valid Client ID
is required. The private key is optional.
The BingMapsProvider
named bing_maps
is able to geocode and reverse geocode street addresses.
A valid api key is required.
The OpenStreetMapsProvider
named openstreetmaps
is able to geocode and reverse geocode street addresses.
The CloudMadeProvider
named cloudmade
is able to geocode and reverse geocode street addresses.
A valid api key is required.
The GeoipProvider
named geoip
is able to geocode IPv4 and IPv6 addresses only. No need to use an HttpAdapter
as it uses a local database.
See the MaxMind page for more information.
The ChainProvider
named chain
is a special provider that takes a list of providers and iterates over this list to get information.
The MapQuestProvider
named map_quest
is able to geocode and reverse geocode street addresses.
The OIORestProvider
named oio_rest
is able to geocode and reverse geocode street addresses, exclusively in Denmark.
The GeocoderCaProvider
named geocoder_ca
is able to geocode and reverse geocode street addresses, exclusively in USA & Canada.
The GeocoderUsProvider
named geocoder_us
is able to geocode street addresses only, exclusively in USA.
The IGNOpenLSProvider
named ign_openls
is able to geocode street addresses only, exclusively in France.
A valid OpenLS api key is required.
The DataScienceToolkitProvider
named data_science_toolkit
is able to geocode IPv4 addresses and street adresses, exclusively in USA & Canada.
The YandexProvider
named yandex
is able to geocode and reverse geocode street addresses.
The default langage-locale is ru-RU
, you can choose between uk-UA
, be-BY
,
en-US
, en-BR
and tr-TR
.
This provider can also reverse information based on coordinates (latitude,
longitude). It's possible to precise the toponym to get more accurate result for reverse geocoding:
house
, street
, metro
, district
and locality
.
The GeoPluginProvider
named geo_plugin
is able to geocode IPv4 addresses and IPv6 addresses only.
The GeoIPsProvider
named geo_ips
is able to geocode IPv4 addresses only.
A valid api key is required.
The MaxMindProvider
named maxmind
is able to geocode IPv4 and IPv6 addresses only.
A valid City/ISP/Org
or Omni
service's api key is required.
This provider provides two constants CITY_EXTENDED_SERVICE
by default and OMNI_SERVICE
.
The GeonamesProvider
named geonames
is able to geocode and reverse geocode places.
A valid username is required.
The IpGeoBaseProvider
named ip_geo_base
is able to geocode IPv4 addresses only, very accurate in Russia.
The BaiduProvider
named baidu
is able to geocode and reverse geocode street addresses, exclusively in China.
A valid api key is required.
The TomTomProvider
named tomtom
is able to geocode and reverse geocode street addresses.
The default langage-locale is en
, you can choose between de
, es
, fr
, it
, nl
, pl
, pt
and sv
.
A valid api key is required.
The ArcGISOnlineProvider
named arcgis_online
is able to geocode and reverse geocode street addresses.
It's possible to specify a sourceCountry to restrict result to this specific country thus reducing
request time (note that this doesn't work on reverse geocoding). This provider also supports SSL.
You can use one of them or write your own provider. You can also register all providers and decide later. That's we'll do:
<?php
$geocoder = new \Geocoder\Geocoder();
$geocoder->registerProviders(array(
new \Geocoder\Provider\GoogleMapsProvider(
$adapter, $locale, $region, $useSsl
),
new \Geocoder\Provider\GoogleMapsBusinessProvider(
$adapter, '<CLIENT_ID>', '<PRIVATE_KEY>', $locale, $region, $useSsl
),
new \Geocoder\Provider\YandexProvider(
$adapter, $locale, $toponym
),
new \Geocoder\Provider\MaxMindProvider(
$adapter, '<MAXMIND_API_KEY>', $service, $useSsl
),
new \Geocoder\Provider\ArcGISOnlineProvider(
$adapter, $sourceCountry, $useSsl
),
));
Parameters:
$locale
is available forYandexProvider
,BingMapsProvider
andTomTomProvider
.$region
is available forGoogleMapsProvider
andGoogleMapsBusinessProvider
.$toponym
is available forYandexProvider
.$service
is available forMaxMindProvider
.$useSsl
is available forGoogleMapsProvider
,GoogleMapsBusinessProvider
,MaxMindProvider
andArcGISOnlineProvider
.$sourceCountry
is available forArcGISOnlineProvider
.
As said it's 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 GoogleMapsProvider
because FreeGeoIpProvider
and HostIpProvider
cannot geocode street addresses. BingMapsProvider
is ignored.
$geocoder = new \Geocoder\Geocoder();
$adapter = new \Geocoder\HttpAdapter\CurlHttpAdapter();
$chain = new \Geocoder\Provider\ChainProvider(array(
new \Geocoder\Provider\FreeGeoIpProvider($adapter),
new \Geocoder\Provider\HostIpProvider($adapter),
new \Geocoder\Provider\GoogleMapsProvider($adapter, 'fr_FR', 'France', true),
new \Geocoder\Provider\BingMapsProvider($adapter, '<API_KEY>'),
// ...
));
$geocoder->registerProvider($chain);
try {
$geocode = $geocoder->geocode('10 rue Gambetta, Paris, France');
var_export($geocode);
} catch (Exception $e) {
echo $e->getMessage();
}
Everything is ok, enjoy!
The main method is called geocode()
which receives a value to geocode. It can be an IP address or a street address (partial or not).
<?php
$result = $geocoder->geocode('88.188.221.14');
// Result is:
// "latitude" => string(9) "47.901428"
// "longitude" => string(8) "1.904960"
// "bounds" => array(4) {
// "south" => string(9) "47.813320"
// "west" => string(8) "1.809770"
// "north" => string(9) "47.960220"
// "east" => string(8) "1.993860"
// }
// "streetNumber" => string(0) ""
// "streetName" => string(0) ""
// "cityDistrict" => string(0) ""
// "city" => string(7) "Orleans"
// "zipcode" => string(0) ""
// "county" => string(6) "Loiret"
// "countyCode" => null
// "region" => string(6) "Centre"
// "regionCode" => null
// "country" => string(6) "France"
// "countryCode" => string(2) "FR"
// "timezone" => string(6) "Europe/Paris"
$result = $geocoder->geocode('10 rue Gambetta, Paris, France');
// Result is:
// "latitude" => string(9) "48.863217"
// "longitude" => string(8) "2.388821"
// "bounds" => array(4) {
// "south" => string(9) "48.863217"
// "west" => string(8) "2.388821"
// "north" => string(9) "48.863217"
// "east" => string(8) "2.388821"
// }
// "streetNumber" => string(2) "10"
// "streetName" => string(15) "Avenue Gambetta"
// "cityDistrict" => string(18) "20E Arrondissement"
// "city" => string(5) "Paris"
// "county" => string(5) "Paris"
// "countyCode" => null
// "zipcode" => string(5) "75020"
// "region" => string(14) "Ile-de-France"
// "regionCode" => null
// "country" => string(6) "France"
// "countryCode" => string(2) "FR"
// "timezone" => string(6) "Europe/Paris"
The geocode()
method returns a Geocoded
result object with the following API, this object also implements the ArrayAccess
interface:
getCoordinates()
will return an array withlatitude
andlongitude
values;getLatitude()
will return thelatitude
value;getLongitude()
will return thelongitude
value;getBounds()
will return an array withsouth
,west
,north
andeast
values;getStreetNumber()
will return thestreet number/house number
value;getStreetName()
will return thestreet name
value;getCity()
will return thecity
;getZipcode()
will return thezipcode
;getCityDistrict()
will return thecity district
, orsublocality
;getCounty()
will return thecounty
;getCountyCode()
will return thecounty
code (county short name);getRegion()
will return theregion
;getRegionCode()
will return theregion
code (region short name);getCountry()
will return thecountry
;getCountryCode()
will return the ISOcountry
code;getTimezone()
will return thetimezone
.
The Geocoder's API is fluent, you can write:
<?php
$result = $geocoder
->registerProvider(new \My\Provider\Custom($adapter))
->using('custom')
->geocode('68.145.37.34')
;
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.
This library provides a reverse()
method to retrieve information from coordinates:
$result = $geocoder->reverse($latitude, $longitude);
Geocoder provides dumpers that aim to transform a ResultInterface
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 ResultInterface
object in an GPX compliant format.
Assuming we got a $result
object as seen previously:
<?php
$dumper = new \Geocoder\Dumper\GpxDumper();
$strGpx = $dumper->dump($result);
echo $strGpx;
It will display:
<gpx
version="1.0"
creator="Geocoder" version="1.0.1-dev"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xmlns="https://www.topografix.com/GPX/1/0"
xsi:schemaLocation="https://www.topografix.com/GPX/1/0 https://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.
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 Formatter
class,
it's really easy to format a ResultInterface
object as a string:
<?php
// $result is an instance of ResultInterface
$formatter = new \Geocoder\Formatter\Formatter($result);
$formatter->format('%S %n, %z %L');
// 'Badenerstrasse 120, 8001 Zuerich'
$formatter->format('<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
-
County:
%P
-
County Code:
%p
-
Region:
%R
-
Region Code:
%r
-
Country:
%C
-
Country Code:
%c
-
Timezone:
%T
You can provide your own adapter
, you just need to create a new class which implements HttpAdapterInterface
.
You can also write your own provider
by implementing the ProviderInterface
.
You can provide your own result
by extending DefaultResultFactory
or MultipleResultFactory
and implementing
ResultInterface
if your provider returns one or multiple results and more informations than the default one.
Please note that the method createFromArray
is marked final
in these factories.
If you need your own ResultFactory
, just implement ResultFactoryInterface
.
Note, AbstractProvider
and AbstractResult
classes can help you by providing useful features.
You can provide your own dumper
by implementing the DumperInterface
.
Write your own formatter
by implementing the FormatterInterface
.
To run unit tests, you'll need cURL
and a set of dependencies you can install using Composer:
php composer.phar install --dev
Once installed, just launch the following command:
phpunit
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="CLOUDMADE_API_KEY" value="YOUR_API_KEY" /> -->
<!-- <server name="IGN_WEB_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="BAIDU_API_KEY" value="YOUR_API_KEY" /> -->
<!-- <server name="TOMTOM_GEOCODING_KEY" value="YOUR_GEOCODING_KEY" /> -->
<!-- <server name="TOMTOM_MAP_KEY" value="YOUR_MAP_KEY" /> -->
</php>
You're done.
- William Durand [email protected]
- All contributors
Geocoder is released under the MIT License. See the bundled LICENSE file for details.