opencage/geocode

OpenCage Geocoding API Library for PHP

A PHP library to use the OpenCage geocoding API.

Build Status / Code Quality

Overview

This library uses Guzzle to access the OpenCage Geocoding API. Both synchronous and asynchronous requests are supported.

Authentication

You need an API key, which you can sign up for here.

Tutorial

You can find a comprehensive tutorial for using this module on the OpenCage site.

Working with AI / Agent Skill

There is an Agent Skill for working with the OpenCage Geocoding API which includes a reference file for developing in PHP using this library.

Installation

Requires PHP 8.3 or newer.

With Composer

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";

A complete runnable example is in demo/geocode.php.

Geocoding

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
$result = $geocoder->geocode('82 Clerkenwell Road, London');
print_r($result);

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

Set optional parameters

See the full list at: https://opencagedata.com/api#optional-params

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

Async geocoding

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

// single async request
$promise = $geocoder->geocodeAsync('82 Clerkenwell Road, London');
$result = $promise->wait();
print_r($result);

// concurrent requests
$promises = [
    'london' => $geocoder->geocodeAsync('London'),
    'paris'  => $geocoder->geocodeAsync('Paris'),
    'tokyo'  => $geocoder->geocodeAsync('Tokyo'),
];
$results = \GuzzleHttp\Promise\Utils::unwrap($promises);
print $results['london']['results'][0]['formatted'];
print $results['paris']['results'][0]['formatted'];
print $results['tokyo']['results'][0]['formatted'];

// async reverse geocoding
$promise = $geocoder->geocodeReverseAsync(43.831, 4.360);
$result = $promise->wait();
print $result['results'][0]['formatted'];

Configuration

Set a timeout

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
$geocoder->setTimeout(5); // seconds, default is 10
$result = $geocoder->geocode('82 Clerkenwell Road, London');

Set a proxy URL

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

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
$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
// )

Usage with Laravel

The library works without Laravel, but in a Laravel application it registers itself through package auto-discovery. Add your API key to .env:

OPENCAGE_API_KEY=YOUR-API-KEY

Then use the OpenCage facade, or let Laravel inject a fully configured Geocoder:

use OpenCage;

$result = OpenCage::geocode('82 Clerkenwell Road, London');

use OpenCage\Geocoder\Geocoder;

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

    public function show()
    {
        $result = $this->geocoder->geocodeReverse(43.831, 4.360);
    }
}

Optionally set OPENCAGE_TIMEOUT (in seconds, default 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

Example results

Array
(
    [total_results] => 2
    [status] => Array
        (
            [message] => OK
            [code] => 200
        )
    [results] => Array
        (
            [0] => Array
                (
                    [annotations] => Array
                        (
                            [DMS] => Array
                                (
                                    [lat] => 51° 31' 21.60894'' N
                                    [lng] => 0° 6' 8.95198'' E
                                )

                            [MGRS] => 30UYC0100511930
                            [Maidenhead] => IO91wm75qk
                            [Mercator] => Array
                                (
                                    [x] => -11408.763
                                    [y] => 6680801.955
                                )

                            [OSGB] => Array
                                (
                                    [easting] => 531628.199
                                    [gridref] => TQ 316 821
                                    [northing] => 182177.015
                                )

                            [OSM] => Array
                                (
                                    [url] => http://www.openstreetmap.org/?mlat=51.52267&mlon=-0.10249#map=17/51.52267/-0.10249
                                )

                            [callingcode] => 44
                            [geohash] => gcpvjemm7csmhczg9cvt
                            [sun] => Array
                                (
                                    [rise] => Array
                                        (
                                            [apparent] => 1452931140
                                            [astronomical] => 1452923940
                                            [civil] => 1452928800
                                            [nautical] => 1452926280
                                        )

                                    [set] => Array
                                        (
                                            [apparent] => 1452961320
                                            [astronomical] => 1452968520
                                            [civil] => 1452963660
                                            [nautical] => 1452966120
                                        )

                                )

                            [timezone] => Array
                                (
                                    [name] => Europe/London
                                    [now_in_dst] => 0
                                    [offset_sec] => 0
                                    [offset_string] => 0
                                    [short_name] => GMT
                                )

                            [what3words] => Array
                                (
                                    [words] => gallons.trim.tips
                                )

                        )

                    [bounds] => Array
                        (
                            [northeast] => Array
                                (
                                    [lat] => 51.5227563
                                    [lng] => -0.1023801
                                )

                            [southwest] => Array
                                (
                                    [lat] => 51.5226042
                                    [lng] => -0.1025907
                                )

                        )

                    [components] => Array
                        (
                            [city] => London
                            [country] => United Kingdom
                            [country_code] => gb
                            [house_number] => 82
                            [postcode] => EC1M 5RF
                            [road] => Clerkenwell Road
                            [state] => England
                            [state_district] => Greater London
                            [suburb] => Clerkenwell
                        )

                    [confidence] => 10
                    [formatted] => 82 Clerkenwell Road, London EC1M 5RF, United Kingdom
                    [geometry] => Array
                        (
                            [lat] => 51.52266915
                            [lng] => -0.10248666188363
                        )

                )

            [1] => Array
                (
                    [annotations] => Array
                        (
                            [DMS] => Array
                                (
                                    [lat] => 51° 30' 30.70800'' N
                                    [lng] => 0° 7' 32.66400'' E
                                )

                            [MGRS] => 30UXC9945410295
                            [Maidenhead] => IO91wm42vb
                            [Mercator] => Array
                                (
                                    [x] => -13997.313
                                    [y] => 6678279.278
                                )

                            [OSGB] => Array
                                (
                                    [easting] => 530055.544
                                    [gridref] => TQ 300 805
                                    [northing] => 180563.298
                                )

                            [OSM] => Array
                                (
                                    [url] => http://www.openstreetmap.org/?mlat=51.50853&mlon=-0.12574#map=17/51.50853/-0.12574
                                )

                            [geohash] => gcpvj0u6yjcmwxz8bn43
                            [sun] => Array
                                (
                                    [rise] => Array
                                        (
                                            [apparent] => 1452931140
                                            [astronomical] => 1452923940
                                            [civil] => 1452928800
                                            [nautical] => 1452926340
                                        )

                                    [set] => Array
                                        (
                                            [apparent] => 1452961320
                                            [astronomical] => 1452968520
                                            [civil] => 1452963660
                                            [nautical] => 1452966120
                                        )

                                )

                            [timezone] => Array
                                (
                                    [name] => Europe/London
                                    [now_in_dst] => 0
                                    [offset_sec] => 0
                                    [offset_string] => 0
                                    [short_name] => GMT
                                )

                            [what3words] => Array
                                (
                                    [words] => thing.then.link
                                )

                        )

                    [bounds] => Array
                        (
                            [northeast] => Array
                                (
                                    [lat] => 51.7202301025
                                    [lng] => 0.336111992598
                                )

                            [southwest] => Array
                                (
                                    [lat] => 51.2786598206
                                    [lng] => -0.523222982883
                                )

                        )

                    [components] => Array
                        (
                            [country] => United Kingdom
                            [county] => Greater London
                            [state] => England
                            [town] => London
                        )

                    [confidence] => 1
                    [formatted] => London, Greater London, United Kingdom
                    [geometry] => Array
                        (
                            [lat] => 51.50853
                            [lng] => -0.12574
                        )

                )

        )
)

Copyright

Copyright (c) OpenCage GmbH. See LICENSE for details.

Who is OpenCage GmbH?

We run a worldwide geocoding API and geosearch service based on open data. Learn more about us.

We also run Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.

-- end --