Skip to content
HTTP API for Pelias Geocoder
JavaScript CoffeeScript Other
Branch: master
Clone or download
Pull request Compare This branch is 398 commits ahead, 115 commits behind pelias:master.
vesameskanen Merge pull request #63 from HSLdevcom/update-travis-regex
Make travis regex matching ready for next decade
Latest commit 487ea69 May 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add bash dependency to CircleCI script Oct 30, 2018
bin chore(tests): Update test running script with latest info Sep 12, 2018
controller Merge remote-tracking branch 'pelias/master' into upstream-12-2018 Jan 14, 2019
helper Assign proper name (name.default no longer exists at geojsonify stage) Jan 3, 2019
public Add a link to the OSM Geocoding Guidelines Jun 8, 2018
query Merge remote-tracking branch 'pelias/master' into upstream-12-2018 Jan 14, 2019
routes Use libpostal correctly Dec 28, 2018
sanitizer Merge remote-tracking branch 'pelias/master' into upstream-12-2018 Jan 14, 2019
service Update service/configurations/Interpolation.js Nov 19, 2018
test Remove tests from docker build Jan 14, 2019
.dockerignore Make .dockerignore node-specific Aug 31, 2017
.gitignore Add pids directory to gitignore Sep 11, 2015
.jshintignore remove code-climate hooks Apr 27, 2015
.jshintrc tell eshint we allow ECMA6 functions Nov 2, 2016
.npmrc disable package-lock Nov 14, 2017
.travis.yml Make travis regex matching ready for next decade May 14, 2019
Dockerfile back to std jessie Jan 15, 2019
LICENSE Update LICENSE Apr 9, 2018 feat(docs): update gitter link Nov 22, 2018
app.js Add default route redirecting to /v1 Aug 30, 2017 fixed a typo with org Jan 11, 2017
index.js feat(log): replace console logs with pelias-logger Oct 27, 2018
package.json Remove prune commit hook as it seems to break local npm linking Jan 3, 2019
pelias.json.docker Part of code was moved into config at upstream. Update our own config… Jan 21, 2019 altered startup so that search path is added for azure Jan 11, 2017
schema.js 'Merge remote-tracking branch 'pelias/master' into upstream-12-2018 Dec 27, 2018
translations.json Add Opastinsilta sv translation Feb 21, 2017 touch to wake up travis Sep 7, 2017

This repository is part of the Pelias project. Pelias is an open-source, open-data geocoder originally sponsored by Mapzen. Our official user documentation is here.

Pelias API Server

This is the API server for the Pelias project. It's the service that runs to process user HTTP requests and return results as GeoJSON by querying Elasticsearch and the other Pelias services.




Full documentation for the Pelias API lives in the pelias/documentation repository.

Install Dependencies

The Pelias API has no dependencies beyond Node.js

See Pelias Software requirements for the supported and recommended versions.

npm install


The API ships with several convenience commands (runnable via npm):

  • npm start: start the server
  • npm test: run unit tests
  • npm run ciao: run functional tests (this requires that the server be running)
  • npm run docs: generate API documentation
  • npm run coverage: generate code coverage reports
  • npm run config: dump the configuration to the command line, which is useful for debugging configuration issues

Configuration via pelias-config

The API recognizes the following properties under the top-level api key in your pelias.json config file:

parameter required default description
services no service definitions for point-in-polygon, libpostal, placeholder, and interpolation services. If missing (which is not recommended), the services will not be called.
no default coordinates for focus point
no custom values for which sources and layers the API accepts (more info).
customBoosts no {} Allows configuring boosts for specific sources and layers, in order to influence result order. See Configurable Boosts below for details
autocomplete.exclude_address_length no 0 As a performance optimization, this optional parameter allows excluding address results for queries below the configured length. Addresses are usually the bulk of the records in Elasticsearch, and searching across all of them for very short text inputs can be slow, with little benefit. Consider setting this to 1 or 2 if you have several million addresses in Pelias.
indexName no pelias name of the Elasticsearch index to be used when building queries
attributionURL no (autodetected) The full URL to use for the attribution link returned in all Pelias responses. Pelias will attempt to autodetect this host, but it will often be correct if, for example, there is a proxy between Pelias and its users. This parameter allows setting a specific URL to avoid any such issues
accessLog no name of the format to use for access logs; may be any one of the predefined values in the morgan package. Defaults to "common"; if set to false, or an otherwise falsy value, disables access-logging entirely.
relativeScores no true if set to true, confidence scores will be normalized, realistically at this point setting this to false is not tested or desirable

A good starting configuration file includes this section (fill in the service and Elasticsearch hosts as needed):

  "esclient": {
    "hosts": [{
      "host": "elasticsearch"
  "api": {
    "services": {
      "placeholder": {
        "url": "http://placeholder:4100"
      "libpostal": {
        "url": "http://libpostal:8080"
      "pip": {
        "url": "http://pip-service:4200",
        "timeout": 1000,
        "retries": 2
      "interpolation": {
        "url": "http://interpolation:4300"
  "logger": {
    "level": "debug"

The timeout and retry values, as show in in the pip service section, are optional but configurable for all services (see pelias/microservice-wrapper for more details).

Custom Boosts

The customBoosts config section allows influencing the sorting of results returned from most Pelias queries. Every Pelias record has a source and layer value, and this section allows prioritizing certain sources and layers.

First, keep in mind:

  1. This will not affect all Pelias queries. In particular, when using the /v1/search endpoint, queries for administrative areas (cities, countries, etc) will likely not be affected
  2. Custom boosts allow influencing results, but not completely controlling them. Very good matches that aren't in a boosted source or layer may still be returned first.

The basic form of the configuration looks like this:

    "customBoosts": {
      "layer": {
        "layername": 5,
        "layername2": 3
      "source": {
        "sourcename": 5

There are subsections for both layer and source, and each subsection must be an object. Keys in those objects represent the sources and layers to be boosted, and the value associated with those keys must be a numeric value.

Boost values are essentially multipliers, so values greater than 1 will cause a source or layer to be returned more often, and higher in results. Boosts of the value 1 are the same as no boost, and boosts between 0 and 1 will de-prioritize matching records.

Recommended boost values are between 1 and 5. Higher boosts are likely to cause unexpected impact without really improving results much.

Configuration via Environment variable

Most Pelias configuration is done through pelias-config, however the API has additional environment variables that affect its operation:

environment variable default description
HOST undefined The network interface the Pelias API will bind to. Defaults to whatever the current Node.js default is, which is currently to listen on all interfaces. See the Node.js Net documentation for more info.
PORT 3100 The TCP port the Pelias API will use for incoming network connections.


Please fork and pull request against upstream master on a feature branch. Pretty please; provide unit tests and script fixtures in the test directory.

Unit tests

You can run the unit test suite using the command:

$ npm test

HTTP tests

We have another set of tests which are used to test the HTTP API layer, these tests send expected HTTP requests and then assert that the responses coming back have the correct geoJSON format and HTTP status codes.

You can run the HTTP test suite using the command:

$ npm run ciao

Note: some of the tests in this suite fail when no data is present in the index, there is a small set of test documents provided in ./test/ciao_test_data which can be inserted in order to avoid these errors.

To inject dummy data in to your local index:

$ node test/ciao_test_data.js

You can confirm the dummy data has been inserted with the command:

$ curl localhost:9200/pelias/_count?pretty
  "count" : 9,

Continuous Integration

Travis tests every release against all supported Node.js versions.

Build Status


We rely on semantic-release and Greenkeeper to maintain our module and dependency versions.

Greenkeeper badge

You can’t perform that action at this time.