Who's on First Admin Lookup for the Pelias Geocoder
JavaScript Shell
orangejulius Merge pull request #211 from pelias/parallel-transform
feat(deps): replace pelias-parallel-stream with parallel-transform
Latest commit 310af46 Jul 20, 2018
Failed to load latest commit information.
.jshintrc initial incorporation of pip service Feb 3, 2017
CONTRIBUTING.md Add contributing document Apr 13, 2016


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 Who's On First Admin Lookup

Greenkeeper badge Travis CI Status


What is admin lookup?

When collecting data for use in a geocoder, it's obviously important to know which city, country, etc each record belongs to. Collectively we call these fields the admin hierarchy.

Not every data source contains this information, and even those that do don't always have it consistently. So, for Pelias we actually ignore all admin hierarchy information from individual records, and generate it ourselves from the polygon data in Who's on First. This process is called admin lookup.

How does admin lookup work?

Admin lookup is essentially reverse geocoding: given the latitude and longitude of a point, populate the admin hierarchy by finding all the polygons for countries, cities, neighborhoods, and other admin fields that contain the point.


There are two possible ways to retrieve admin hierarchy: using remote pip service or load data into memory. It's recommended to use remote service in all cases (see downsides section bellow).


Who's On First Admin Lookup module recognizes the following top-level properties in your pelias.json config file:

  "imports": {
    "adminLookup": {
      "enabled": true
    // NOT RECOMMENDED: getting data from folder
    "whosonfirst": {
      "datapath": "/path/to/wof-data"
    "services": {
      // getting data from remote pip service
      "pip": {
        "url": "https://mypipservice.com"

What are there downsides of storing data in memory?

There are two: admin lookup slows down the process of loading data into Pelias, and it takes quite a bit of memory. Based on the current amount of data in Who's on First, count on using at least 4 or 5 GB of memory just for admin lookup while importing.