Pelias is a geocoder powered completely by open data, available freely to everyone.
Local Installation · Cloud Webservice · Documentation · Community Chat
What is Pelias?
Pelias is a search engine for places worldwide, powered by open data. It turns addresses and place names into geographic coordinates, and turns geographic coordinates into places and addresses. With Pelias, you’re able to turn your users’ place searches into actionable geodata and transform your geodata into real places.
We think open data, open source, and open strategy win over proprietary solutions at any part of the stack and we want to ensure the services we offer are in line with that vision. We believe that an open geocoder improves over the long-term only if the community can incorporate truly representative local knowledge.
Lightweight spatial service used by Pelias — provides point-in-polygon (PIP) lookups, geometry, relationships and ontology data via a small HTTP API and demo pages.
All endpoints are GET endpoints unless noted. See server/routes/* for parameter details and exact output shape.
-
GET
/place/:source/:idReturn place metadata by source and id. -
GET
/place/:source/:id/geometryReturn all geometry roles for the place. -
GET
/place/:source/:id/geometry/:roleReturn geometry for a specific role (e.g.intersection,shape, etc.). -
GET
/place/:source/:id/relationship/intersectsReturn places that intersect the given place. -
GET
/place/:source/:id/relationship/containsReturn places that contain the given place. -
GET
/place/:source/:id/relationship/withinReturn places within the given place. -
GET
/place/:source/:id/propertyReturn properties for the place. -
GET
/place/:source/:id/nameReturn names for the place. -
GET
/place/:source/:id/hierarchyReturn the administrative hierarchy for the place. -
GET
/query/pipPoint-in-polygon lookup (compact view). Query parameters are handled by the pip route implementation in server/routes/pip.js. -
GET
/query/pip/verbosePoint-in-polygon lookup (verbose view), returns detailed match records. -
GET
/query/pip/_view/pelias/:lon/:latPelias-compatible PIP view (legacy Pelias format).- Path params: lon, lat
- Query params:
layers(comma-separated list) is supported by the Pelias view implementation and filters the output layers. See server/routes/pip_pelias.js for details.
-
GET
/query/searchGeneral spatial search endpoint (see server/routes/search.js for supported query parameters). -
GET
/ontologyReturn top-level ontology index. -
GET
/ontology/:classReturn ontology entries for a class. -
GET
/ontology/:class/:typeReturn ontology entries for a class/type pair.
Demo pages and utilities:
- GET
/explore(static demo UI at server/demo) - GET
/explore/place/:source/:id - GET
/explore/pip - GET
/explore/ontology - GET
/explore/ontology/:class/:type
Root:
- GET
/redirects to/explore/pip
Pelias PIP view (Pelias-compatible response):
curl -s "http://localhost:3000/query/pip/_view/pelias/170.97/-45.09?layers=locality,region"
Simple place lookup:
curl -s "http://localhost:3000/place/whosonfirst/85633345"
# build image
docker build -t 'pelias/spatial' .# run environment checks
docker run --rm -it \
--entrypoint=npm \
pelias/spatial \
run env_check# run tests
docker run --rm -it \
--entrypoint=npm \
pelias/spatial \
test# generate code coverage report
docker run --rm -it \
--entrypoint=npm \
pelias/spatial \
run coverage# create empty spatial database
docker run --rm -i \
-v "${PWD}:/data" \
pelias/spatial \
import whosonfirst --db=/data/empty.db --file=/dev/null# merge two databases
docker run --rm -i \
-v "${PWD}:/data" \
pelias/spatial \
merge --db=/data/empty.db /data/external.db# run whosonfirst import
# note: database sourced from https://dist.whosonfirst.org/sqlite/
ingress() {
WOFDB='/data/wof/sqlite/whosonfirst-data-admin-nz-latest.db'
EXTRACT_QUERY='SELECT json_extract(body, "$") FROM geojson'
sqlite3 "${WOFDB}" "${EXTRACT_QUERY}"
}
ingress | docker run --rm -i \
-v "${PWD}:/data" \
pelias/spatial \
import whosonfirst --db=/data/geo.docker.db# run openstreetmap import
# note: data generated using https://docs.osmcode.org/osmium/latest/
ingress() {
EXTRACT_FILE='osmium.extract.geojsonl.gz'
gzcat "${EXTRACT_FILE}"
}
ingress | docker run --rm -i \
-v "${PWD}:/data" \
pelias/spatial \
import osmium --db=/data/geo.docker.db# start the HTTP server on port 3000
docker run --rm -it \
-v "${PWD}:/data" \
-p 3000:3000 \
pelias/spatial \
server --db=/data/geo.docker.db# run point-in-polygon query
docker run --rm -i \
-v "${PWD}:/data" \
pelias/spatial \
pip --db=/data/geo.docker.db 174.766843 -41.288788Install dependencies from homebrew (macos):
# install a modern version of nodejs
brew install node@23
brew link --overwrite node@23
brew postinstall node
# install sqlite3 and libspatialite
brew install sqlite3 libspatialite# run environment checks
npm run env_check# run tests
npm test# generate code coverage report
npm run coverage# create empty spatial database
node bin/spatial.js import whosonfirst --db=empty.db --file=/dev/null# merge two databases
node bin/spatial.js merge --db=/data/empty.db /data/external.db# run whosonfirst import
# note: database sourced from https://dist.whosonfirst.org/sqlite/
ingress() {
WOFDB='/data/wof/sqlite/whosonfirst-data-admin-nz-latest.db'
EXTRACT_QUERY='SELECT json_extract(body, "$") FROM geojson'
sqlite3 "${WOFDB}" "${EXTRACT_QUERY}"
}
ingress | node bin/spatial.js --db=geo.local.db import whosonfirst# run openstreetmap import
# note: data generated using https://docs.osmcode.org/osmium/latest/
ingress() {
EXTRACT_FILE='osmium.extract.geojsonl.gz'
gzcat "${EXTRACT_FILE}"
}
ingress | node bin/spatial.js --db=geo.local.db import osmium# start the HTTP server on port 3000
node bin/spatial.js server --db=geo.local.db# run point-in-polygon query
node bin/spatial.js --db=geo.local.db pip 174.766843 -41.288788For performance critial HTTP APIs we have two methods of load-testing:
For some basic tests you can use k6 to write perf tests in javascript:
import http from 'k6/http'
const baseurl = 'http://localhost:3000/query/pip/_view/pelias'
function randomFloat(from, to, fixed) {
return (Math.random() * (to - from) + from).toFixed(fixed) * 1
}
export default function() {
let lon = randomFloat(-180, +180, 8)
let lat = randomFloat(-90, +90, 8)
http.get(`${baseurl}/${lon}/${lat}`)
}k6 run --vus 20 --iterations 100000 test.jsJawg provide a suite of stress-testing tools for benchmarking various Pelias services.
These tools are powered by Gatling which can produce impressive visual charts and provide more information about where the bottlenecks are occurring (ie. disk congestion).
see #7 for examples