Topics covered in this tutorial
- General Background
- Agent Skill
- Libraries
- Forward geocoding
- Reverse geocoding
- Geocoding a list of places
- Running requests in parallel
- Usage with Laravel
- Further reading
Background
Before we dive in to the tutorial
- Sign up for an OpenCage geocoding API key.
- Play with the demo page, so that you see the actual response the API returns.
- Browse the API reference, so you understand the optional parameters, best practices, possible response codes, and the rate limiting on free trial accounts.
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
$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";
2,500 geocoding API requests/day - No credit card required