pelias / pelias/api

Trailing US ZIP is sometimes parsed as `admin`, causing autocomplete misses

Open
#1,723 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
259
Forks
168
Avg merge
6h 15m
Merged PRs (30d)
1

Description

On a local deployment for NYC using pelias/api:v5.53.0, several address queries stop returning their indexed targets when a ZIP code is appended. The debug output identifies the final ZIP as an administrative name rather than a postcode.

Examples from the same dataset and configuration:

Autocomplete input Parsed fields Result
5762 B'WAY subject: "5762 B'WAY" Address found
5762 B'WAY, 10463 subject: "5762 B'WAY", admin: "10463" No results
5762 BROADWAY, 10463 housenumber: "5762", street: "BROADWAY", postcode: "10463" Address found

The same admin classification and miss occurred for 662 DR G C TAYLOR BOULEVARD, 11206 and 73-25 CAPT P WATERS ROAD, 11379. The generated autocomplete query treats the ZIP as a required admin-matching clause instead of a postcode. The intended address is indexed. Correcting the token's classification recovered all three targeted cases at rank one in the local candidate.

A local prototype I made used an explicit, default-off US-postcode option and changed admin to postcode only when:

  • The Pelias parser produced an address-like subject and no existing postcode
  • The entire admin value is exactly five digits and exactly matches the final comma-separated input segment
  • There is no intersection/cross-street parse
  • The request has an exclusively US country boundary, or the operator enabled this behavior for a US deployment with no request country boundary

It leaves ZIP+4, mixed/non-US boundaries, combined locality-and-ZIP text, existing postcodes, and non-address subjects unchanged. Five-digit postcodes are not unique to the US, of course, so enabling this globally without geographic context would be inappropriate.

My prototype was wired into autocomplete and the search path that uses the Pelias parser. An intersection regression test in the prototype showed that moving the admin constraint was unsafe, so intersections were excluded.

This is related to the admin-matching discussion in #1505. The suggested correction preserves the meaning of an identified ZIP.

Would a parser correction or this guarded API approach be preferable, and what geographic evidence should be required before interpreting an otherwise unclassified five-digit token as a ZIP?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the autocomplete and search paths that use the Pelias parser, then reproduce the three address examples and inspect the existing intersection handling. Compare the parser-correction and guarded API approaches, and verify that valid ZIP cases recover results while intersections, ZIP+4, non-US boundaries, existing postcodes, and non-address subjects remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, search
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.