Geocoder：一个帮助我们建立地理感知应用程序的php类库

Geocoder ======== [](http://travis-ci.org/geocoder-php/Geocoder) [](https://packagist.org/packages/willdurand/Geocoder) [](https://packagist.org/packages/willdurand/Geocoder)  > **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](https://github.com/geocoder-php/Geocoder/blob/3.x/README.md). > > Documentation for version **2.x** is available here: [Geocoder 2.x > documentation](https://github.com/geocoder-php/Geocoder/blob/2.x/README.md). --- **Geocoder** is a PHP library which helps you build geo-aware applications by providing a powerful abstraction layer for geocoding manipulations. * [Installation](#installation) * [Usage](#usage) - [Address & AddressCollection](#address--addresscollection) - [The ProviderAggregator](#the-provideraggregator) - [TimedGeocoder](#timedgeocoder) - [HTTP Adapters](#http-adapters) - [Providers](#providers) - [Address-based Providers](#address-based-providers) - [ArcGISOnline](#arcgisonline) - [GeoIP2](#geoip2) - [GoogleMaps](#googlemaps) - [GoogleMapsBusiness](#googlemapsbusiness) - [Mapzen](#mapzen) - [MaxMindBinary](#maxmindbinary) - [Nominatim](#nominatim) - [TomTom](#tomtom) - [Yandex](#yandex) - [IP-based Providers](#ip-based-providers) - [Locale Aware Providers](#locale-aware-providers) - [The Chain Provider](#the-chain-provider) - [Dumpers](#dumpers) - [GPS eXchange Format (GPX)](#gps-exchange-format-gpx) - [GeoJSON](#geojson) - [GeoArray](#geoarray) - [Keyhole Markup Language (KML)](#keyhole-markup-language-kml) - [Well-Known Binary (WKB)](#well-known-binary-wkb) - [Well-Known Text (WKT)](#well-known-text-wkt) - [Formatters](#formatters) * [Extending Things](#extending-things) * [Versioning](#versioning) * [Cookbook](#cookbook) Installation ------------ The recommended way to install Geocoder is through [Composer](http://getcomposer.org): ``` $ composer require willdurand/geocoder ``` Usage ----- [Geocoder](https://github.com/geocoder-php/Geocoder) and its companion [Geocoder Extra](https://github.com/geocoder-php/geocoder-extra) provides a lot of [providers](#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](#http-adapters) but it is up to you since each HTTP-based provider implements [PSR-7](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md). ```php $adapter = new \Http\Adapter\Guzzle6\Client(); $geocoder = new \Geocoder\Provider\GoogleMaps($adapter); $geocoder->geocode(...); $geocoder->reverse(...); ``` The `Geocoder` interface, which all providers implement, exposes two main methods: * `geocode($streetOrIpAddress)` * `reverse($latitude, $longitude)` It also contains methods to control the number of results: * `limit($limit)` * `getLimit()` ### Address & AddressCollection Both `geocode()` and `reverse()` methods return a collection of `Address` objects (`AddressCollection`), 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`). ### The ProviderAggregator The `ProviderAggregator` is used to register several providers so that you can decide which provider to use later on. ``` php <?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 <?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. ```php // 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](http://symfony.com/doc/current/components/stopwatch.html) 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. ### HTTP Adapters In order to talk to geocoding APIs, you need HTTP adapters. While it was part of the library in Geocoder 1.x and 2.x, Geocoder 3.x and upper now relies on the [PSR-7 Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md) which defines how HTTP message should be implemented. You can use any library to send HTTP messages that implements [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation). To use Guzzle 6 you should run the follwing command: ``` $ composer require php-http/guzzle6-adapter ``` ### Providers Providers perform the geocoding black magic for you (talking to the APIs, fetching results, dealing with erro