Install

npm install --save nominatim-geocoder

Why yet another geocoder library ?

I needed a library which respects the Nominatim Usage Policy and is capable of custom api endpoints. Installing Nominatim itself is a pretty simple task and should be considered for a bigger workload.

If you are familiar with docker, nominatim-docker might be worth a look.

Usage

Nominatim Query parameters

Pro tip: In case of well structured data, queries like {country: 'de', postalcode='10115', street='Somestreet XX'} perform much faster than {q: 'Somestreet XX, 10115 Berlin'}

Promises

const Nominatim = require('nominatim-geocoder')
const geocoder = new Nominatim()

geocoder.search( { q: 'Berlin, Germany' } )
    .then((response) => {
        console.log(response)
    })
    .catch((error) => {
        console.log(error)
    })

Callback

The callback function has to be the third argument.

const Nominatim = require('nominatim-geocoder').NominatimCallback
const geocoder = new Nominatim()

geocoder.search( { q: 'Berlin, Germany' }, {}, function(error, response) {
  console.log(error, response)
})

Response

The response will be either an empty array [], or an array with matches.

[{
    "place_id": "159261664",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
    "osm_type": "relation",
    "osm_id": "1402156",
    "boundingbox": ["52.5237693", "52.5401484", "13.3658603", "13.4012965"],
    "lat": "52.53195385",
    "lon": "13.3838001271759",
    "display_name": "Mitte, Berlin, 10115, Deutschland",
    "class": "place",
    "type": "postcode",
    "importance": 0.435
}, ...]

Configuration

Custom API endpoint

You can set customUrl to your endpoint. This will override the host and secure options.

const Nominatim = require('nominatim-geocoder')

const geocoder = new Nominatim({
  delay: 1000, // delay between requests
  secure: false, // enables ssl
  host:'nominatim.openstreetmap.org',
  customUrl: 'http://your-own-nominatim/', // if you want to host your own nominatim
})

Overwrite default query parameters

const Nominatim = require('nominatim-geocoder')

const geocoder = Nominatim({/* No options */}, {
  format: 'json',
  limit: 3,
})

Concurrent requests

You have your own Nominatim Server and synchronous requests are simply to slow ?

const Nominatim = require('nominatim-geocoder')

// Now you'll have 100 concurrent requests
const concurrentRequests = 100
const maxQueueSize = Infinity
Nominatim.setupQueue(concurrentRequests, maxQueueSize)

const geocoder = Nominatim({
    customUrl: 'http://my-nominatim'
})

Memory usage

If you are using concurrent request you'll probably have a lot of data. Just pushing all your data to a queue and hope there is enough heap might work, unless you got >1 million requests to do.

Throtteling the input is a good way to avoid this.

const cursor = mongodb.collection('document').find({})

let workers = 0
const maxWorkers = 200

while (await cursor.hasNext()) {
  const document = await cursor.next()

  // Basically sleep until there are workers available
  // This prevents the queue to be flooded with millions of requests
  while (workers >= maxWorkers) {
    await new Promise(resolve => { setTimeout(resolve, 10) })
  }

  workers += 1
  geocoder.search( { q: document.address } )
    .then(result => {
      workers += -1
    }).catch((error) => {
      workers += -1
    })
}

Good to know

• All requests are cached with the LRU strategy (Least recently used), the datastructure is a HashMap (average complexity O(n))

• Even though search calls are asynchronous, they will be executed one after another via a queue

• All instances of nominatim share the same cache and execution queue. This means the library can be used across modules without being passed down and still adhere to the Nominatim Usage Policy