markenwerk/google-geocoder

A PHP library to query Google's location service for geolocation and reverse lookups based on a given address, a geo location or a Google Places ID.

PHP Google Geocoder

, _(*1)

A PHP library to query Google's location service for geolocation and reverse lookups based on a given address, a geo location or a Google Places ID., _(*2)

Installation

```{json} { "require": { "chroma-x/google-geocoder": "~3.0" } }, <sub>(*3)</sub>

## Usage

### Autoloading and namesapce

```{php}  
require_once('path/to/vendor/autoload.php');

Performing a GeoLookup

Resolving an address

The API provides an optional usage of an API key to circumvent API quota limits. Please visit the Google API console to receive an API key., <sub>(*4)</sub>

```{php} use ChromaX\CommonException;, <sub>(*5)</sub>

try{ // Perform lookup $addressLookup = new ChromaX\GoogleGeocode\Lookup\AddressLookup(); $addressLookup = new Markenwerk\GoogleGeocode\Lookup\AddressLookup();, <sub>(*6)</sub>

// Optional adding an API key
$addressLookup->setApiKey('MY_GOOGLE_GEOCODING_API_KEY');

// Submit lookup
$addressLookup->lookup('Germany, 24105 Kiel, Lornsenstraße 43');

// Retrieving the lookup as an array of ChromaX\GoogleGeocode\Result\GeoLookupResult instances
$lookupResults = $addressLookup->getResults();

// Get the number of lookup results
$lookupResultCount = $addressLookup->getResultCount();

// Retrieving the first lookup result as ChromaX\GoogleGeocode\Result\GeoLookupResult instance
$firstResult = $addressLookup->getFirstResult();

} catch (CommonException\NetworkException\CurlException $exception) { // Google Geocode API is not reachable or curl failed } catch (CommonException\ApiException\InvalidResponseException $exception) { // Google Geocode API unexpected result } catch (CommonException\ApiException\RequestQuotaException $exception) { // Google Geocode API requests over the allowed limit } catch (CommonException\ApiException\NoResultException $exception) { // Google Geocode API request had no result }, <sub>(*7)</sub>

#### Resolving a geo location

The API provides an optional usage of an API key to circumvent API quota limits. Please visit the [Google API console](https://console.developers.google.com/apis/api/geocoding_backend?project=_) to receive an API key.

```{php}
use ChromaX\CommonException;

try{
    // Perform lookup
    $geoLocationLookup = new ChromaX\GoogleGeocode\Lookup\GeoLocationLookup();
    $geoLocationLookup = new Markenwerk\GoogleGeocode\Lookup\GeoLocationLookup();

    // Optional adding an API key
    $geoLocationLookup->setApiKey('MY_GOOGLE_GEOCODING_API_KEY');

    // Submit lookup
    $geoLocationLookup->lookup(54.334123, 10.1364007);

    // Retrieving the lookup as an array of ChromaX\GoogleGeocode\Result\GeoLookupResult instances
    $lookupResults = $geoLocationLookup->getResults();

    // Get the number of lookup results
    $lookupResultCount = $geoLocationLookup->getResultCount();

    // Retrieving the first lookup result as ChromaX\GoogleGeocode\Result\AddressLookupResult instance
    $firstResult = $geoLocationLookup->getFirstResult();

} catch (CommonException\NetworkException\CurlException $exception) {
    // Google Geocode API is not reachable or curl failed
} catch (CommonException\ApiException\InvalidResponseException $exception) {
    // Google Geocode API unexpected result
} catch (CommonException\ApiException\RequestQuotaException $exception) {
    // Google Geocode API requests over the allowed limit
} catch (CommonException\ApiException\NoResultException $exception) {
    // Google Geocode API request had no result
}

Resolving a Google Places ID

Resolving Google Places IDs utilizes the Google Places API. Therefore a Places API key is mandatory for performing a lookup. Please visit the Google API console to receive an API key., <sub>(*8)</sub>

```{php} use ChromaX\CommonException;, <sub>(*9)</sub>

try{ // Perform lookup $googlePlacesLookup = new ChromaX\GoogleGeocode\Lookup\GooglePlacesLookup(); $googlePlacesLookup ->setApiKey('MY_GOOGLE_PLACES_API_KEY') ->lookup('ChIJ_zNzWmpWskcRP8DWT5eX5jQ');, <sub>(*10)</sub>

// Retrieving the lookup as an array of ChromaX\GoogleGeocode\Result\GeoLookupResult instances
$lookupResults = $googlePlacesLookup->getResults();

// Get the number of lookup results
$lookupResultCount = $googlePlacesLookup->getResultCount();

// Retrieving the first lookup result as ChromaX\GoogleGeocode\Result\AddressLookupResult instance
$firstResult = $googlePlacesLookup->getFirstResult();

} catch (CommonException\NetworkException\CurlException $exception) { // Google Geocode API is not reachable or curl failed } catch (CommonException\ApiException\InvalidResponseException $exception) { // Google Geocode API unexpected result } catch (CommonException\ApiException\RequestQuotaException $exception) { // Google Geocode API requests over the allowed limit } catch (CommonException\ApiException\AuthenticationException $exception) { // Google Places service API key invalid } catch (CommonException\ApiException\NoResultException $exception) { // Google Geocode API request had no result }, <sub>(*11)</sub>

---

### Reading from a GeoLookupResult

**Attention:** Plaese note that all getter methods on the `GeoLocationAddress` return a `GeoLocationAddressComponent` instance or `null`. For preventing calls on non-objects the `GeoLocationAddress` class provides methods to check whether the address components exists. 

```{php}
// Retrieving the first lookup result as ChromaX\GoogleGeocode\Result\GeoLookupResult instance
$firstResult = $addressLookup->getFirstResult();

// Retieving address information as ChromaX\GoogleGeocode\GeoLocation\GeoLocationAddress
$geoLocationAddress = $firstResult->getAddress();

if($firstResult->hasAddress()) {

    // Retrieving the address information from the lookup result

    if($firstResult->getAddress()->hasStreetName()) {
        // Returns 'Lornsenstraße'
        $addressStreetShort = $firstResult->getAddress()->getStreetName()->getShortName();
        // Returns 'Lornsenstraße'
        $addressStreetLong = $firstResult->getAddress()->getStreetName()->getLongName();
    }

    if($firstResult->getAddress()->hasStreetNumber()) {
        // Returns '43'
        $addressStreetNumberShort = $firstResult->getAddress()->getStreetNumber()->getShortName();
        // Returns '43'
        $addressStreetNumberLong = $firstResult->getAddress()->getStreetNumber()->getLongName();
    }

    if($firstResult->getAddress()->hasPostalCode()) {
        // Returns '24105'
        $addressPostalCodeShort = $firstResult->getAddress()->getPostalCode()->getShortName();
        // Returns '24105'
        $addressPostalCodeLong = $firstResult->getAddress()->getPostalCode()->getLongName();
    }

    if($firstResult->getAddress()->hasCity()) {
        // Returns 'KI'
        $addressCityShort = $firstResult->getAddress()->getCity()->getShortName();
        // Returns 'Kiel'
        $addressCityLong = $firstResult->getAddress()->getCity()->getLongName();
    }

    if($firstResult->getAddress()->hasArea()) {
        // Returns 'Ravensberg - Brunswik - Düsternbrook'
        $addressAreaShort = $firstResult->getAddress()->getArea()->getShortName();
        // Returns 'Ravensberg - Brunswik - Düsternbrook'
        $addressAreaLong = $firstResult->getAddress()->getArea()->getLongName();
    }

    if($firstResult->getAddress()->hasProvince()) {
        // Returns 'SH'
        $addressProvinceShort = $firstResult->getAddress()->getProvince()->getShortName();
        // Returns 'Schleswig-Holstein'
        $addressProvinceLong = $firstResult->getAddress()->getProvince()->getLongName();
    }

    if($firstResult->getAddress()->hasCountry()) {
        // Returns 'DE'
        $addressCountryShort = $firstResult->getAddress()->getCountry()->getShortName();
        // Returns 'Germany'
        $addressCountryLong = $firstResult->getAddress()->getCountry()->getLongName();
    }

}

if($firstResult->hasGeometry()) {

    // Retrieving the geometry information from the lookup result

    if($firstResult->getGeometry()->hasLocation()) {
        // Returns 54.334123
        $geometryLocationLatitude = $firstResult->getGeometry()->getLocation()->getLatitude();
        // Returns 10.1364007
        $geometryLocationLatitude = $firstResult->getGeometry()->getLocation()->getLongitude();
    }

    if($firstResult->getGeometry()->hasViewport()) {
        // Returns 54.335471980291
        $geometryLocationLatitude = $firstResult->getGeometry()->getViewport()->getNortheast()->getLatitude();
        // Returns 10.137749680292
        $geometryLocationLatitude = $firstResult->getGeometry()->getViewport()->getNortheast()->getLongitude();
        // Returns 54.332774019708
        $geometryLocationLatitude = $firstResult->getGeometry()->getViewport()->getSouthwest()->getLatitude();
        // Returns 10.135051719708
        $geometryLocationLatitude = $firstResult->getGeometry()->getViewport()->getSouthwest()->getLongitude();
    }

}

if($firstResult->hasGooglePlacesId()) {
    // Retrieving the Google Places information from the lookup result
    // Returns 'ChIJ_zNzWmpWskcRP8DWT5eX5jQ'
    $googlePlacesId = $firstResult->getGooglePlacesId();
}

Exception handling

PHP Google Geocoder provides different exceptions provided by the PHP Common Exceptions project for proper handling.
You can find more information about PHP Common Exceptions at Github., <sub>(*12)</sub>

Contribution

Contributing to our projects is always very appreciated.
But: please follow the contribution guidelines written down in the CONTRIBUTING.md document., <sub>(*13)</sub>

License

PHP Google Geocoder is under the MIT license., <sub>(*14)</sub>