Pelias API Server

7.7.0 verified Sat May 09 auth: no javascript

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.

Common errors

error Error: listen EADDRINUSE :::3100 ↓

cause 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 Error: configuration error: No 'api' section found in pelias.json ↓

cause 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 Error: connect ECONNREFUSED 127.0.0.1:9200 ↓

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

fix

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

Warnings

breaking Node.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.

breaking JSONP 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.

deprecated Elasticsearch 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'.

gotcha Deduplication 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.

gotcha Cluster 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.

Install

npm install pelias-api

yarn add pelias-api

pnpm add pelias-api

Imports

PeliasApi
wrong
```
import PeliasApi from 'pelias-api';
```
correct
```
const PeliasApi = require('pelias-api');
```
Package uses CommonJS; no ESM export. Do not use import syntax.
routes
wrong
```
const routes = require('pelias-api').routes;
```
correct
```
const { routes } = require('pelias-api');
```
Destructuring is the common pattern; the package exports an object with 'routes', 'server', etc.
server
wrong
```
import { server } from 'pelias-api';
```
correct
```
const { server } = require('pelias-api');
```
CommonJS only; the 'server' property is a function returning an Express app. Use require.

Quickstart

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