Pelias import pipeline for polyline (road network) data.
Clone or download
missinglink Merge pull request #203 from pelias/detect-pbf-files-without-ls
fix(docker_extract): detect files without using ls
Latest commit f6518a5 Oct 9, 2018

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.

Polyline importer

Greenkeeper badge

Travis CI Status Gitter Chat

The polyline importer facilitates importing road network data in to Pelias from a list of polyline encoded line strings.


  • NodeJS 6 or newer (the latest in the Node 8 series is currently recommended)
  • Elasticsearch 2.3+ (support for version 1.x has been deprecated).

Clone and Install dependencies

Since this module is just one part of our geocoder, we'd recommend starting with our Dockerfiles for quick setup, or our full installation docs to use this module.

$ git clone && cd polylines
$ npm install

Download data

We are still deciding on the best format to publish polyline data for distribution.

Currently there is a single planet-wide road network file which was cut on 8th Jan 2017, download here (1.5GB compressed, 2.3GB uncompressed).

For more information on how the extract was generated, see the wiki article: Generating polylines from Valhalla.

We also have some smaller extracts for testing purposes, a small number were manually cut from pbf for the geographies of our major contributors. See the 'Generating a custom polylines extract from a PBF extract' section below for more info on how you can generate your own extracts:

note: these extracts were generated using a different method from the planet cut above.

Once you have downloaded and extracted the data you will need to follow the Configuration steps below in order to tell Pelias where they can be found.

If you would like to use a different source of polyline data you might need to tweak the defaults in ./stream/pipeline.js, open an issue if you get stuck.


In order to tell the importer the location of your downloads and environmental settings you will first need to create a ~/pelias.json file.

See the config documentation for details on the structure of this file. Your relevant config info for the polyline module might look something like this:

note: the importer currently only supports a single entry in the files array. Also, the config file only accepts "polyline" (without the "s").

  "imports": {
    "polyline": {
      "datapath": "/data",
      "files": [ "road_network.polylines" ]

Administrative Hierarchy Lookup

Polyline data doesn't have a full administrative hierarchy (ie, country, state, county, etc. names), but it can be calculated using data from Who's on First. See the readme for pelias/wof-admin-lookup for more information. By default, adminLookup is enabled. To disable, set imports.adminLookup.enabled to false in Pelias config.

Note: Admin lookup requires loading around 5GB of data into memory.

Running an import

This will start the import process, it will take around 30 seconds to prime it's in-memory data and then you should see regular debugging output in the terminal.

$ PELIAS_CONFIG=<path_to_config_json> npm start

CLI tool

You can use the CLI tool to run imports and for debugging purposes:

note: by default the cli tool will read from stdin and write to stdout.

$ node ./bin/cli.js --help
Usage: cli.js [options]

  --file           read from file instead of stdin
  --config         read filename from pelias config (overrides --file)
  --pretty         indent output (stdout only)
  --db             save to elasticsearch instead of printing to stdout


Run a 'dry-run' of the import process:

node ./bin/cli.js --config --pretty

Import a specific file to elasticsearch:

node ./bin/cli.js --file=/tmp/myfile.polylines --db

Generating a custom polylines extract from a PBF extract

You can generate a custom polylines extract using this OSM PBF tool.

Note: golang 1.9+ is required, please ensure this is correctly installed before continuing.

$ go version
go version go1.10 linux/amd64

$ go get

$ pbf --help

$ wget

$ pbf streets chicago_illinois.osm.pbf | head

yop}nApvc_gDqAywAEast Altgeld Avenue
wto}nAfpl_gDqFuzEEast Altgeld Avenue
_mr}nAbvb~fDkFmQ}BkQ}AkdBEast Altgeld Avenue
mwp}nAt{q~fDKkW]yFi@mDwBcIeS_f@qE}LmDyMwAaH_AoE}C{Uy@mMYaHyCwlDSsFi@iFwEaUEast Altgeld Avenue
smvaoAzxdmfDwbAtyB}cAvzBscAzxBmcAhyB{j@pnAmE|HNorth Navarre Avenue
wq~hoAvt~dgD?hGJfD\fCl@zBr@dBrBbDv@jBx@hCpBtBBbCDnB@`@gBpC]jBEzCF~BL~AdBxH?VKpSHidden Lakes Boulevard
o~cooAb~}xfDn_@i^Taggert Court
{garnA|_~zfDo@qdA}@kEWater Tower Lane
ka|}nAh`jlgDdD{C~MmNrByHTall Grass Court
onvdnAbntyfDpMvOhHtCTall Grass Court

$ pbf streets chicago_illinois.osm.pbf > chicago_illinois.polylines


If you have any issues getting set up or the documentation is missing something, please open an issue here:


Please fork and pull request against upstream master on a feature branch.

Pretty please; provide unit tests and script fixtures in the test directory.

Code Linting

A .jshintrc file is provided which contains a linting config, usually your text editor will understand this config and give you inline hints on code style and readability.

These settings are strictly enforced when you do a git commit, you can execute git commit at any time to run the linter against your code.

Running Unit Tests

$ npm test

Continuous Integration

Travis tests every change against our supported Node.js versions.