@code-plate/iran-cities 1.1.0 → 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

@@ -98,7 +98,7 @@ getCapital('khuzestan');        // => { id: 674, en: 'ahvaz', isCapital: true, c
 getCapitals();                  // ۳۱ مرکز استان
 getProvinceByPhoneCode('021');  // => تهران ('21' و 21 هم قبول است)
 getCity('نجف‌آباد').phoneCode;  // => '031' (کد استانِ شهر)
-getCity('اهواز').coordinates;   // => { lat, lng } | برای شهرهای غیرمرکز استان: undefined
+getCity('اهواز').coordinates;   // => { lat, lng, confidence } | برای شهرهای غیرمرکز استان: undefined
 
 // آمار کلی
 getStats(); // { provinceCount: 31, cityCount: 1252 }
@@ -270,7 +270,7 @@ export class IranLocationsService {
 ### تایپ‌ها
 
 ```ts
-interface Coordinates { lat: number; lng: number; }
+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; }
@@ -288,7 +288,7 @@ npm run validate  # اعتبارسنجی یکپارچگی data.json (id، slug،
 npm test          # validate + typecheck
 ```
 
-> **مختصات:** برای ۳۷۰ شهر (۳۱ مرکز استان + عمدتاً مراکز شهرستان) موجود است و فقط وقتی ثبت شده که حداقل دو منبع مستقل روی آن توافق داشته‌اند (جزئیات در `reports/`). برای بقیه `coordinates` برابر `undefined` است و هیچ مقدار تقریبی جایگزین نمی‌شود. منبع داده: GeoNames (CC BY 4.0)، فایل `NOTICE.md`.
+> **مختصات:** برای ۱۱۵۲ شهر از ۱۲۵۲ شهر موجود است (`coordinates: { lat, lng, confidence }`). `confidence` سه مقدار دارد: `'high'` (۹۷۷ شهر) یعنی منبع مستقل دیگری هم همان نقطه را تأیید کرده؛ `'medium'` (۹۸ شهر) یعنی نام شهر در GeoNames یکتا و شهر واقعی بوده ولی تأیید مستقل نداشته؛ `'low'` (۷۷ شهر) یعنی فقط تطبیق نام در GeoNames هست و مکانِ مطابق کوچک یا بدون جمعیت ثبت شده یا نام تقریبی تطبیق داده شده (فقط برای نمایش تقریبی؛ خطای چند تا ده‌ها کیلومتر محتمل است). برای ۱۰۰ شهر باقی‌مانده `coordinates` برابر `undefined` است و هیچ مقدار تقریبی جایگزین نمی‌شود (فهرست و دلیل: `reports/coordinates-not-imported.csv`). منبع داده: GeoNames (CC BY 4.0)، فایل `NOTICE.md`.
 
 ## لایسنس
 

package/README.md

@@ -98,7 +98,7 @@ getCapital('khuzestan');        // => { id: 674, en: 'ahvaz', isCapital: true, c
 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 } | undefined for non-capital cities
+getCity('اهواز').coordinates;   // => { lat, lng, confidence } | undefined for non-capital cities
 
 // Overall stats
 getStats(); // { provinceCount: 31, cityCount: 1252 }
@@ -270,7 +270,7 @@ export class IranLocationsService {
 ### Types
 
 ```ts
-interface Coordinates { lat: number; lng: number; }
+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; }
@@ -288,7 +288,7 @@ npm run validate  # data integrity checks for data.json (ids, slugs, capitals, a
 npm test          # validate + typecheck
 ```
 
-> **Coordinates:** available for 370 cities (31 provincial capitals + mostly county seats), recorded only when at least two independent sources agree (details in `reports/`). For every other city `coordinates` is `undefined`; no approximate values are filled in. Data source: GeoNames (CC BY 4.0), see `NOTICE.md`.
+> **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