Repository files navigation

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:HttpAdapter andProvider and is really extensible.

HttpAdapters are responsible to get data from remote APIs.

Currently, there are the following adapters:

• BuzzHttpAdapter forBuzz, a lightweight PHP 5.3 library for issuing HTTP requests;
• CurlHttpAdapter forcURL;
• GuzzleHttpAdapter forGuzzle, PHP 5.3+ HTTP client and framework for building RESTful web service clients;
• ZendHttpAdapter forZend 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;
• Yahoo! PlaceFinder as Address-Based geocoding and reverse geocoding provider;
• Google Maps 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 iteratesover this list to get information.

The recommended way to install Geocoder is through composer.

Just create acomposer.json file for your project:

{"require": {"willdurand/geocoder":"*"    }}

And run these two commands to install it:

$ wget http://getcomposer.org/composer.phar$ php composer.phar install

Now you can add the autoloader, and you will have access to the library:

<?phprequire'vendor/autoload.php';

If you don't use neitherComposer nor aClassLoader in your application, just require the provided autoloader:

<?phprequire_once'src/autoload.php';

You're done.

First, you need anadapter to query an API:

<?php$adapter  =new \Geocoder\HttpAdapter\BuzzHttpAdapter();

TheBuzzHttpAdapter is tweakable, actually you can pass aBrowser object to this adapter:

<?php$buzz    =new \Buzz\Browser(new \Buzz\Client\Curl());$adapter =new \Geocoder\HttpAdapter\BuzzHttpAdapter($buzz);

Now, you have to choose aprovider which is closed to what you want to get.

TheFreeGeoIpProvider is able to geocodeIP addresses only.

TheHostIpProvider is able to geocodeIP addresses only.

TheIpInfoDbProvider is able to geocodeIP addresses only.

TheYahooProvider is able to geocode bothIP addresses andstreet addresses.This provider can also reverse information based on coordinates (latitude, longitude).

TheGoogleMapsProvider is able to geocode and reverse geocodestreet addresses.

TheBingMapsProvider is able to geocode and reverse geocodestreet addresses.

TheOpenStreetMapsProvider is able to geocode and reverse geocodestreet addresses.

TheCloudMadeProvider is able to geocode and reverse geocodestreet addresses.

TheGeoipProvider is able to geocodeIP addresses only. No need to use anHttpAdapter as it uses a local database.See theMaxMind page for more information.

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)));

The$locale parameter is available for theYahooProvider.

Everything is ok, enjoy!

The main method is calledgeocode() 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) ""// "city"           => string(7) "Orleans"// "zipcode"        => string(0) ""// "county"         => string(6) "Loiret"// "region"         => string(6) "Centre"// "country"        => string(6) "France"// "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"// "city"           => string(5) "Paris"// "county"         => string(5) "Paris"// "zipcode"        => string(5) "75020"// "region"         => string(14) "Ile-de-France"// "country"        => string(6) "France"// "timezone"       => string(6) "Europe/Paris"

Thegeocode() method returns aGeocoded result object with the following API, this object also implements theArrayAccess 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;
• getRegion() will return theregion;
• getRegionCode() will return theregion code (region short name);
• getCountry() will return thecountry;
• getCountryCode() will return the ISO country code;
• getTimezone() will return the timezone.

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')    ;

Theusing() method allows you to choose theadapter to use. When you deal with multiple adapters, you may want tochoose one of them. The default behavior is to use the first one but it can be annoying.

This library provides areverse() method to retrieve information from coordinates:

$result =$geocoder->reverse($latitude,$longitude);

Note: theYahooProvider bundled in this lib is the unique provider able to do this feature.

Geocoder provides dumpers that aim to transform aResultInterface object in standard formats.

TheGPS eXchange format is designed to share geolocated data like point of interests, tracks, ways, but alsocoordinates.Geocoder provides a dumper to convert aResultInterface 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:

<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 geographic data structures.

Keyhole Markup Language is an XML notationfor expressing geographic annotation and visualization within Internet-based, two-dimensional mapsand 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 theFormatter class,it's really easy to format aResultInterface 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

• Zipcode:%z

• County:%P

• Region:%R

• Region Code:%r

• Country:%C

• Country Code:%c

• Timezone:%T

You can provide your ownadapter, you just need to create a new class which implementsHttpAdapterInterface.

You can also write your ownprovider by implementing theProviderInterface.

Note, theAbstractProvider class can help you by providing useful features.

You can provide your owndumper by implementing theDumperInterface.

Write your ownformatter by implementing theFormatterInterface.

To run unit tests, you'll need 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 someskipped unit tests due to the need of API keys.

Rename thephpunit.xml.dist file tophpunit.xml, then uncomment the following lines and add your own API keys:

<php><!-- <server name="IPINFODB_API_KEY" value="YOUR_API_KEY" />--><!-- <server name="YAHOO_API_KEY" value="YOUR_API_KEY" />--><!-- <server name="BINGMAPS_API_KEY" value="YOUR_API_KEY" />--><!-- <server name="CLOUDMADE_API_KEY" value="YOUR_API_KEY" />--></php>

You're done.

• William Durandwilliam.durand1@gmail.com
• All contributors

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