Skip to content

scshasha/Geocoder

BranchesTags
 
 

Repository files navigation

Geocoder

Build Status Latest Stable Version Total Downloads Monthly Downloads Software License

Important: You are browsing the documentation of Geocoder 4.x (not released yet).

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.

Summery (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 php-http/message

Cookbook

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

Usage

Geocoder and its companion Geocoder Extra provides a lot of providers.

Choose the one that fits your need first. Let's say the GoogleMaps one is what you were looking for, so let's see how to use it. In the code snippet below, curl has been chosen as HTTP layer but it is up to you since each HTTP-based provider implements PSR-7.

$adapter  = new \Http\Adapter\Guzzle6\Client();
$provider = new \Geocoder\Provider\GoogleMaps($adapter);
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$geocoder->geocodeQuery(GeocodeQuery::create(...));
$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)

Location & Collection

Both geocodeQuery() and reverseQuery() methods return a collection of Location objects (Collection), each providing the following API:

  • getCoordinates() will return a Coordinates object (with latitude and longitude properties);
  • getLatitude() will return the latitude value;
  • getLongitude() will return the longitude value;
  • getBounds() will return an Bounds object (with south, west, north and east properties);
  • getStreetNumber() will return the street number/house number value;
  • getStreetName() will return the street name value;
  • getLocality() will return the locality or city;
  • getPostalCode() will return the postalCode or zipcode;
  • getSubLocality() will return the city district, or sublocality;
  • getAdminLevels() will return an ordered collection (AdminLevelCollection) of AdminLevel object (with level, name and code properties);
  • getCountry() will return a Country object (with name and code properties);
  • getCountryCode() will return the ISO country code;
  • getTimezone() will return the timezone.

The AddressCollection exposes the following methods:

  • count() (this class implements Countable);
  • first() retrieves the first Address;
  • slice($offset, $length = null) returns Address objects between $offset and length;
  • get($index) fetches an Address using its $index;
  • all() returns all Address objects;
  • getIterator() (this class implements IteratorAggregate).

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.

$geocoder = new \Geocoder\ProviderAggregator();
$adapter  = new \Http\Adapter\Guzzle6\Client();

$chain = new \Geocoder\Provider\Chain([
    new \Geocoder\Provider\FreeGeoIp($adapter),
    new \Geocoder\Provider\HostIp($adapter),
    new \Geocoder\Provider\GoogleMaps($adapter, 'France'),
    new \Geocoder\Provider\BingMaps($adapter, '<API_KEY>'),
    // ...
]);

$geocoder->registerProvider($chain);

$geocode = $geocoder->geocode('10 rue Gambetta, Paris, France');
var_export($geocode);

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.

<?php

$geocoder = new \Geocoder\ProviderAggregator();

$geocoder->registerProviders([
    new \Geocoder\Provider\GoogleMaps(
        $adapter, $locale, $region, $useSsl
    ),
    new \Geocoder\Provider\GoogleMapsBusiness(
        $adapter, '<CLIENT_ID>', '<PRIVATE_KEY>', $locale, $region, $useSsl
    ),
    new \Geocoder\Provider\Yandex(
        $adapter, $locale, $toponym
    ),
    new \Geocoder\Provider\MaxMind(
        $adapter, '<MAXMIND_API_KEY>', $service, $useSsl
    ),
    new \Geocoder\Provider\ArcGISOnline(
        $adapter, $sourceCountry, $useSsl
    ),
]);

$geocoder->registerProvider(
    new \Geocoder\Provider\Nominatim(
        $adapter, 'http://your.nominatim.server', $locale
    )
);

$geocoder
    ->using('google_maps')
    ->geocode('...');

$geocoder
    ->limit(10)
    ->reverse($lat, $lng);

The ProviderAggregator's API is fluent, meaning you can write:

<?php

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

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.

// configure you geocoder object

$stopwatch = new \Symfony\Component\Stopwatch\Stopwatch();
$geocoder = new \Geocoder\TimedGeocoder($geocoder, $stopwatch);

$geocoder->geocode('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.

Providers

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

Address-based Providers

Provider Name Reverse? SSL? Coverage Multiple? Terms
ArcGIS Online arcgis_online yes supported worldwide yes requires API key. 1250 requests free
Bing Maps bing_maps yes no worldwide yes requires API key. Limit 10,000 requests per month
Chain chain meta provider which iterates over a list of providers
Geonames geonames yes no worldwide yes requires registration, no free tier
Google Maps google_maps yes supported worldwide yes requires API key. Limit 2500 requests per day
Google Maps for Business google_maps_business yes supported worldwide yes requires API key. Limit 100,000 requests per day
MapQuest map_quest yes no worldwide yes both open and commercial service requires API key
Mapzen mapzen yes supported worldwide yes requires API key; limited to 6 request/sec, 30,000 request/day
Nominatim nominatim yes supported worldwide yes requires a domain name (e.g. local installation)
OpenCage opencage yes supported worldwide yes requires API key. 2500 requests/day free
OpenStreetMap openstreetmap yes no worldwide yes heavy users (>1q/s) get banned
TomTom tomtom yes required worldwide yes requires API key. First 2500 requests or 30 days free
Yandex yandex yes no worldwide yes

Below, you will find more information for these providers.

ArcGISOnline

It is 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).

GeoIP2

It requires either the database file, or the webservice - represented by the GeoIP2 , which is injected to the GeoIP2Adapter. The geoip2/geoip2 package must be installed.

This provider will only work with the corresponding GeoIP2Adapter:

<?php

// Maxmind GeoIP2 Provider: e.g. the database reader
$reader   = new \GeoIp2\Database\Reader('/path/to/database');

$adapter  = new \Geocoder\Adapter\GeoIP2Adapter($reader);
$geocoder = new \Geocoder\Provider\GeoIP2($adapter);

$address   = $geocoder->geocode('74.200.247.59')->first();
GoogleMaps

Locale and/or region can be specified:

$geocoder = new \Geocoder\Provider\GoogleMaps(
    $httpAdapter,
    $locale,
    $region,
    $useSsl, // true|false
    $apiKey
);
GoogleMapsBusiness

A valid Client ID is required. The private key is optional. This provider also supports SSL, and extends the GoogleMaps provider.

Mapzen

A valid API key is required. This provider also supports SSL.

MaxMindBinary

This provider requires a data file, and the geoip/geoip package must be installed.

It is worth mentioning that this provider has serious performance issues, and should not be used in production. For more information, please read issue #301.

Nominatim

Access to a Nominatim server is required. See the Nominatim Wiki Page for more information.

TomTom

The default language-locale is en, you can choose between de, es, fr, it, nl, pl, pt and sv.

Yandex

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.

IP-based Providers

Provider Name IPv4? IPv6? Multiple? Terms Notes
FreeGeoIp free_geo_ip yes yes no
GeoIPs geo_ips yes no no requires API key
GeoIP2 (Maxmind) maxmind_geoip2 yes yes no
GeoPlugin geo_plugin yes yes no
HostIp host_ip yes no no
IpInfoDB ip_info_db yes no no requires API key city precision
Geoip geoip yes no no wrapper around the PHP extension which must be installed
MaxMind web service maxmind yes yes no requires Omni API key City/ISP/Org and Omni services, IPv6 on country level
MaxMind Binary file maxmind_binary yes no no needs locally installed database files

Important: the Geocoder Extra library contains even more official providers!

Locale Aware Providers

Providers that are locale aware expose the following methods:

$geocoder->setLocale('xyz');

$locale = $geocoder->getLocale();

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 an Address object in an GPX compliant format.

Assuming we got a $address object as seen previously:

<?php

$dumper = new \Geocoder\Dumper\Gpx();
$strGpx = $dumper->dump($address);

echo $strGpx;

It will display:

<gpx
    version="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">
    <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

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 an Address object as a string:

<?php

// $address is an instance of Address
$formatter = new \Geocoder\Formatter\StringFormatter();

$formatter->format($address, '%S %n, %z %L');
// 'Badenerstrasse 120, 8001 Zuerich'

$formatter->format($address, '<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
  • 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.

Stable Version

Version 3.x is the current major stable version of Geocoder.

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:

<php>
    <!-- <server name="IPINFODB_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="BINGMAPS_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="TOMTOM_MAP_KEY" value="YOUR_MAP_KEY" /> -->
    <!-- <server name="GOOGLE_GEOCODING_KEY" value="YOUR_GEOCODING_KEY" /> -->
    <!-- <server name="OPENCAGE_API_KEY" value="YOUR_API_KEY" /> -->
</php>

You're done.

Credits

Contributor Code of Conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at http://contributor-covenant.org/version/1/0/0/

License

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

About

The most featured Geocoder library written in PHP.

geocoder-php.org/Geocoder

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

54 tags

Packages

No packages published

Languages

  • PHP 100.0%