openzim / openzim/maps

Use per-country ADM level names for disambiguation labels

Open
#102 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
19
Forks
5
Avg merge
4m
Merged PRs (30d)
2

Description

With https://github.com/openzim/maps/pull/101, ADM_LEVEL_NAMES in processor.py maps GeoNames feature codes to generic English names (ADM1region, ADM2department, etc.). These are used when two places share the same name and are in an ancestor/descendant relationship, producing labels like "Rumilly (district)" vs "Rumilly (city)".

The problem is that ADM levels are country-specific: ADM1 is a "state" in the US, a "region" in France, a "Land" in Germany, a "province" in Canada, etc. The generic fallback names are misleading for most countries.

GeoNames originally definition is probably intentionally way more blurry: https://www.geonames.org/export/codes.html

Proposed solution

Replace the single flat dict with a bundled JSON asset (src/maps2zim/assets/adm_level_names.json) structured as:

{
  "_default": {"ADM1": "region", "ADM2": "department", "ADM3": "district", "ADM4": "city"},
  "US": {"ADM1": "state", "ADM2": "county", "ADM3": "city"},
  "DE": {"ADM1": "state", "ADM2": "district", "ADM3": "municipality"},
  ...
}

_compute_discriminating_labels looks up the place's country_code first, falling back to _default.

Data sourcing

No off-the-shelf file is known to exist. The initial dataset should cover the most frequent countries in the GeoNames data and can be extended over time. Wikidata SPARQL or the OpenStreetMap wiki (which documents per-country admin levels) are the best reference sources for curating the initial content.

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

Review processor.py and the existing ADM_LEVEL_NAMES logic, then inspect _compute_discriminating_labels to understand the country-code lookup and fallback behavior. Curate an initial adm_level_names.json dataset using the linked GeoNames, Wikidata SPARQL, or OpenStreetMap references. Done means frequent countries have useful ADM labels, unknown countries use _default, and disambiguation labels reflect those names.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.