Geocoder
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., (*1)
, (*2)
HttpAdapters
HttpAdapters are responsible to get data from remote APIs., (*3)
Currently, there are the following adapters:, (*4)
-
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
Providers contain the logic to extract useful information., (*5)
Currently, there are many providers for the following APIs:, (*6)
-
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;
-
OpenStreetMap as Address-Based geocoding and reverse geocoding provider (based on the Nominatim provider);
-
Nominatim 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 Geocoder Extra library contains even more providers!, (*7)
Installation
The recommended way to install Geocoder is through composer., (*8)
Just create a composer.json file for your project:, (*9)
``` json
{
"require": {
"willdurand/geocoder": "@stable"
}
}, (*10)
**Protip:** you should browse the [`willdurand/geocoder`](https://packagist.org/packages/willdurand/geocoder)
page to choose a stable version to use, avoid the `@stable` meta constraint.
And run these two commands to install it:
``` bash
$ curl -sS https://getcomposer.org/installer | php
$ composer install
Now you can add the autoloader, and you will have access to the library:, (*11)
``` php
<?php, (*12)
require 'vendor/autoload.php';, (*13)
If you don't use either **Composer** or a _ClassLoader_ in your application, just require the provided autoloader:
``` php
<?php
require_once 'src/autoload.php';
You're done., (*14)
Usage
First, you need an adapter to query an API:, (*15)
``` php
<?php, (*16)
$adapter = new \Geocoder\HttpAdapter\BuzzHttpAdapter();, (*17)
The `BuzzHttpAdapter` is tweakable, actually you can pass a `Browser` object to this adapter:
``` php
<?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., (*18)
FreeGeoIpProvider
The FreeGeoIpProvider named free_geo_ip is able to geocode IPv4 and IPv6 addresses only., (*19)
HostIpProvider
The HostIpProvider named host_ip is able to geocode IPv4 addresses only., (*20)
IpInfoDbProvider
The IpInfoDbProvider named ip_info_db is able to geocode IPv4 addresses only.
A valid api key is required., (*21)
GoogleMapsProvider
The GoogleMapsProvider named google_maps is able to geocode and reverse geocode street addresses., (*22)
GoogleMapsBusinessProvider
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., (*23)
BingMapsProvider
The BingMapsProvider named bing_maps is able to geocode and reverse geocode street addresses.
A valid api key is required., (*24)
OpenStreetMapProvider
The OpenStreetMapProvider named openstreetmap is able to geocode and reverse
geocode street addresses., (*25)
Warning: The OpenStreetMapsProvider is deprecated, and you should
rather use the OpenStreetMapProvider. See issue
#269., (*26)
NominatimProvider
The NominatimProvider named nominatim is able to geocode and reverse geocode street addresses.
Access to a Nominatim server is required. See the Nominatim
Wiki Page for more information., (*27)
CloudMadeProvider
The CloudMadeProvider named cloudmade is able to geocode and reverse geocode street addresses.
A valid api key is required., (*28)
GeoipProvider
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., (*29)
ChainProvider
The ChainProvider named chain is a special provider that takes a list of providers and iterates over this list to get information., (*30)
MapQuestProvider
The MapQuestProvider named map_quest is able to geocode and reverse geocode street addresses.
A valid api key is required., (*31)
OIORestProvider
The OIORestProvider named oio_rest is able to geocode and reverse geocode street addresses, exclusively in Denmark., (*32)
GeocoderCaProvider
The GeocoderCaProvider named geocoder_ca is able to geocode and reverse geocode street addresses, exclusively in USA & Canada., (*33)
GeocoderUsProvider
The GeocoderUsProvider named geocoder_us is able to geocode street addresses only, exclusively in USA., (*34)
IGNOpenLSProvider
The IGNOpenLSProvider named ign_openls is able to geocode street addresses only, exclusively in France.
A valid OpenLS api key is required., (*35)
The DataScienceToolkitProvider named data_science_toolkit is able to geocode IPv4 addresses and street adresses, exclusively in USA & Canada., (*36)
YandexProvider
The YandexProvider named yandex is able to geocode and reverse geocode street addresses.
The default language-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., (*37)
GeoPluginProvider
The GeoPluginProvider named geo_plugin is able to geocode IPv4 addresses and IPv6 addresses only., (*38)
GeoIPsProvider
The GeoIPsProvider named geo_ips is able to geocode IPv4 addresses only.
A valid api key is required., (*39)
MaxMindProvider
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., (*40)
GeonamesProvider
The GeonamesProvider named geonames is able to geocode and reverse geocode places.
A valid username is required., (*41)
IpGeoBaseProvider
The IpGeoBaseProvider named ip_geo_base is able to geocode IPv4 addresses only, very accurate in Russia., (*42)
BaiduProvider
The BaiduProvider named baidu is able to geocode and reverse geocode street addresses, exclusively in China.
A valid api key is required., (*43)
TomTomProvider
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., (*44)
ArcGISOnlineProvider
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., (*45)
Using The Providers
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:, (*46)
``` php
<?php, (*47)
$geocoder = new \Geocoder\Geocoder();
$geocoder->registerProviders(array(
new \Geocoder\Provider\GoogleMapsProvider(
$adapter, $locale, $region, $useSsl
),
new \Geocoder\Provider\GoogleMapsBusinessProvider(
$adapter, '', '', $locale, $region, $useSsl
),
new \Geocoder\Provider\YandexProvider(
$adapter, $locale, $toponym
),
new \Geocoder\Provider\MaxMindProvider(
$adapter, '', $service, $useSsl
),
new \Geocoder\Provider\ArcGISOnlineProvider(
$adapter, $sourceCountry, $useSsl
),
new \Geocoder\Provider\NominatimProvider(
$adapter, 'http://your.nominatim.server', $locale
),
));, (*48)
Parameters:
* `$locale` is available for `YandexProvider`, `BingMapsProvider` and `TomTomProvider`.
* `$region` is available for `GoogleMapsProvider` and `GoogleMapsBusinessProvider`.
* `$toponym` is available for `YandexProvider`.
* `$service` is available for `MaxMindProvider`.
* `$useSsl` is available for `GoogleMapsProvider`, `GoogleMapsBusinessProvider`, `MaxMindProvider` and `ArcGISOnlineProvider`.
* `$sourceCountry` is available for `ArcGISOnlineProvider`.
* `$rootUrl` is available for `NominatimProvider`.
### Using The ChainProvider ###
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.
``` php
$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!, (*49)
API
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)., (*50)
``` php
<?php, (*51)
$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", (*52)
$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", (*53)
The `geocode()` method returns a `Geocoded` result object with the following API, this object also implements the `ArrayAccess` interface:
* `getCoordinates()` will return an array with `latitude` and `longitude` values;
* `getLatitude()` will return the `latitude` value;
* `getLongitude()` will return the `longitude` value;
* `getBounds()` will return an array with `south`, `west`, `north` and `east` values;
* `getStreetNumber()` will return the `street number/house number` value;
* `getStreetName()` will return the `street name` value;
* `getCity()` will return the `city`;
* `getZipcode()` will return the `zipcode`;
* `getCityDistrict()` will return the `city district`, or `sublocality`;
* `getCounty()` will return the `county`;
* `getCountyCode()` will return the `county` code (county short name);
* `getRegion()` will return the `region`;
* `getRegionCode()` will return the `region` code (region short name);
* `getCountry()` will return the `country`;
* `getCountryCode()` will return the ISO `country` code;
* `getTimezone()` will return the `timezone`.
The Geocoder's API is fluent, you can write:
``` php
<?php
$result = $geocoder
->registerProvider(new \My\Provider\Custom($adapter))
->using('custom')
->limit(10)
->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., (*54)
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., (*55)
Reverse Geocoding
This library provides a reverse() method to retrieve information from coordinates:, (*56)
``` php
$result = $geocoder->reverse($latitude, $longitude);, (*57)
Dumpers
-------
**Geocoder** provides dumpers that aim to transform a `ResultInterface` 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 `ResultInterface` object in an GPX compliant format.
Assuming we got a `$result` object as seen previously:
``` php
<?php
$dumper = new \Geocoder\Dumper\GpxDumper();
$strGpx = $dumper->dump($result);
echo $strGpx;
It will display:, (*58)
``` xml
![CDATA[Paris]]
![CDATA[Address]]
, (*59)
### GeoJSON ###
[GeoJSON](http://geojson.org/) is a format for encoding a variety of geographic data structures.
### Keyhole Markup Language (KML) ###
[Keyhole Markup Language](http://en.wikipedia.org/wiki/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.
Formatter
---------
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
<?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('
%S %n, %z %L, (*60)
');
// '
Badenerstrasse 120, 8001 Zuerich, (*61)
'
Here is the mapping:, (*62)
-
Street Number: %n, (*63)
-
Street Name: %S, (*64)
-
City: %L, (*65)
-
City District: %D, (*66)
-
Zipcode: %z, (*67)
-
County: %P, (*68)
-
County Code: %p, (*69)
-
Region: %R, (*70)
-
Region Code: %r, (*71)
-
Country: %C, (*72)
-
Country Code: %c, (*73)
-
Timezone: %T, (*74)
Extending Things
You can provide your own adapter, you just need to create a new class which implements HttpAdapterInterface., (*75)
You can also write your own provider by implementing the ProviderInterface., (*76)
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., (*77)
If you need your own ResultFactory, just implement ResultFactoryInterface., (*78)
Note, AbstractProvider and AbstractResult classes can help you by providing useful features., (*79)
You can provide your own dumper by implementing the DumperInterface., (*80)
Write your own formatter by implementing the FormatterInterface., (*81)
Contributing
See CONTRIBUTING file., (*82)
Unit Tests
To run unit tests, you'll need cURL and a set of dependencies you can install using Composer:, (*83)
composer install --dev
Once installed, just launch the following command:, (*84)
phpunit
You'll obtain some skipped unit tests due to the need of API keys., (*85)
Rename the phpunit.xml.dist file to phpunit.xml, then uncomment the following lines and add your own API keys:, (*86)
xml
<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>, (*87)
You're done., (*88)
Credits
License
Geocoder is released under the MIT License. See the bundled LICENSE file for details., (*89)
Wallogit.com
