PHP wrapper for the Address encoding library.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
phpunit.xml.dist PHP

Build Status

Thin PHP wrapper for geocoding API that includes a service provider for Laravel.


  • Geocode an individual address
  • Batch geocode up to 10,000 addresses at a time
  • Parse an address into its identifiable components

Read the complete geocoding API for service documentation.

Installing via Composer

The recommended way to install PHP is through Composer.

# Install Composer
curl -sS | php

# Add Geocodio as a dependency
php composer.phar require stanley/geocodio-php:~1.0

After installing, you need to require Composer's autoloader:



Using the PHP library is super simple.

use Stanley\Geocodio\Client;

// Create the new Client object by passing in your api key
$client = new Client('YOUR_API_KEY');

Note: Create an API key by signing up at

Geocode single address

To encode a single address, simply pass a string to the geocode function.

$data = '123 Anywhere St, Chicago, IL';
$result = $client->geocode($data);

Geocode multiple addresses

For multiple addresses, you can pass an array of addresses to the same geocode function.

$data = [
  '123 Anywhere St, Chicago, IL',
  '456 Oak St, Los Angeles, CA'
$result = $client->geocode($data);

Up to 10,000 addresses can be geocoded in a single batch request

Reverse geocoding a single coordinate also supports reverse geocoding. To convert a single lat/long pair into an address, call the 'reverse' method.

The lat/long pairs should be separateed by a comma.

$data = '35.9746000,-77.9658000';
$result = $client->reverse($data);

Reverse geocoding multiple coordinates

To do a batch conversion, pass your lat/long pairs in an array.

$data = [
$result = $client->reverse($data);


Geocoding and reverse geocoding requests accepts an optional second parameter for fields.

$data = '123 Anywhere St, Chicago, IL';
$result = $client->geocode($data, ['cd', 'stateleg']);
$data = "35.9746000,-77.9658000";
$result = $client->reverse($data, ['cd', 'stateleg']);
$data = [
  '123 Anywhere St, Chicago, IL',
  '456 Oak St, Los Angeles, CA'
$result = $client->geocode($data, ['cd', 'stateleg']);

Return Values

The PHP client will return an instance of the Stanley\Geocodio\Data class. The raw response body can be accessed from the response property. This property had the response data stored as an object.

$body = $address->response;

Laravel Service Provider and Facade

A service provder and facade are available if you are using Laravel. Once you've added the package to your composer.json file, run php composer.phar update. Add 'Stanley\Geocodio\ServiceProviders\LaravelServiceProvider'to the providers key. Then, edit the aliases key and add 'Geocodio' => 'Stanley\Geocodio\Geocodio' to the array.

You are now ready to use the Facade. If you are using Laravel, you will need to pass your API Key as the third parameter.

$fields = [];
$key = 'YOUR_API_KEY';
$data = Geocodio::get('123 Anywhere St, Chicago, IL', $fields, $key);
return response()->json($data);


Periodically, the service will return errors.

To handle these:

  • An HTTP 403 error raises a GeocodioAuthError
  • An HTTP 422 error raises a GeocodioDataError and the error message will be reported through the exception
  • An HTTP 5xx error raises a GeocodioServerError
  • An unmatched non-200 response will simply raise Exception


The original library was written by David Stanley. Much of this readme and the structure of this library was inspired by the Py-Geocodio Library by Ben Lopatin.