0.1.4 • Public • Published


    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.


    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'}


    const Nominatim = require('nominatim-geocoder')
    const geocoder = new Nominatim() { q: 'Berlin, Germany' } )
        .then((response) => {
        .catch((error) => {


    The callback function has to be the third argument.

    const Nominatim = require('nominatim-geocoder').NominatimCallback
    const geocoder = new Nominatim() { q: 'Berlin, Germany' }, {}, function(error, response) {
      console.log(error, 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:\/\/\/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
    }, ...]


    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
      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
      // 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 { 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


    npm i nominatim-geocoder

    DownloadsWeekly Downloads






    Last publish


    • thomas.nordquist