Node.js Geocoding Tutorial

Install nodejs package

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

Set API key

Create a .env file with:

OPENCAGE_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.results.length > 0) {
      const place = data.results[0];
      console.log(place.formatted);
      console.log(place.components.road);
      console.log(place.annotations.timezone.name);
    } else {
      console.log('status', data.status.message);
      console.log('total_results', data.total_results);
    }
  })
  .catch((error) => {
    console.log('error', error.message);
    if (error.status.code === 402) {
      console.log('hit free trial daily limit');
      console.log('become a customer: https://opencagedata.com/pricing');
    }
  });

// ... 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.results.length > 0) {
      const place = data.results[0];
      console.log(place.formatted);
      console.log(place.geometry);
      console.log(place.annotations.timezone.name);
    } else {
      console.log('Status', data.status.message);
      console.log('total_results', data.total_results);
    }
  })
  .catch((error) => {
    // console.log(JSON.stringify(error));
    console.log('Error', error.message);
    // other possible response codes:
    // https://opencagedata.com/api#codes
    if (error.status.code === 402) {
      console.log('hit free trial daily limit');
      console.log('become a customer: https://opencagedata.com/pricing');
    }
  });

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

Batch geocode a file of addresses

For basic usage, here is an example to batch geocode a file of addresses

Create a file "smaill_file_to_geocode.csv" containing addresses

Madrid,Spain
Milan,Italy
Berlin,Germany

const fs = require('fs');
const { geocode } = require('opencage-api-client');

const infile = 'smaill_file_to_geocode.csv';

const batch = async (lines) => {
  for (let index = 0; index < lines.length; index++) {
    const address = lines[index];
    if (address.trim() !== '') {
      try {
        const apiResult = await geocode({ q: address });
        // NodeJS<14 use : if(apiResult && apiResult.results && apiResult.results.length > 0)
        if (apiResult?.results?.length > 0) {
          const geocoded = apiResult.results[0];
          const latitude = geocoded.geometry.lat;
          const longitude = geocoded.geometry.lng;
          console.log(`${address}, ${latitude}, ${longitude}`);
        }
      } catch (error) {
        console.log(error);
      }
    }
  }
};

fs.readFile(infile, 'utf8', (err, data) => {
  if (err) {
    console.error(err);
    return;
  }
  const lines = data.split(/\r?\n/);

  batch(lines);
});

// ... prints
// Madrid,Spain, 40.4167047, -3.7035825
// Milan,Italy, 45.4668, 9.1905
// Berlin,Germany, 52.5170365, 13.3888599

Running many parallel queries

For large dataset, nodejs and its I/O model allows to quickly process a big amount of data per seconds We prepared a more complex code example, than the previous one above, nodejs parallel batch requests

using a queue, task workers.

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

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

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