This repository is part of the Pelias project. Pelias is an open-source, open-data geocoder built by Mapzen that also powers Mapzen Search. Our official user documentation is here.

Pelias Result Sorting

Overview

Module that sorts for ambiguous Pelias search and geocoding results

Installation

$ npm install pelias-sorting

NPM Module

The pelias-sorting npm module can be found here:

https://npmjs.org/package/pelias-sorting

Resolving ambiguities

The list presented here is used to resolve ambiguities in Pelias. For example, there's only one place named Truth or Consequences so there are no ambiguities to sort. Similarly, Saint Petersburg, Russia is fully-qualified and unambiguous. However, "Lancaster" can be interpreted as any of:

• 2 neighbourhoods
• 13 cities (in 2 countries)
• 4 counties

Without additional information such as state to narrow down this list, Pelias sorts these ambiguities according to what the user is more likely referring to. According to the ordering rules below, the input "Lancaster" without focus.point parameters would return Lancaster, California since it's the most populous of the mid-sized cities. However, if focus.point.lat=54.232&focus.point.lon=-6.721 (roughly the center of Great Britain) was supplied for the same query, then Lancaster, England would be returned first.

Ordering Rules

Unless otherwise specified, ties between two results at the same layer are broken using population values with higher population results returned first.

1. very large city
   • population > 4,000,000
   • "Paris" should always rank Paris, France higher than Paris, Texas since people looking for the latter will supply additional qualifiers such as state or country.
   • Examples:
     1. New York City, NY
     2. Saint Petersburg, Russia
2. continent
   • Continent names are so well known that users looking for some more granular are accustomed to adding additional qualifiers.
   • Examples:
     1. Asia
     2. Antarctica
3. country
   • These names are so well known that users looking for some more granular are accustomed to adding additional qualifiers. For example, Luxembourg the country contains a city named Luxembourg but users entering Luxembourg without additional qualification are normally looking for the country.
   • Examples:
     1. Canada
     2. Laos
4. dependency
   • These names are so well known that users looking for some more granular are accustomed to adding additional qualifiers
   • Examples:
     1. Puerto Rico
     2. Gibraltar
5. large city
   • population between 500,000 and 4,000,000
   • Ties among mid-size cities are broken by preferring those closer to focus.point or greater population if not supplied.
   • Examples:
     1. San Francisco, California
     2. Marseilles, France
6. macroregion
   • Macroregions are considered groups of regions. While this classification is limited to Europe, an unofficial colloquial United States analog would be New England, which contains [Connecticut](), Maine, Massachusetts, New Hampshire, Rhode Island, and Vermont.
   • Examples:
     1. Sardinia, Italy
     2. Andalusia, Spain
7. region
   • These are "states" in the United States and "provinces" in Canada.
   • Examples:
     1. New Mexico, USA
     2. British Columbia, Canada
8. borough
   • Examples:
     1. Manhattan, New York City
     2. Bronx
9. very popular neighbourhood - popularity >= 10,000
   • Ties among popular neighbourhoods are broken by preferring those closer to focus.point or greater popularity if not supplied.
   • Examples:
     1. Chelsea, New York City
     2. Greenwich, London
10. mid-size city
    • population between 5,000 and 500,000
    • Ties among mid-size cities are broken by preferring those closer to focus.point or greater population if not supplied.
    • Examples:
      1. Socorro, New Mexico
      2. Strasbourg, France
11. macrocounty
    • macrocounty results are ranked below medium cities because they typically contain a city of the same name that users are normally interested in
    • Examples:
      1. Perpignan, France
      2. Stuttgart, Germany
12. county
    • Like macrocounty, counties normally contain a city with the same name
    • Examples:
      1. Maui, Hawaii
      2. Nordsachsen, Sachsen, Germany
13. macrohood
    • Groups of neighbourhoods
    • Examples:
      1. San Fernando Valley, Los Angeles, CA
      2. Suutarila, Helsinki, Finland
14. popular neighbourhood - popularity between 1,000 and 10,000
    • Ties among popular neighbourhoods are broken by preferring those closer to focus.point or greater popularity if not supplied.
    • Examples:
      1. Rittenhouse Square, Philadelphia
      2. Hyde Park
15. small city - population < 5,000
    • Ties among small cities are broken by preferring those closer to focus.point or greater population if not supplied.
    • Examples:
      1. Yoe, Pennsylvania
      2. Großerlach, Germany
16. non-popular neighbourhood - popularity < 1,000
    • Ties among non-popular neighbourhoods are broken by preferring those closer to focus.point or greater popularity if not supplied.
    • Examples:
      1. The Flats, Wilmington, DE
      2. Dagenham Heathway, London, GB

Regarding neighbourhoods, Pelias has no qualitative stance on what the term "popularity" means.