OpenCage Geocoder Node.js Tutorial

Before we dive in to the tutorial ...

This is a tutorial for using the OpenCage Geocoding API in Node.js. Before you can query the API you will need to sign up for an OpenCage API key.

Once you've done that we recommend you spend five minutes on:

playing with the demo page, so that you see the actual response the API returns.
browsing the API documentation, so you understand the various optional parameters, possible response codes, and the rate limiting on free trial accounts

Ok, ready?

Nodejs packages for accessing the OpenCage Geocoding API

In node.js there are two packages you can use:

opencage-api-client
node-geocoder

Install nodejs package

$ npm install opencage-api-client
# or using yarn
$ yarn add opencage-api-client

opencage-api-client on github opencage-api-client on npm

Set API key

Create a .env file with:

OCD_API_KEY=YOUR-API-KEY

Reverse geocode (coordinates to place)

const opencage = require('opencage-api-client');

opencage.geocode({q: '37.4396, -122.1864', language: 'fr'}).then(data => {
  // console.log(JSON.stringify(data));
  if (data.status.code == 200) {
    if (data.results.length > 0) {
      var place = data.results[0];
      console.log(place.formatted);
      console.log(place.components.road);
      console.log(place.annotations.timezone.name);
    }
  } else if (data.status.code == 402) {
    console.log('hit free-trial daily limit');
    console.log('become a customer: https://opencagedata.com/pricing'); 
  } else {
    // other possible response codes:
    // https://opencagedata.com/api#codes
    console.log('error', data.status.message);
  }
}).catch(error => {
  console.log('error', error.message);
});

// ... prints
// 1330 Middle Avenue, Menlo Park, Californie 94025, États-Unis d'Amérique
// Middle Avenue
// America/Los_Angeles

Forward geocode (address to coordinates)

const opencage = require('opencage-api-client');

opencage.geocode({q: 'Theresienhöhe 11, München'}).then(data => {
  console.log(JSON.stringify(data));
  if (data.status.code == 200) {
    if (data.results.length > 0) {
      var place = data.results[0];
      console.log(place.formatted);
      console.log(place.geometry);
      console.log(place.annotations.timezone.name);
    }
  } else if (data.status.code == 402) {
    console.log('hit free-trial daily limit');
    console.log('become a customer: https://opencagedata.com/pricing'); 
  } else {
    // other possible response codes:
    // https://opencagedata.com/api#codes
    console.log('error', data.status.message);
  }
}).catch(error => {
  console.log('error', error.message);
});

// ... prints
// Theresienhöhe 11, 80339 Munich, Germany
// { lat: 48.1341651, lng: 11.5464794 }
// Europe/Berlin

Install nodejs package

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

node-geocoder on github node-geocoder on npm

Forward geocode (address to coordinates)

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 geocode addresses

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