How pelias/api works
Project Type and Purpose
• This is a Node.js/Express API server (Pelias API) providing HTTP endpoints for geocoding and reverse-geocoding.
• It receives REST requests (autocomplete, search, reverse, place), processes them via a modular pipeline, queries Elasticsearch, and enriches results by calling other Pelias microservices (libpostal, placeholder, pip, interpolation).
• It’s an open-source search engine that returns GeoJSON results.
File Structure Analysis
• Top-level files:
• app.js / index.js – Express app entry-point
• bin/ – startup scripts (generate docs, start server, register unit tests)
• Dockerfile / .github – CI and container configuration
• Core directories:
• routes/ – defines API routes (v1 endpoints, default routes)
• middleware/ – Express middleware chain (CORS, logging, parsing, normalization, scoring, trimming, JSONP, error handling)
• controller/ – orchestrates per-endpoint logic, applies predicates, transforms Markdown, calls query builder
• query/ – builds Elasticsearch query bodies, includes parsers and default parameter files, view helpers
• service/ – high-level operations: configuration discovery, multi-get, search wrapper
• sanitizer/ – input validation and sanitization for each endpoint
• helper/ – utility functions (type mapping, geojson conversion, logging, unicode)
• test/ – unit tests and functional (CIAO) tests with fixtures
• Configuration:
• Uses pelias-config via environment variable or pelias.json
• package.json scripts (start, test, ciao, docs, coverage, config)
a. Clients and Load Balancers
• External HTTP clients (web/mobile/other servers)
• Optional: reverse proxy/load balancer (NGINX, HAProxy)
b. API Server (Node.js / Express)
• Entry-point: app.js initializes Express, mounts routes
• Routes layer: routes/v1.js, default.js define endpoint paths
• Middleware pipeline: every request passes sequential middleware modules (cors → access_log → parseBBox → confidenceScore → … → sendJSON → 404/500 handlers)
• Controllers: one per endpoint (search.js, autocomplete.js, reverse.js, place.js, structured_libpostal.js, coarse_reverse.js)
• Sanitizer: input validation modules invoked before controllers
• Query builder: query/*.js builds Elasticsearch DSL based on sanitized input
• Service layer: service/search.js, service/mget.js abstracts calls to Elasticsearch; service/configurations for auto-discovery of sources/layers
• Microservice clients: via service/configurations or helper modules, HTTP calls to Pelias services:
– libpostal (address parser)
– placeholder (fill missing address components)
– pip-service (point-in-polygon lookup for administrative hierarchies)
– interpolation (street number interpolation)
• Elasticsearch cluster: stores and indexes place data
• Response formatter: helper/geojsonify* builds GeoJSON output
c. External Dependencies
• Elasticsearch cluster (could be a cluster of nodes behind a load balancer)
• Pelias microservices (libpostal, placeholder, pip, interpolation)
• Optional: Monitoring/logging services
Relationships and Data Flow
1. HTTP Client → Load Balancer → API Server (app.js)
2. API Server:
• routes → middleware sequence (authentication, logging, validation, normalization, scoring, dedupe, trimming)
• controller (decide which query to run) → sanitizer (validate input) → query builder (compose ES DSL)
• service layer → Elasticsearch (HTTP JSON)
• optionally call external Pelias microservices (HTTP JSON)
• service layer merges results → controller formats → middleware sendJSON → HTTP response
3. API Server logs and error handlers manage failures and diagnostics
Architectural Patterns and Design Principles
• Layered architecture: clear separation (routes → middleware → controllers → services → datastore)
• Modular, pluggable middleware for cross-cutting concerns
• Predicate-based controllers (controller/predicates) drive conditional logic
• Dependency inversion: service/configurations abstract external service URLs and retries
• Auto-discovery pattern for dynamic configuration of Elasticsearch sources and layers
Technologies and Frameworks
• Node.js and Express.js for server framework
• Elasticsearch (RESTful JSON API) as primary datastore
• Pelias microservices: libpostal, placeholder, pip, interpolation (HTTP services)
• Docker for containerization and Dockerfile in repo
• pelias-config for centralized configuration management
• Mocha/CoffeeScript/CIAO for unit and HTTP functional testing