@code-plate/iran-cities 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.2.0
+- **Added:** numeric `id` for provinces and cities (globally unique, stable); `isCapital`, `capitalId`, province `phoneCode`.
+- **Added:** `coordinates: { lat, lng, confidence }` for 1152 cities (GeoNames, CC BY 4.0); `confidence` is `'high' | 'medium' | 'low'`.
+- **Added:** `getCityById`, `getProvinceById`, `getCitiesByName`, `getCapital`, `getCapitals`, `getProvinceByPhoneCode`; lookups accept numeric ids.
+- **Added:** `npm run validate` data-integrity checks.
+- **Fixed:** duplicate «گلوگاه» entry in Mazandaran removed (1253 -> 1252 cities); `useCitySearch` / `useProvinceSearch` no longer re-run on inline `options`.
+- **Corrected data (old names/slugs still resolve):** city 402 `sowme'eh-sara` -> `sowmeeh-sara` (fa: صومعه سرا); city 672 `هلشی` -> `halashi` (fa: هلشی). Ids unchanged.
+- **Corrected coordinates:** Ahvaz and Kermanshah capital coordinates fixed (source table was ~110 km / ~60 km off).

package/NOTICE.md

@@ -0,0 +1,21 @@
+# Attribution / منابع و مجوز داده‌ها
+
+Coordinates (`lat`/`lng`) in `src/data.json` are point locations from **GeoNames** (https://www.geonames.org),
+licensed under **Creative Commons Attribution 4.0** (CC BY 4.0). Attribution to GeoNames is required.
+
+- Source file: GeoNames Iran dump `IR.zip` (https://download.geonames.org/export/dump/IR.zip), supplied by the package author on 2026-10-07.
+- The 31 provincial-capital coordinates were supplied by the package author (Wikipedia table), cross-checked against GeoNames;
+  two were corrected (Ahvaz, Kermanshah).
+- Each city was matched to a GeoNames populated place by normalized Persian name within the same province
+  (province mapped through GeoNames admin1 codes), with a Latin-name fallback. Abandoned/destroyed/historical places were excluded.
+
+The following public datasets were used **only to cross-check the match** (no values were copied from them unless they equal the GeoNames value):
+
+| Dataset | Used for | License |
+|---|---|---|
+| sajaddp/list-of-cities-in-Iran | cross-check; official county seats (GeoNames-derived) | repo: GPL-3.0; coordinate records: CC BY 4.0 (GeoNames) |
+| dr5hn/countries-states-cities-database | cross-check only | ODbL-1.0 |
+| jafaripur/iran-locality-database | cross-check only | none stated |
+| mhndev/iran-geography | cross-check only | none stated |
+
+This is a summary, not legal advice.

package/README.fa.md

@@ -26,8 +26,10 @@ pnpm add @code-plate/iran-cities
 ## داده‌ها
 
 - `۳۱` استان
-- `۱۲۵۳` شهر
-- هر رکورد شامل `en` (شناسه لاتین kebab-case، مثل `tehran`) و `fa` (نام فارسی، مثل `تهران`) است.
+- `۱۲۵۲` شهر
+- هر رکورد شامل `id` (شناسه‌ی عددی یکتا و پایدار)، `en` (شناسه لاتین kebab-case، مثل `tehran`) و `fa` (نام فارسی، مثل `تهران`) است.
+- هر استان `phoneCode` (کد تلفن بین‌شهری) و `capitalId` (id مرکز استان) دارد؛ هر شهر `isCapital` دارد و مراکز استان‌ها `coordinates: { lat, lng }` هم دارند.
+- `id` شهرها در **کل کشور یکتاست** (شهرهای هم‌نام مثل «مهاباد» در دو استان، دو id متفاوت دارند) و بین نسخه‌ها تغییر نمی‌کند؛ شهر جدید همیشه id بعدی را می‌گیرد.
 
 ---
 
@@ -40,6 +42,9 @@ import {
   getProvince,
   getCities,
   getCity,
+  getCityById,
+  getProvinceById,
+  getCitiesByName,
   getAllCities,
   getProvinceOfCity,
   searchProvinces,
@@ -49,15 +54,16 @@ import {
 
 // همه‌ی استان‌ها به همراه شهرهایشان
 getProvinces();
-// [{ en: 'alborz', fa: 'البرز', cities: [{ en: 'karaj', fa: 'کرج' }, ...] }, ...]
+// [{ id: 1, en: 'alborz', fa: 'البرز', cities: [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj' }, ...] }, ...]
 
 // فقط لیست استان‌ها (بدون شهر) - برای Select/Dropdown
 getProvincesList();
-// [{ en: 'alborz', fa: 'البرز' }, { en: 'ardabil', fa: 'اردبیل' }, ...]
+// [{ id: 1, en: 'alborz', fa: 'البرز' }, { id: 2, en: 'ardabil', fa: 'اردبیل' }, ...]
 
 // گرفتن یک استان با نام انگلیسی یا فارسی
 getProvince('tehran');
 getProvince('تهران'); // همین نتیجه را می‌دهد
+getProvince(28);      // با id عددی هم کار می‌کند (رشته‌ی عددی '28' هم قبول است)
 
 // شهرهای یک استان خاص
 getCities('fars');       // بر اساس شناسه انگلیسی
@@ -69,18 +75,33 @@ getCity('شیراز', 'fars'); // محدود به استان فارس
 
 // لیست مسطح (flat) همه‌ی شهرهای کشور همراه با استان مربوطه
 getAllCities();
-// [{ en: 'karaj', fa: 'کرج', provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
+// [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj', provinceId: 1, provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
+
+// گرفتن شهر/استان با id
+getCityById(292);     // => شیراز (provinceId: 7)
+getProvinceById(7);   // => فارس
+
+// نام‌های تکراری: همه‌ی شهرهای با این نام
+getCitiesByName('مهاباد'); // => [اصفهان/مهاباد (id 270), آذربایجان غربی/مهاباد (id 1171)]
 
 // پیدا کردن استانِ یک شهر
-getProvinceOfCity('اصفهان'); // => { en: 'isfahan', fa: 'اصفهان', cities: [...] }
+getProvinceOfCity('اصفهان'); // => { id: 6, en: 'isfahan', fa: 'اصفهان', cities: [...] }
+getProvinceOfCity(292);      // با id شهر هم کار می‌کند
 
 // جستجوی زنده (autocomplete) در استان‌ها یا شهرها
 searchProvinces('خراسان');            // هر سه استان خراسان را برمی‌گرداند
 searchCities('شهر', { limit: 10 });   // ۱۰ نتیجه‌ی اول شامل «شهر»
 searchCities('mashhad', { locale: 'en' }); // جستجو فقط در نام انگلیسی
 
+// مرکز استان، کد تلفن و مختصات
+getCapital('khuzestan');        // => { id: 674, en: 'ahvaz', isCapital: true, coordinates: { lat: 31.31901, lng: 48.6842 }, phoneCode: '061', ... }
+getCapitals();                  // ۳۱ مرکز استان
+getProvinceByPhoneCode('021');  // => تهران ('21' و 21 هم قبول است)
+getCity('نجف‌آباد').phoneCode;  // => '031' (کد استانِ شهر)
+getCity('اهواز').coordinates;   // => { lat, lng, confidence } | برای شهرهای غیرمرکز استان: undefined
+
 // آمار کلی
-getStats(); // { provinceCount: 31, cityCount: 1253 }
+getStats(); // { provinceCount: 31, cityCount: 1252 }
 ```
 
 ### نکته‌ی مهم درباره‌ی جستجو
@@ -119,21 +140,25 @@ app.get('/api/cities/search', (req, res) => {
 import { useProvinces, useCities, useProvinceCitySelect, useCitySearch } from '@code-plate/iran-cities/react';
 
 function AddressForm() {
-  const { provinces, cities, province, setProvince, city, setCity } = useProvinceCitySelect();
+  const { provinces, cities, province, setProvince, city, setCity, provinceId, cityId, selectedCity } =
+    useProvinceCitySelect();
+
+  // موقع ارسال فرم: { provinceId, cityId } را به بک‌اند بفرستید
+  // selectedCity => { id, en, fa, slug, provinceId, provinceEn, provinceFa }
 
   return (
     <>
       <select value={province} onChange={(e) => setProvince(e.target.value)}>
         <option value="">انتخاب استان</option>
         {provinces.map((p) => (
-          <option key={p.en} value={p.en}>{p.fa}</option>
+          <option key={p.id} value={p.en}>{p.fa}</option>
         ))}
       </select>
 
       <select value={city} onChange={(e) => setCity(e.target.value)} disabled={!province}>
         <option value="">انتخاب شهر</option>
         {cities.map((c) => (
-          <option key={c.en} value={c.en}>{c.fa}</option>
+          <option key={c.id} value={c.en}>{c.fa}</option>
         ))}
       </select>
     </>
@@ -154,7 +179,7 @@ function CityAutocomplete() {
       <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="نام شهر..." />
       <ul>
         {results.map((c) => (
-          <li key={`${c.provinceEn}-${c.en}`}>{c.fa} ({c.provinceFa})</li>
+          <li key={c.id}>{c.fa} ({c.provinceFa})</li>
         ))}
       </ul>
     </div>
@@ -168,7 +193,7 @@ function CityAutocomplete() {
 |---|---|
 | `useProvinces()` | لیست استان‌ها |
 | `useCities(provinceQuery)` | شهرهای یک استان، وابسته به تغییر پارامتر |
-| `useProvinceCitySelect()` | state کامل یک فرم استان→شهر (با ریست خودکار شهر هنگام تغییر استان) |
+| `useProvinceCitySelect()` | state کامل یک فرم استان→شهر (با ریست خودکار شهر هنگام تغییر استان)؛ علاوه بر `province`/`city` مقدارهای `provinceId`, `cityId`, `selectedProvince`, `selectedCity` و `reset()` را هم برمی‌گرداند |
 | `useCitySearch(initialQuery?, options?)` | state جستجوی زنده‌ی شهر |
 | `useProvinceSearch(initialQuery?, options?)` | state جستجوی زنده‌ی استان |
 
@@ -224,12 +249,18 @@ export class IranLocationsService {
 | تابع | ورودی | خروجی | توضیح |
 |---|---|---|---|
 | `getProvinces()` | - | `Province[]` | همه‌ی استان‌ها به همراه شهرها |
-| `getProvincesList()` | - | `{en, fa}[]` | فقط لیست استان‌ها |
-| `getProvince(query)` | `string` | `Province \| undefined` | یک استان با en یا fa |
-| `getCities(provinceQuery)` | `string` | `City[]` | شهرهای یک استان |
-| `getCity(cityQuery, provinceQuery?)` | `string, string?` | `FlatCity \| undefined` | یک شهر مشخص |
+| `getProvincesList()` | - | `{id, en, fa}[]` | فقط لیست استان‌ها |
+| `getCapital(provinceQuery)` | `string \| number` | `FlatCity \| undefined` | مرکز استان |
+| `getCapitals()` | - | `FlatCity[]` | مراکز ۳۱ استان |
+| `getProvinceByPhoneCode(code)` | `string \| number` | `Province \| undefined` | استان با کد تلفن بین‌شهری |
+| `getProvinceById(id)` | `number` | `Province \| undefined` | استان با id |
+| `getCityById(id)` | `number` | `FlatCity \| undefined` | شهر با id سراسری |
+| `getCitiesByName(name)` | `string` | `FlatCity[]` | همه‌ی شهرهای با این نام (برای نام‌های تکراری) |
+| `getProvince(query)` | `string \| number` | `Province \| undefined` | یک استان با en یا fa |
+| `getCities(provinceQuery)` | `string \| number` | `City[]` | شهرهای یک استان |
+| `getCity(cityQuery, provinceQuery?)` | `string \| number, (string \| number)?` | `FlatCity \| undefined` | یک شهر مشخص |
 | `getAllCities()` | - | `FlatCity[]` | همه‌ی شهرها به‌صورت مسطح |
-| `getProvinceOfCity(cityQuery)` | `string` | `Province \| undefined` | استانِ یک شهر |
+| `getProvinceOfCity(cityQuery)` | `string \| number` | `Province \| undefined` | استانِ یک شهر |
 | `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | جستجوی fuzzy استان |
 | `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | جستجوی fuzzy شهر |
 | `getStats()` | - | `{provinceCount, cityCount}` | آمار کلی |
@@ -239,9 +270,10 @@ export class IranLocationsService {
 ### تایپ‌ها
 
 ```ts
-interface City { en: string; fa: string; }
-interface Province { en: string; fa: string; cities: City[]; }
-interface FlatCity extends City { provinceEn: string; provinceFa: string; }
+interface Coordinates { lat: number; lng: number; confidence: 'high' | 'medium' | 'low'; }
+interface City { id: number; isCapital: boolean; coordinates?: Coordinates; slug: string; en: string; fa: string; }
+interface Province { id: number; en: string; fa: string; phoneCode: string; capitalId: number; cities: City[]; }
+interface FlatCity extends City { provinceId: number; provinceEn: string; provinceFa: string; phoneCode: string; }
 ```
 
 ---
@@ -252,8 +284,12 @@ interface FlatCity extends City { provinceEn: string; provinceFa: string; }
 npm install
 npm run build     # خروجی dist/ (cjs + esm + d.ts)
 npm run typecheck
+npm run validate  # اعتبارسنجی یکپارچگی data.json (id، slug، مرکز استان، کد تلفن، مختصات)
+npm test          # validate + typecheck
 ```
 
+> **مختصات:** برای ۱۱۵۲ شهر از ۱۲۵۲ شهر موجود است (`coordinates: { lat, lng, confidence }`). `confidence` سه مقدار دارد: `'high'` (۹۷۷ شهر) یعنی منبع مستقل دیگری هم همان نقطه را تأیید کرده؛ `'medium'` (۹۸ شهر) یعنی نام شهر در GeoNames یکتا و شهر واقعی بوده ولی تأیید مستقل نداشته؛ `'low'` (۷۷ شهر) یعنی فقط تطبیق نام در GeoNames هست و مکانِ مطابق کوچک یا بدون جمعیت ثبت شده یا نام تقریبی تطبیق داده شده (فقط برای نمایش تقریبی؛ خطای چند تا ده‌ها کیلومتر محتمل است). برای ۱۰۰ شهر باقی‌مانده `coordinates` برابر `undefined` است و هیچ مقدار تقریبی جایگزین نمی‌شود (فهرست و دلیل: `reports/coordinates-not-imported.csv`). منبع داده: GeoNames (CC BY 4.0)، فایل `NOTICE.md`.
+
 ## لایسنس
 
 MIT

package/README.md

@@ -26,8 +26,10 @@ pnpm add @code-plate/iran-cities
 ## Data
 
 - `31` provinces
-- `1253` cities
-- Every record has an `en` field (latin, kebab-case identifier, e.g. `tehran`) and an `fa` field (Persian name, e.g. `تهران`).
+- `1252` cities
+- Every record has an `id` (stable numeric identifier), an `en` field (latin, kebab-case identifier, e.g. `tehran`) and an `fa` field (Persian name, e.g. `تهران`).
+- Every province has a `phoneCode` (area code) and a `capitalId`; every city has `isCapital`, and province capitals also carry `coordinates: { lat, lng }`.
+- City `id`s are **globally unique** (same-named cities such as «Mahabad» in two provinces get different ids) and never change between versions; new cities always get the next id.
 
 ---
 
@@ -40,6 +42,9 @@ import {
   getProvince,
   getCities,
   getCity,
+  getCityById,
+  getProvinceById,
+  getCitiesByName,
   getAllCities,
   getProvinceOfCity,
   searchProvinces,
@@ -49,15 +54,16 @@ import {
 
 // All provinces along with their cities
 getProvinces();
-// [{ en: 'alborz', fa: 'البرز', cities: [{ en: 'karaj', fa: 'کرج' }, ...] }, ...]
+// [{ id: 1, en: 'alborz', fa: 'البرز', cities: [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj' }, ...] }, ...]
 
 // Just the list of provinces (no cities) - for a Select/Dropdown
 getProvincesList();
-// [{ en: 'alborz', fa: 'البرز' }, { en: 'ardabil', fa: 'اردبیل' }, ...]
+// [{ id: 1, en: 'alborz', fa: 'البرز' }, { id: 2, en: 'ardabil', fa: 'اردبیل' }, ...]
 
 // Get a single province by English id or Persian name
 getProvince('tehran');
 getProvince('تهران'); // same result
+getProvince(28);      // numeric id works too (so does the string '28')
 
 // Cities of a specific province
 getCities('fars');       // by English id
@@ -69,18 +75,33 @@ getCity('شیراز', 'fars'); // scoped to Fars province
 
 // Flat list of every city in the country, along with its province
 getAllCities();
-// [{ en: 'karaj', fa: 'کرج', provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
+// [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj', provinceId: 1, provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
+
+// Look up by id
+getCityById(292);     // => Shiraz (provinceId: 7)
+getProvinceById(7);   // => Fars
+
+// Duplicate names: every city with that name
+getCitiesByName('مهاباد'); // => [Isfahan/Mahabad (id 270), West Azerbaijan/Mahabad (id 1171)]
 
 // Find which province a city belongs to
-getProvinceOfCity('اصفهان'); // => { en: 'isfahan', fa: 'اصفهان', cities: [...] }
+getProvinceOfCity('اصفهان'); // => { id: 6, en: 'isfahan', fa: 'اصفهان', cities: [...] }
+getProvinceOfCity(292);      // city id works too
 
 // Live search (autocomplete) over provinces or cities
 searchProvinces('خراسان');             // returns all three "Khorasan" provinces
 searchCities('شهر', { limit: 10 });    // first 10 results containing "شهر"
 searchCities('mashhad', { locale: 'en' }); // search English names only
 
+// Capital, area code and coordinates
+getCapital('khuzestan');        // => { id: 674, en: 'ahvaz', isCapital: true, coordinates: { lat: 31.31901, lng: 48.6842 }, phoneCode: '061', ... }
+getCapitals();                  // the 31 provincial capitals
+getProvinceByPhoneCode('021');  // => Tehran ('21' and 21 work too)
+getCity('نجف‌آباد').phoneCode;  // => '031' (area code of the city's province)
+getCity('اهواز').coordinates;   // => { lat, lng, confidence } | undefined for non-capital cities
+
 // Overall stats
-getStats(); // { provinceCount: 31, cityCount: 1253 }
+getStats(); // { provinceCount: 31, cityCount: 1252 }
 ```
 
 ### A note on search
@@ -119,21 +140,25 @@ An optional subpath is available for React with a few ready-made hooks:
 import { useProvinces, useCities, useProvinceCitySelect, useCitySearch } from '@code-plate/iran-cities/react';
 
 function AddressForm() {
-  const { provinces, cities, province, setProvince, city, setCity } = useProvinceCitySelect();
+  const { provinces, cities, province, setProvince, city, setCity, provinceId, cityId, selectedCity } =
+    useProvinceCitySelect();
+
+  // On submit, send { provinceId, cityId } to your backend.
+  // selectedCity => { id, en, fa, slug, provinceId, provinceEn, provinceFa }
 
   return (
     <>
       <select value={province} onChange={(e) => setProvince(e.target.value)}>
         <option value="">Select a province</option>
         {provinces.map((p) => (
-          <option key={p.en} value={p.en}>{p.fa}</option>
+          <option key={p.id} value={p.en}>{p.fa}</option>
         ))}
       </select>
 
       <select value={city} onChange={(e) => setCity(e.target.value)} disabled={!province}>
         <option value="">Select a city</option>
         {cities.map((c) => (
-          <option key={c.en} value={c.en}>{c.fa}</option>
+          <option key={c.id} value={c.en}>{c.fa}</option>
         ))}
       </select>
     </>
@@ -154,7 +179,7 @@ function CityAutocomplete() {
       <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="City name..." />
       <ul>
         {results.map((c) => (
-          <li key={`${c.provinceEn}-${c.en}`}>{c.fa} ({c.provinceFa})</li>
+          <li key={c.id}>{c.fa} ({c.provinceFa})</li>
         ))}
       </ul>
     </div>
@@ -168,7 +193,7 @@ Hooks available in the `react` subpath:
 |---|---|
 | `useProvinces()` | List of provinces |
 | `useCities(provinceQuery)` | Cities of a province, reacts to changes in the parameter |
-| `useProvinceCitySelect()` | Full state + logic for a province→city form field (auto-resets the city when the province changes) |
+| `useProvinceCitySelect()` | Full state + logic for a province→city form field (auto-resets the city when the province changes); also returns `provinceId`, `cityId`, `selectedProvince`, `selectedCity` and `reset()` |
 | `useCitySearch(initialQuery?, options?)` | Live city search state |
 | `useProvinceSearch(initialQuery?, options?)` | Live province search state |
 
@@ -224,12 +249,18 @@ export class IranLocationsService {
 | Function | Input | Output | Description |
 |---|---|---|---|
 | `getProvinces()` | - | `Province[]` | All provinces with their cities |
-| `getProvincesList()` | - | `{en, fa}[]` | Provinces only |
-| `getProvince(query)` | `string` | `Province \| undefined` | A province by en or fa |
-| `getCities(provinceQuery)` | `string` | `City[]` | Cities of a province |
-| `getCity(cityQuery, provinceQuery?)` | `string, string?` | `FlatCity \| undefined` | A specific city |
+| `getProvincesList()` | - | `{id, en, fa}[]` | Provinces only |
+| `getCapital(provinceQuery)` | `string \| number` | `FlatCity \| undefined` | Capital of a province |
+| `getCapitals()` | - | `FlatCity[]` | The 31 provincial capitals |
+| `getProvinceByPhoneCode(code)` | `string \| number` | `Province \| undefined` | Province by area code |
+| `getProvinceById(id)` | `number` | `Province \| undefined` | Province by id |
+| `getCityById(id)` | `number` | `FlatCity \| undefined` | City by global id |
+| `getCitiesByName(name)` | `string` | `FlatCity[]` | Every city with that name (for duplicate names) |
+| `getProvince(query)` | `string \| number` | `Province \| undefined` | A province by en or fa |
+| `getCities(provinceQuery)` | `string \| number` | `City[]` | Cities of a province |
+| `getCity(cityQuery, provinceQuery?)` | `string \| number, (string \| number)?` | `FlatCity \| undefined` | A specific city |
 | `getAllCities()` | - | `FlatCity[]` | All cities, flattened |
-| `getProvinceOfCity(cityQuery)` | `string` | `Province \| undefined` | The province a city belongs to |
+| `getProvinceOfCity(cityQuery)` | `string \| number` | `Province \| undefined` | The province a city belongs to |
 | `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | Fuzzy province search |
 | `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | Fuzzy city search |
 | `getStats()` | - | `{provinceCount, cityCount}` | Overall stats |
@@ -239,9 +270,10 @@ export class IranLocationsService {
 ### Types
 
 ```ts
-interface City { en: string; fa: string; }
-interface Province { en: string; fa: string; cities: City[]; }
-interface FlatCity extends City { provinceEn: string; provinceFa: string; }
+interface Coordinates { lat: number; lng: number; confidence: 'high' | 'medium' | 'low'; }
+interface City { id: number; isCapital: boolean; coordinates?: Coordinates; slug: string; en: string; fa: string; }
+interface Province { id: number; en: string; fa: string; phoneCode: string; capitalId: number; cities: City[]; }
+interface FlatCity extends City { provinceId: number; provinceEn: string; provinceFa: string; phoneCode: string; }
 ```
 
 ---
@@ -252,8 +284,12 @@ interface FlatCity extends City { provinceEn: string; provinceFa: string; }
 npm install
 npm run build     # outputs dist/ (cjs + esm + d.ts)
 npm run typecheck
+npm run validate  # data integrity checks for data.json (ids, slugs, capitals, area codes, coordinates)
+npm test          # validate + typecheck
 ```
 
+> **Coordinates:** available for 1152 of 1252 cities (`coordinates: { lat, lng, confidence }`). `confidence` has three levels: `'high'` (977 cities) – an independent source confirms the same point; `'medium'` (98) – the name is unique in GeoNames and the place is city-like, but no independent confirmation; `'low'` (77) – only a name match in GeoNames, where the matched place is small/unpopulated or the name match was approximate (approximate display only; errors of several to tens of km are possible). For the remaining 100 cities `coordinates` is `undefined`; no approximate values are filled in (list and reasons: `reports/coordinates-not-imported.csv`). Data source: GeoNames (CC BY 4.0), see `NOTICE.md`.
+
 ## License
 
 MIT