PHP Geocoding Tutorial

This is a tutorial for using the OpenCage geocoding API in PHP.

Topics covered in this tutorial

Background

The code examples below will use your geocoding API key once you log in.

Before we dive in to the tutorial

  1. Sign up for an OpenCage geocoding API key.
  2. Play with the demo page, so that you see the actual response the API returns.
  3. Browse the API reference, so you understand the optional parameters, best practices, possible response codes, and the rate limiting on free trial accounts.
Working with AI?

We offer an Agent Skill to make it easy for AI to quickly learn about our geocoding API.

Agent Skill / Working with AI

Are you developing with AI?

We offer an Agent Skill that includes a reference file specifically about developing code to access our API via PHP.

PHP libraries for accessing the OpenCage Geocoding API

There are two PHP libraries you can use:

The library uses the Guzzle HTTP client (version 7 or 8) to access the API. Both synchronous and asynchronous (parallel) requests are supported. In a Laravel application it registers itself automatically.

PHP 8.3 or newer is required. On PHP 8.2 Composer installs the 4.0.x series, and for PHP 8.0 or 8.1 use the 3.x series of the library.

Install via Composer. Require the library in your project's composer.json file.

composer require opencage/geocode

Import the Geocoder class.

require "vendor/autoload.php";

Geocode an address (forward geocoding)

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
# no need to URI encode the query, the library does this for you
$result = $geocoder->geocode('82 Clerkenwell Road, London, UK');
print_r($result);

Geocode coordinates (reverse geocoding)

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
$result = $geocoder->geocodeReverse(43.831, 4.360); # latitude, longitude
print $result['results'][0]['formatted'];
# 3 Rue de Rivarol, 30020 Nîmes, France

Batch geocode addresses

To geocode a long list faster, run the requests in parallel.

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');

$addresses = ['London', 'Paris, France', 'Berlin'];
$results = [];

foreach ($addresses as $address) {
    $result = $geocoder->geocode($address);
    if ($result['status']['code'] === 200) {
        $results[$address] = $result;
    } else {
        error_log("failed to geocode '$address' : " . $result['status']['message']);
    }
}

Set optional parameters

See the full list

$result = $geocoder->geocode('6 Rue Massillon, 30020 Nîmes, France', [
    'language' => 'fr',
    'countrycode' => 'fr'
]);
if ($result && $result['total_results'] > 0) {
  $first = $result['results'][0];
  print $first['geometry']['lng'] . ';' . $first['geometry']['lat'] . ';' . $first['formatted'] . "\n";
  // 4.360081;43.8316276;6 Rue Massillon, 30020 Nîmes, France
}

Configuration

Set a request timeout (in seconds, the default is 10).

$geocoder->setTimeout(5);

Set a proxy URL. The URL must include a scheme (http, https, socks5 or socks5h) and a host, and must be set before calling geocode(). With socks5h the proxy also resolves the hostname, so no DNS lookup happens outside the proxy.

$geocoder->setProxy('https://proxy.example.com:1234');
$result = $geocoder->geocode("Brandenburger Tor, Berlin");
print_r($result['results'][0]['formatted']);
// Brandenburger Tor, Unter den Linden, 10117 Berlin, Germany
print_r($result['results'][0]['geometry']);
// Array
// (
//    [lat] => 52.5166047
//    [lng] => 13.3809897
// )

Geocoding faster by running queries in parallel

The library can run multiple requests concurrently using its asynchronous methods, which is much faster than geocoding a list one at a time.

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');

# a single async request returns a promise
$promise = $geocoder->geocodeReverseAsync(51.5074, -0.1278);
$result = $promise->wait();

# run several reverse geocoding requests concurrently
$promises = [
    'london' => $geocoder->geocodeReverseAsync(51.5074, -0.1278),
    'paris'  => $geocoder->geocodeReverseAsync(48.8566, 2.3522),
    'tokyo'  => $geocoder->geocodeReverseAsync(35.6762, 139.6503),
];
$results = \GuzzleHttp\Promise\Utils::unwrap($promises);
print $results['london']['results'][0]['formatted'];

Free trial keys are limited to one request per second. To stay within that limit, send the requests in chunks and pause between each chunk. Raise $chunkSize if your plan allows a higher rate.

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');

$addresses = [
    '82 Clerkenwell Road, London, EC1M 5RF, UK',
    '6 Rue Massillon, 30020 Nîmes, France',
    'Brandenburger Tor, 10117 Berlin, Germany',
    'Plaza Mayor, 28012 Madrid, Spain',
];

$chunkSize = 1;
$results = [];

foreach (array_chunk($addresses, $chunkSize) as $chunk) {
    $promises = [];
    foreach ($chunk as $address) {
        $promises[$address] = $geocoder->geocodeAsync($address);
    }
    # wait for this chunk to finish before starting the next one
    $results += \GuzzleHttp\Promise\Utils::unwrap($promises);

    sleep(1); # pause before the next chunk
}

foreach ($results as $address => $result) {
    if ($result['status']['code'] !== 200) {
        error_log("failed to geocode '$address' : " . $result['status']['message']);
    } elseif (empty($result['results'])) {
        print $address . " => no results\n";
    } else {
        print $address . ' => ' . $result['results'][0]['formatted'] . "\n";
    }
}

Before you start geocoding at high volume, please read our guide to geocoding large datasets where we explain various strategies and points to consider.

Usage with Laravel

The library works without Laravel, but in a Laravel application it registers itself through package auto-discovery, so there is no service provider to add. Put your API key in .env:

OPENCAGE_API_KEY=YOUR-API-KEY

Then use the OpenCage facade, which offers the same methods as the Geocoder class, including the asynchronous ones.

use OpenCage;

$result = OpenCage::geocode('82 Clerkenwell Road, London, UK');
print $result['results'][0]['formatted'];

Or let Laravel inject a fully configured Geocoder.

use OpenCage\Geocoder\Geocoder;

class PlaceController
{
    public function __construct(private Geocoder $geocoder)
    {
    }

    public function show()
    {
        $result = $this->geocoder->geocodeReverse(43.831, 4.360);
        return $result['results'][0]['formatted'];
    }
}

Optionally set OPENCAGE_TIMEOUT (in seconds, the default is 10) and OPENCAGE_PROXY in .env. To change the configuration in code instead, publish the config file to config/opencage.php:

php artisan vendor:publish --tag=opencage-config


Install via Composer. The OpenCage provider is a separate package that pulls in the core willdurand/geocoder library. It doesn't include an HTTP client, so require one as well, for example Guzzle.

composer require geocoder-php/open-cage-provider guzzlehttp/guzzle

Import the classes.

require "vendor/autoload.php";

use GuzzleHttp\Client as GuzzleClient;
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;

Geocode an address (forward geocoding)

$client   = new GuzzleClient();
$provider = new \Geocoder\Provider\OpenCage\OpenCage($client, 'YOUR-API-KEY');
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$results = $geocoder->geocodeQuery(GeocodeQuery::create('1 Hacker Way, Menlo Park, 94025'));
# print_r($results);

$coords = $results->first()->getCoordinates();

echo json_encode([ 'lat' => $coords->getLatitude(), 'lon' => $coords->getLongitude() ]) . "\n";

Batch geocode addresses

The provider reports errors, such as an invalid API key or an exceeded quota, by throwing exceptions.

$client   = new GuzzleClient();
$provider = new \Geocoder\Provider\OpenCage\OpenCage($client, 'YOUR-API-KEY');
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$addresses = ['London', 'Paris', 'Berlin'];
$results = [];

foreach ($addresses as $address) {
    try {
        $results[$address] = $geocoder->geocodeQuery(GeocodeQuery::create($address));
    } catch (\Geocoder\Exception\Exception $e) {
        error_log("failed to geocode '$address' : " . $e->getMessage());
    }
}

Geocode coordinates (reverse geocoding)

$client   = new GuzzleClient();
$provider = new \Geocoder\Provider\OpenCage\OpenCage($client, 'YOUR-API-KEY');
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');

$results = $geocoder->reverseQuery(ReverseQuery::fromCoordinates(37.4856225, -122.1468803));
# print_r($results);

echo $results->first()->getStreetName() . "\n";

Start your free trial

2,500 geocoding API requests/day - No credit card required