pelias-api

library7.7.0jsnpmunverified

Pelias API is the HTTP API server for the Pelias geocoding project (v7.7.0). It processes user requests (search, reverse geocode, autocomplete, etc.) and returns GeoJSON results by querying Elasticsearch and other Pelias microservices. Released on npm with monthly-ish releases, it requires Node.js >=12 and on Docker uses Node 20. Key differentiators: open-source using only open data (OpenStreetMap, OpenAddresses, Who's on First), fully modular design with separate services for interpolation, place parsing, and point-in-polygon. Supports cluster mode, deduplication, and configurable search parameters. Currently active.

http-networking web-framework

npm install pelias-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PELIAS-API

pelias-api

http-networkingjavascriptv7.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PeliasApi

✓ const PeliasApi = require('pelias-api');

✗ import PeliasApi from 'pelias-api';

Package uses CommonJS; no ESM export. Do not use import syntax.

routes

✓ const { routes } = require('pelias-api');

✗ const routes = require('pelias-api').routes;

Destructuring is the common pattern; the package exports an object with 'routes', 'server', etc.

server

✓ const { server } = require('pelias-api');

✗ import { server } from 'pelias-api';

CommonJS only; the 'server' property is a function returning an Express app. Use require.

Initializes a Pelias API server with Elasticsearch configuration and optional default focus point.

const { server } = require('pelias-api'); const app = server({ api: { defaultParameters: { focus: { point: { lat: 40.7128, lon: -74.006 } } } }, elasticsearch: { hosts: ['http://localhost:9200'], apiVersion: '7.0' } }); app.listen(3100, () => { console.log('Pelias API server running on port 3100'); });

Debug

Known issues

breakingNode.js 20 baseimage upgrade required. The Docker baseimage uses Node.js 20.19.4. Node 12 or 14 images will break.

fix

Update to Node.js 20 or use pelias/api Docker image tag >=7.0.0.

affects: >=7.0.0

breakingJSONP middleware removed in v7.7.0. JSONP support is no longer available.

fix

Remove JSONP usage or implement your own JSONP wrapper. Consider using CORS instead.

affects: >=7.7.0

deprecatedElasticsearch 6.x support is deprecated. The API targets Elasticsearch 7.x and may not work with ES 6.

fix

Upgrade Elasticsearch to 7.x. In pelias-config set elasticsearch.apiVersion to '7.0'.

affects: >=6.0.0

gotchaDeduplication uses name comparison ignoring periods. This can cause false positive deduplication for names with periods (e.g. 'St.' matches 'St').

fix

Adjust deduplication logic or override if needed. Periods are stripped before comparison.

affects: >=7.6.0

gotchaCluster mode enabled with 'cluster' feature. When enabled, multiple worker processes share the same port. Ensure your application is idempotent and stateless.

fix

Set PELIAS_CLUSTER environment variable or use config to enable cluster mode. Test thoroughly.

affects: >=7.3.0

Errors

Common errors & fixes

Error: listen EADDRINUSE :::3100

Port 3100 is already in use by another process or another Pelias instance.

fix

Kill the existing process (lsof -ti:3100 | xargs kill -9) or change the port in config.

Error: configuration error: No 'api' section found in pelias.json

The configuration file is missing the top-level 'api' key required by the server.

fix

Add 'api': {} to your pelias.json or ensure PELIAS_CONFIG points to a valid config.

Error: connect ECONNREFUSED 127.0.0.1:9200

Elasticsearch is not running or not reachable on localhost:9200.

fix

Start Elasticsearch service (e.g., systemctl start elasticsearch) or update hosts in config.

Upgrade

Version history

7.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pelias/api ↗

packagehttps://www.npmjs.com/package/pelias-api ↗

homepagehttps://pelias.io ↗