fix(ES): retag 6,920 mistyped admin rows to type=city (#1498 follow-up)

After PR-A dropped 22 admin-level placeholders, 6,920 rows in
contributions/cities/ES.json still carried type='adm1', 'adm2', or 'adm3'
even though they are real Spanish municipalities (provincial capitals
typed adm1/adm2; small towns typed adm3). Consuming apps that filter on
type='city' were excluding these from city dropdowns -- the failure mode
the issue reporter described.

Spot-check (60 random rows across all three adm levels) confirmed every
sample is a real Spanish municipality with coordinates, and 99%+ have
wikiDataId references. Aggregate signals: 6,913/6,920 have wikiDataId,
6,516/6,920 have non-zero population, 6,920/6,920 have coordinates.

Type counts (post PR-A -> post PR-B):
  adm3:    6,860 ->     0
  adm2:       40 ->     0
  adm1:       20 ->     0
  city:    1,416 -> 8,336
  section:    60 ->    60  (left alone -- mixed quality, needs row-level review)
  locality:    6 ->     6
  capital/historical_capital/adm4: 1 each -> 1 each

Diff is 6,920 single-field mutations only -- coordinates, names, state
codes, populations all byte-for-byte unchanged. Schema/cross-reference
validators report 0 errors; coord-bounds and same-name<5km duplicate
counts identical to PR-A head.

Closes #1498.

Author: dr5hn

.github/fixes-docs/FIX_1498_PR_B_SUMMARY.md

@@ -0,0 +1,69 @@
+# FIX #1498 — Spain: retag mistyped admin rows to type=city (PR-B of 2)
+
+**Issue:** [#1498 — Bug ES: GetCity returns province-level admin entries as cities](https://github.com/dr5hn/countries-states-cities-database/issues/1498)
+**Scope:** Bulk-retag 6,920 rows in `contributions/cities/ES.json` whose `type` is `adm1`/`adm2`/`adm3` to `type='city'`. Touches only the `type` field.
+**Sibling PR:** PR-A (already merged / in review) dropped 22 admin-level placeholder rows.
+**Closes:** #1498.
+**Date:** 2026-05-04
+
+## Problem
+
+After PR-A removed the 22 admin-level placeholders, ES.json still carried 6,920 records whose `type` field was set to `adm1`, `adm2`, or `adm3` even though the rows themselves are real Spanish municipalities. Consuming apps that filter on `type='city'` (or sort city-vs-admin records) treat these as administrative regions and exclude them from city dropdowns — exactly the failure mode the reporter described.
+
+## Spot-check (why these are real cities)
+
+A 60-row random sample (20 of each adm type) gave:
+
+- **adm1 (20 rows total in file):** every sample is a major Spanish city — Barcelona, Valencia, Sevilla, Zaragoza, Murcia, Pamplona, Valladolid, Las Palmas de Gran Canaria, Santiago de Compostela, Santander, Toledo, Mérida, Logroño, Vitoria-Gasteiz, Oviedo, Palma, etc.
+- **adm2 (40 rows total):** every sample is a provincial capital or municipality — Córdoba, Málaga, Lleida, Girona, Soria, Segovia, Jaén, Lugo, Albacete, Guadalajara, Palencia, Zamora, Castelló de la Plana, Ciudad Real, Alicante/Alacant (id 152158, the canonical Alicante), etc.
+- **adm3 (6,860 rows total):** every sample is a real Spanish municipality with coordinates and (mostly) population data.
+
+Aggregate quality signals across the 6,920 candidates:
+
+| Type | Count | Has wikiDataId | Has population > 0 | Has coords |
+|------|------:|---------------:|-------------------:|-----------:|
+| adm1 | 20    | 20/20          | 20/20              | 20/20      |
+| adm2 | 40    | 39/40          | 38/40              | 40/40      |
+| adm3 | 6,860 | 6,854/6,860    | 6,458/6,860        | 6,860/6,860 |
+
+## Counts (post PR-A → post PR-B)
+
+| Type | Before | After |
+|------|--:|--:|
+| city | 1,416 | **8,336** |
+| section | 60 | 60 |
+| adm3 | 6,860 | 0 |
+| adm2 | 40 | 0 |
+| adm1 | 20 | 0 |
+| locality | 6 | 6 |
+| historical_capital | 1 | 1 |
+| capital | 1 | 1 |
+| adm4 | 1 | 1 |
+| **Total** | **8,405** | **8,405** |
+
+(Note: the brief gave a back-of-envelope estimate of "6,936 to retag → 8,357 city". The actual numbers are 6,920 → 8,336, because 16 of the 22 rows PR-A dropped were themselves typed adm1/adm2/adm3.)
+
+## Out of scope (deliberately not touched)
+
+- **`type='section'` (60 rows):** mixed quality — some are real neighbourhoods of Barcelona/Madrid that should stay typed `section` (they're already correctly excluded from city dropdowns), some look like real towns. Needs row-by-row review, not bulk retag.
+- **`type='locality'` (6 rows):** small, defensible category; left alone.
+- **`type='capital'`, `type='historical_capital'`, `type='adm4'` (1 each):** not city-equivalents in this dataset's vocabulary. Left alone.
+
+## Implementation
+
+`bin/scripts/fixes/spain_retag_admin_types.py` — single-pass mutation, only touches the `type` field, only for ES rows whose current type is in `{adm1, adm2, adm3}`. Asserts row count is preserved and no admin-typed rows remain. Idempotent.
+
+## Validation (mirrors `.github/scripts/validate-*`)
+
+- Schema: 0 errors.
+- Cross-reference: 0 errors. Every `state_id` resolves to an ES state and `state_code` matches the resolved state's `iso2`.
+- Coordinate-bounds: 127 out-of-box (Canary Islands, `TF`/`GC` — pre-existing, identical to PR-A head).
+- Same-name + ≤5km duplicate pairs: 45 — **identical to PR-A head**. The retag only changed the `type` field; coordinates and names are byte-for-byte unchanged.
+- Diff inspection: 6,920 rows changed, every change is exactly one field (`type`), source value in `{adm1, adm2, adm3}`, target value `'city'`. Zero collateral changes.
+- Idempotent re-run: 0 candidates remaining.
+
+## Constraints honoured
+
+- Touches **only** the `type` field of `country_code='ES'` rows.
+- Does **not** touch `state_code`, `state_id`, coordinates, or any other field.
+- Does **not** modify `states.json` or `countries.json`.

bin/scripts/fixes/spain_retag_admin_types.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Retag mistyped admin-level rows in contributions/cities/ES.json to type='city'.
+
+Issue #1498 follow-up to PR-A (which dropped 22 admin-level placeholders).
+After PR-A, ES.json contains ~6,920 rows whose `type` field is set to
+`adm1`, `adm2`, or `adm3` even though they are real Spanish municipalities
+(provincial capitals, big cities, and small towns alike). This script
+retags those rows to `type='city'` so consuming apps stop misclassifying
+real cities as administrative regions.
+
+Why these rows are real cities (spot-checked, see PR description for
+samples):
+  - 100% have geographic coordinates.
+  - 99%+ have a `wikiDataId` reference.
+  - Almost all have a non-zero `population`.
+  - The names map cleanly to municipalities visible on Spanish gov
+    sources (provincial capitals like Zaragoza/Murcia/Sevilla typed
+    `adm1`; province-capitals-or-comparable typed `adm2`; small towns
+    typed `adm3`).
+
+Conservative scope:
+  - Only `country_code='ES'` rows are touched.
+  - Only `type` in {'adm1', 'adm2', 'adm3'} is rewritten.
+  - **Not** touched: `type='section'` (61 rows, mixed quality — needs
+    separate per-row review), `type='locality'` (6 rows), `type='city'`
+    (already correct), `type='capital'`/`'historical_capital'`/`'adm4'`
+    (1 each — left alone).
+
+Idempotent: re-running on already-retagged data writes nothing and exits 0.
+
+Usage:
+    python3 bin/scripts/fixes/spain_retag_admin_types.py [--dry-run]
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import sys
+from pathlib import Path
+from typing import List
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+CITIES_JSON = REPO_ROOT / "contributions/cities/ES.json"
+
+ADMIN_TYPES = ("adm1", "adm2", "adm3")
+TARGET_TYPE = "city"
+COUNTRY_CODE = "ES"
+
+
+def load_cities(path: Path) -> List[dict]:
+    """Read the cities JSON file and verify the top-level shape."""
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, list):
+        raise SystemExit(f"Expected JSON array at {path}, got {type(data).__name__}")
+    return data
+
+
+def is_target(row: dict) -> bool:
+    """Row is an ES record whose type is one of the admin levels we retag."""
+    return row.get("country_code") == COUNTRY_CODE and row.get("type") in ADMIN_TYPES
+
+
+def type_distribution(rows: List[dict]) -> "collections.Counter[str]":
+    """Counter of `type` values across rows."""
+    return collections.Counter(r.get("type") for r in rows)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Report the rewrite plan without rewriting the file.",
+    )
+    args = parser.parse_args()
+
+    if not CITIES_JSON.exists():
+        raise SystemExit(f"Cities file not found: {CITIES_JSON}")
+
+    cities = load_cities(CITIES_JSON)
+    pre_count = len(cities)
+
+    before = type_distribution(cities)
+    targets = [r for r in cities if is_target(r)]
+    retag_count = len(targets)
+
+    # Track per-source-type retag counts for reporting.
+    by_source = collections.Counter(r.get("type") for r in targets)
+
+    # Sample 5 retagged rows for human eyes.
+    sample = targets[:5]
+
+    # State_code distribution: every row keeps its existing state_code.
+    # Verify no row would change state_code as a side-effect.
+    state_code_changes = 0  # this script never modifies state_code; sanity assert.
+
+    print(f"Input file:        {CITIES_JSON.relative_to(REPO_ROOT)}")
+    print(f"Pre-retag count:   {pre_count}")
+    print(f"Type distribution before:")
+    for t, c in sorted(before.items(), key=lambda x: -x[1]):
+        print(f"  {t!r:>20}: {c}")
+    print(f"Retag candidates:  {retag_count}")
+    for src in ADMIN_TYPES:
+        print(f"  from {src!r}: {by_source.get(src, 0)}")
+
+    if retag_count == 0:
+        print("\nNo admin-typed rows found — nothing to do (idempotent).")
+        return 0
+
+    print("\nSample of rows that will be retagged:")
+    for r in sample:
+        print(
+            f"  id={r['id']} {r['name']!r} state_code={r.get('state_code')!r} "
+            f"old_type={r.get('type')!r} -> {TARGET_TYPE!r}"
+        )
+
+    if args.dry_run:
+        print("\n--dry-run: not writing.")
+        return 0
+
+    for row in cities:
+        if is_target(row):
+            row["type"] = TARGET_TYPE
+
+    after = type_distribution(cities)
+    print(f"\nType distribution after:")
+    for t, c in sorted(after.items(), key=lambda x: -x[1]):
+        print(f"  {t!r:>20}: {c}")
+    assert sum(after.values()) == sum(before.values()), "row count drift!"
+    assert state_code_changes == 0
+    # Sanity: no row in ADMIN_TYPES remains.
+    leftover = sum(after[t] for t in ADMIN_TYPES if t in after)
+    assert leftover == 0, f"{leftover} admin-typed rows still present"
+
+    with CITIES_JSON.open("w", encoding="utf-8") as fh:
+        json.dump(cities, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+
+    print(f"\nWrote {pre_count} records to {CITIES_JSON.relative_to(REPO_ROOT)}.")
+    print("Run `python3 bin/scripts/sync/normalize_json.py "
+          "contributions/cities/ES.json` next to canonicalize formatting.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())