addok-cluster

addok-cluster

A very fast and efficient way to use addok geocoding capabilities in your Node.js process.

Features

• Manage multiple addok nodes
• Fluent JavaScript API
• 30% more efficient than HTTP calls
• Fast priority queue (high, medium, low)
• Supports AbortController
• Auto-restart nodes
• Handle multiple Redis databases (round robin)
• Managed Redis server (optional)

Prerequisites

• Node.js 20 LTS and above
• Be able to use ESM
• A working environment for addok (Python, Redis, dependencies…)

Install

npm install addok-cluster

Configure

import {createCluster} from 'addok-cluster'

const cluster = await createCluster(options)

Environment variable name	Option name	Description
PYTHON_PATH	pythonPath	Path to python executable to use
ADDOK_CLUSTER_NUM_NODES	numNodes	Number of nodes to instantiate (default to number of CPUs)
ADDOK_CONFIG_MODULE	addokConfigModule	Path to addok configuration file
ADDOK_REDIS_URL	addokRedisUrl	Connection string to addok Redis instance (can be an array)
ADDOK_REDIS_DATA_DIR	redisDataDir	Path to Redis data directory (enable managed Redis)
ADDOK_REDIS_STARTUP_TIMEOUT	redisStartupTimeout	Duration in milliseconds allowed to Redis to start (managed Redis only)

Use

Geocode

const params = {
  q: '1 rue de la paix 75002 Paris',
  autocomplete: false,
  lon: null,
  lat: null,
  limit: 5,
  filters: {
    postcode: '75002',
    citycode: '75102'
  }
}

const options = {
  priority: 'medium',
  signal: null
}

const results = await cluster.geocode(params, options)

Param	Description	Default
q	Text input to geocode (required)
autocomplete	Auto-complete mode (boolean)	false
lon, lat	Coordinates of reference position
limit	Number of returned results	5
filters	Additional filters (depend on addok config)	{}

Multiple filter values

Filter values can be provided as a string (single value) or as an array of strings (multiple values with OR logic):

const params = {
  q: 'rue de la paix',
  filters: {
    // Single value (backward compatible)
    type: 'street',
    // Multiple values (OR logic)
    postcode: ['75001', '75002', '75003']
  }
}

Reverse geocode

const params = {
  lon: null,
  lat: null,
  limit: 5,
  filters: {
    type: 'housenumber'
  }
}

const options = {
  priority: 'high',
  signal: null
}

const results = await cluster.reverse(params, options)

Param	Description	Default
lon, lat	Coordinates of reference position (required)
limit	Number of returned results	5
filters	Additional filters (depend on addok config)	{}

Filter values can be provided as a string (single value) or as an array of strings (multiple values with OR logic). See the Multiple filter values section for more details.

Options

priority: low | medium (default) | high

Define the priority level of the request. Requests are processed following FIFO rule, from high to low.

signal: AbortSignal instance (optional)

If an AbortSignal instance is provided, its status is checked just before forwarding to addok.

Stop cluster

cluster.end()

Sponsorship

This software is maintained by Living Data, thanks to the support of partners such as Etalab (API Adresse) and IGN (Géoplateforme).