PHPackages                             chroma-x/google-geocoder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. chroma-x/google-geocoder

ActiveLibrary[API Development](/categories/api)

chroma-x/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.

3.0.5(5y ago)386[1 issues](https://github.com/chroma-x/php-google-geocoder/issues)MITPHPPHP >=5.3CI failing

Since Apr 22Pushed 5y ago1 watchersCompare

[ Source](https://github.com/chroma-x/php-google-geocoder)[ Packagist](https://packagist.org/packages/chroma-x/google-geocoder)[ Docs](http://chroma-x.de/)[ RSS](/packages/chroma-x-google-geocoder/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (5)Versions (18)Used By (0)

PHP Google Geocoder
===================

[](#php-google-geocoder)

[![Build Status](https://camo.githubusercontent.com/d16221dcd381667512a76465a0ccfb3df3edc39a095dac0be8fa6b6ac9d1b56b/68747470733a2f2f7472617669732d63692e6f72672f6368726f6d612d782f7068702d676f6f676c652d67656f636f6465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/chroma-x/php-google-geocoder)[![Test Coverage](https://camo.githubusercontent.com/27b3d46a9e2461b42cd10239534a8607758a6e8c9fcad60d443a236c81f29d91/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6368726f6d612d782f7068702d676f6f676c652d67656f636f6465722f6261646765732f636f7665726167652e737667)](https://codeclimate.com/github/chroma-x/php-google-geocoder/coverage)[![Dependency Status](https://camo.githubusercontent.com/249c0a0462861cd0f1d733bf2ac8389bfee11a258ce1936fbb3d36d50516e75d/68747470733a2f2f7777772e76657273696f6e6579652e636f6d2f757365722f70726f6a656374732f3537316637383431666364313961303034353434323333662f62616467652e737667)](https://www.versioneye.com/user/projects/571f7841fcd19a004544233f)[![Code Climate](https://camo.githubusercontent.com/92b8097f2cfc70dfa6febd1b4f66802377c55172b528f17eca01268c1c05bd20/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6368726f6d612d782f7068702d676f6f676c652d67656f636f6465722f6261646765732f6770612e737667)](https://codeclimate.com/github/chroma-x/php-google-geocoder)[![Latest Stable Version](https://camo.githubusercontent.com/3769e2ca812e044b3e588c38c4ca314013da7f5a8e36ddb88d09a3b372c28dc5/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f676f6f676c652d67656f636f6465722f762f737461626c65)](https://packagist.org/packages/chroma-x/google-geocoder)[![Total Downloads](https://camo.githubusercontent.com/629265c2901231cf4f7d8390e851e71d4d47a19604b1a70f865eec3afffc5b1f/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f676f6f676c652d67656f636f6465722f646f776e6c6f616473)](https://packagist.org/packages/chroma-x/google-geocoder)[![License](https://camo.githubusercontent.com/2e8e9d647e51bd82969450491726d31d2aa949af9445e784137ac1b4193cf457/68747470733a2f2f706f7365722e707567782e6f72672f6368726f6d612d782f676f6f676c652d67656f636f6465722f6c6963656e7365)](https://packagist.org/packages/chroma-x/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.

Installation
------------

[](#installation)

```
{
   	"require": {
        "chroma-x/google-geocoder": "~3.0"
    }
}

```

Usage
-----

[](#usage)

### Autoloading and namesapce

[](#autoloading-and-namesapce)

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

```

---

### Performing a GeoLookup

[](#performing-a-geolookup)

#### Resolving an address

[](#resolving-an-address)

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.

```
use ChromaX\CommonException;

try{
	// Perform lookup
	$addressLookup = new ChromaX\GoogleGeocode\Lookup\AddressLookup();
	$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 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
}

```

#### Resolving a geo location

[](#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.

```
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-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](https://console.developers.google.com/apis/api/geocoding_backend?project=_) to receive an API key.

```
use ChromaX\CommonException;

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

	// 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
}

```

---

### Reading from a GeoLookupResult

[](#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 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
------------------

[](#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](https://github.com/chroma-x/php-common-exceptions).

Contribution
------------

[](#contribution)

Contributing to our projects is always very appreciated.
**But: please follow the contribution guidelines written down in the [CONTRIBUTING.md](https://github.com/chroma-x/php-google-geocoder/blob/master/CONTRIBUTING.md) document.**

License
-------

[](#license)

PHP Google Geocoder is under the MIT license.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity67

Established project with proven stability

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~108 days

Recently: every ~412 days

Total

17

Last Release

1946d ago

Major Versions

1.6 → 2.02016-04-26

2.2.0 → 3.0.02016-07-11

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/5921241?v=4)[Martin Brecht-Precht](/maintainers/bonscho)[@Bonscho](https://github.com/Bonscho)

---

Tags

composer-packagegeocodergeolocationgooglelookupphp-libraryreverse-lookupgooglegeolocationgeolookup

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chroma-x-google-geocoder/health.svg)

```
[![Health](https://phpackages.com/badges/chroma-x-google-geocoder/health.svg)](https://phpackages.com/packages/chroma-x-google-geocoder)
```

###  Alternatives

[google/apiclient

Client library for Google APIs

9.8k191.4M997](/packages/google-apiclient)[geoip2/geoip2

MaxMind GeoIP2 PHP API

2.5k85.4M294](/packages/geoip2-geoip2)[google/apiclient-services

Client library for Google APIs

1.3k180.5M51](/packages/google-apiclient-services)[google/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)[revolution/laravel-google-sheets

Google Sheets API v4

4483.1M6](/packages/revolution-laravel-google-sheets)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)