Code Libraries and Plugins

You can invoke the the OpenCage geocoder 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 would love to feature it here.

PHP Wrapper

While there is a stand alone library, you can also access the OpenCage geocoder via William Durand's Geocoder-PHP library.

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

Python Wrapper

Works with Python version 2 and 3.

Please note, while there is a stand alone module, you can also access the OpenCage geocoder via the popular geopy library, or Denis Carriere's geocoder library.

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.")

Ruby Wrapper

Please note, while there is a stand alone opencage-geocoder gem, you can also access the OpenCage geocoder via ruby geocoder or the geokit gem.

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

Perl Module

Geo::Coder::OpenCage is available on CPAN. Install it like so:

# with cpan or cpanm
$ cpanm Geo::Coder::OpenCage

And then use it like so:

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

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.