Code Libraries and Plugins

You can invoke the the OpenCage Geocoding API from your browser's address bar or geocode from the command line using either CURL or wget.

If you want to use the API from within your code, here are a set of libraries that wrap the API for use.

We would love to have libraries for C#, C++, erlang, and angularjs (and really any other language). If you've made any libraries that use our API please let us know via the contact form , we will feature it here.

PHP Wrapper

The PHP wrapper attempts to use the CURL extension to access the API. If CURL support is not available, the library falls back to using fopen wrappers.

Works with PHP version 5.6, 7 and hhvm. To use the wrapper you must either have the CURL extension compiled into your version of PHP or configure the use of fopen wrappers via the allow_url_fopen directive in your php.ini.

The recommended - and easiest way - to install is via Composer. Require the library in your project's composer.json file.

composer require opencage/geocode

Import the Geocoder class.

require "vendor/autoload.php";

Start geocoding

$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
$result = $geocoder->geocode('82 Clerkenwell Road, London');
print_r($result);
You can also access the OpenCage geocoder via William Durand's Geocoder-PHP library. Here is a code sample showing how to query our API using Geocoder.

Python Wrapper

Works with Python version 2 and 3.

Install the module:

pip install opencage

Find an address:

from opencage.geocoder import OpenCageGeocode

key = 'YOUR-API-KEY'
geocoder = OpenCageGeocode(key)

query = "82 Clerkenwell Road, London";
result = geocoder.geocode(query)

Batch geocode a file:

import sys
from opencage.geocoder import OpenCageGeocode

key = 'YOUR-API-KEY'
geocoder = OpenCageGeocode(key)
infilepath = 'cities.txt'

try: 
  with open(infilepath,'r') as f:
    for line in f:
      address = line.strip()
      query = address;
      result = geocoder.geocode(query)

      if result and len(result):
        longitude = result[0]['geometry']['lng']
        latitude  = result[0]["geometry"]["lat"]
        z = "%f;%f;%s" % (latitude, longitude, query)
        print z
      else:
        sys.stderr.write("not found: %s\n" % query)
except IOError:
  print("Error: File does not appear to exist.")
You can also access the OpenCage geocoder via Denis Carriere's geocoder library. Here is a code sample showing how to query our API using python geocoder.

Ruby Wrapper

Install the wrapper's gem:

gem install opencage-geocoder

Or in your Gemfile:

source 'https://rubygems.org'
gem 'opencage-geocoder'

Create an instance of the geocoder, passing a valid API key:

require 'opencage/geocoder'
geocoder = OpenCage::Geocoder.new(api_key: 'YOUR-API-KEY')

geocoder.geocode("82 Clerkenwell Road, London")

You can also access the OpenCage geocoder via ruby geocoder (code sample) or the geokit gem (code sample).

Perl Module

# install with cpanm
$ cpanm Geo::Coder::OpenCage

And then use it like this:

my $Geocoder = Geo::Coder::OpenCage->new(
    api_key => 'YOUR-API-KEY',
);

my $result = $Geocoder->geocode(location => '82 Clerkenwell Road, London');

Leaflet JavaScript Plugin

To use the Leaflet plugin, load the plugin's CSS and JavaScript files:

<link rel="stylesheet" href="http://rawgit.com/opencagedata/leaflet-opencage-search/master/dist/css/L.Control.OpenCageSearch.dev.css" />

<script src="http://rawgit.com/opencagedata/leaflet-opencage-search/master/dist/js/L.Control.OpenCageSearch.dev.js"></script>

Then add the plugin's control to an L.Map instance:

var map = L.map('map').setView([51.52255, -0.10249], 13);
var options = {
  key: 'YOUR-API-KEY',
  limit: 10
};
var control = L.Control.openCageSearch(options).addTo(map);
L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
  attribution: '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

.Net Wrapper

var gc = new Geocoder("YOUR-API-KEY");
var result = gc.Geocode("82 Clerkenwell Road, London");
result.PrintDump(); // ServiceStack human readable object dump to console

var reserveresult = gc.ReverseGeocode(51.4277844, -0.3336517);
reserveresult.PrintDump(); // ServiceStack human readable object dump to console

nodejs package

# install with npm or yarn
$ npm install node-geocoder

And then use it like this:

var NodeGeocoder = require('node-geocoder');
 
var geocoder = NodeGeocoder({
  provider: 'opencage',
  apiKey: 'YOUR-API-KEY'
});

// Using callback
geocoder.geocode('37.4396, -122.1864', function(err, res) {
  console.log(res);
});
geocoder.geocode('29 champs elysée paris', function(err, res) {
  console.log(res);
});

// Or using Promise
geocoder.geocode('37.4396, -122.1864')
.then(function(res) {
  console.log(res);
})
.catch(function(err) {
  console.log(err);
});

// Batch gecoding
geocoder.batchGeocode(['address1', 'address2'], function (err, results) {
  // Return an array of type {error: false, value: []}
  console.log(results) ;
});

Third-party integrations

If you'd like to integrate our geocoder in your software please get in touch via the contact form , we will glaldy feature it here.

Google Docs

Have some long/lats in a Google sheet and want to reverse geocode them? Here's how you do it: Google sheets

GraphHopper

GraphHopper is an open source routing engine. GraphHopper users can use OpenCage as an external geocoding provider.

Traccar

Traccar is a free and open source GPS tracking platform. Traccar users can integrate the OpenCage geocoder as their reverse geocoder.