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.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
.codeclimate.yml
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE
README.md
composer.json
phpunit.xml.dist

README.md

PHP Google Geocoder

Build Status Test Coverage Dependency Status SensioLabs Insight Code Climate Latest Stable Version Total Downloads License

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.

Installation

{
   	"require": {
        "markenwerk/google-geocoder": "~3.0"
    }
}

Usage

Autoloading and namesapce

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.

use Markenwerk\CommonException;

try{
	// Perform lookup
	$addressLookup = new Markenwerk\GoogleGeocode\Lookup\AddressLookup();

	// 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 Markenwerk\GoogleGeocode\Result\GeoLookupResult instances
	$lookupResults = $addressLookup->getResults();

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

	// Retrieving the first lookup result as Markenwerk\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
}

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 to receive an API key.

use Markenwerk\CommonException;

try{
	// Perform lookup
	$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 Markenwerk\GoogleGeocode\Result\GeoLookupResult instances
	$lookupResults = $geoLocationLookup->getResults();

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

	// Retrieving the first lookup result as Markenwerk\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.

use Markenwerk\CommonException;

try{
	// Perform lookup
	$googlePlacesLookup = new Markenwerk\GoogleGeocode\Lookup\GooglePlacesLookup();
	$googlePlacesLookup
		->setApiKey('MY_GOOGLE_PLACES_API_KEY')
		->lookup('ChIJ_zNzWmpWskcRP8DWT5eX5jQ');

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

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

	// Retrieving the first lookup result as Markenwerk\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
}


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.

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

// Retieving address information as Markenwerk\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.

Contribution

Contributing to our projects is always very appreciated.
But: please follow the contribution guidelines written down in the CONTRIBUTING.md document.

License

PHP Google Geocoder is under the MIT license.