Geocoder is a library which helps you build geo-aware applications. It provides an abstraction layer for geocoding manipulations.
The library is splitted in two parts:
HttpAdapters are responsible to get data from remote APIs. Currently, there is one adapter for Buzz, a lightweight PHP 5.3 library for issuing HTTP requests.
Providers contain the logic to extract useful information. Currently, there are three providers for the following APIs:
- IpInfoDB as IP-Based geocoding provider;
- Yahoo! PlaceFinder as Address-Based geocoding provider;
- HostIp as IP-Based geocoding provider.
If you don't use a ClassLoader in your application, just require the provided autoloader:
<?php require_once 'src/autoload.php';
First, you need an
<?php $adapter = new \Geocoder\HttpAdapter\BuzzHttpAdapter();
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
YahooProvider is able to geocode both IP addresses and street addresses.
HostIpProvider are able to geocode IP addresses only.
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\YahooProvider( $adapter, '<YAHOO_API_KEY>', $locale ), new \Geocoder\Provider\IpInfoDbProvider( $adapter, '<IPINFODB_API_KEY>' ), new \Geocoder\Provider\HostIpProvider($adapter) ));
$locale parameter is available and optional for the
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 $geocoder->geocode('220.127.116.11'); // Result is: // "latitude" => string(9) "47.901428" // "longitude" => string(8) "1.904960" // "city" => string(7) "Orleans" // "zipcode" => string(0) "" // "region" => string(6) "Centre" // "country" => string(6) "France" $geocoder->geocode('10 rue Gambetta, Paris, France'); // Result is: // "latitude" => string(9) "48.863217" // "longitude" => string(8) "2.388821" // "city" => string(5) "Paris" // "zipcode" => string(5) "75020" // "region" => string(14) "Ile-de-France" // "country" => string(6) "France"
Once you've called this method, the
geocoder contains information that you can query with the following getters:
getCoordinates()will return an array with
getLatitude()will return the
getLongitude()will return the
getCity()will return the
getZipcode()will return the
getRegion()will return the
getCountry()will return te
The Geocoder's API is fluent, you can write:
<?php $geocoder ->registerProvider(new \My\Provider\Custom($adapter)) ->using('custom') ->geocode('18.104.22.168') ;
using() method allows you to choose the
adapter to use. When you deal with multiple adapters, 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:
IpInfoDbProvider doesn't provide this feature.
You can provide your own
adapter, you just need to create a new class which implements
You can also write your own
provider by implementing the
ProviderInterface. Note, the
AbstractProvider class can help you by
providing useful features.
To run unit tests, you'll need two dependencies:
git clone git://github.com/kriswallsmith/Buzz.git vendor/Buzz git clone git://github.com/symfony/ClassLoader.git vendor/Symfony/Component/ClassLoader
Once installed, just launch the following command:
- William Durand
Geocoder is released under the MIT License. See the bundled LICENSE file for details.