|
| 1 | +# Country Data Requirements |
| 2 | +Guide for adding a new country to the static Region Identifier dataset. Each supported country needs three JSON files plus a small code change. |
| 3 | + |
| 4 | +## 1) Country config – `country/ISO3.json` |
| 5 | +- Keys: |
| 6 | + - `zipCodeFormat`: `"numeric"` or `"alpha"`. |
| 7 | + - `zipCodeLength`: integer, required for numeric formats to pad/compare values (USA=5, AUS=4, DEU=5, etc.). Omit for alpha formats (CAN/GBR/NLD). |
| 8 | +- Example: |
| 9 | +```json |
| 10 | +{ "zipCodeFormat": "numeric", "zipCodeLength": 5 } |
| 11 | +``` |
| 12 | + |
| 13 | +## 2) Region names – `regionNames/ISO3.json` |
| 14 | +- Plain object mapping ISO 3166-2 region codes (same codes used in `regions/*.json`) to display names in English. |
| 15 | +- Example (`regionNames/AUS.json`): |
| 16 | +```json |
| 17 | +{ |
| 18 | + "AU-NSW": "New South Wales", |
| 19 | + "AU-VIC": "Victoria" |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +## 3) Region mappings – `regions/ISO3.json` |
| 24 | +Array of objects that map postal codes to ISO 3166-2 region codes. Formats already used in the repo: |
| 25 | +- **Numeric intervals** (inclusive): objects with `low`, `high`, `region`. Values can be numbers or numeric strings if leading zeros matter. Example (`regions/AUS.json`): |
| 26 | +```json |
| 27 | +{ "region": "AU-NSW", "low": 1000, "high": 1999 } |
| 28 | +``` |
| 29 | +- **Explicit codes**: objects with `low`, `region`, no `high`. Every postal code (or prefix) must be listed. Use strings to preserve zeros. Examples: |
| 30 | + - Belgium lists every 4-digit code (`regions/BEL.json`). |
| 31 | + - Spain lists 5-digit codes as strings (`regions/ESP.json`). |
| 32 | + - Mexico lists 2-digit prefixes (`regions/MEX.json`). |
| 33 | + - CAN/GBR use alpha prefixes (e.g., `"low": "X0A"` or `"low": "AB"`). |
| 34 | +- **Discrete lists**: objects with `region` and `list` (array of codes). Numeric countries store numbers; matching uses `zipCodeLength` to pad leading zeros before comparison. Examples: USA (`list` of 5-digit numbers), RUS (per-region lists). |
| 35 | + |
| 36 | +Additional format notes: |
| 37 | +- Files can mix formats if needed. Order matters because the lookup stops at the first match. |
| 38 | +- Intervals and lists are treated as inclusive ranges; for alpha codes only exact equality is used. |
| 39 | +- Keep codes as strings when leading zeros are significant. |
| 40 | + |
| 41 | +## 4) Code wiring |
| 42 | +- Add the ISO3 code to `availableCountries` in `lib/region.js`; otherwise the static data is ignored and Google is used. |
| 43 | +- If the country needs custom postal-code normalization, extend `validateZipCode` (see existing cases for GBR, CAN, NLD, MEX). |
| 44 | + |
| 45 | +## 5) Testing |
| 46 | +- Add test cases to `test/tests.js` under `countriesPostalCodes`: include the country ISO/name, a representative zip, expected region code, and set `usingGoogle: false`. |
| 47 | +- Run `npm test` to execute Mocha tests. |
| 48 | +- Optional: verify pretty-name lookups via `getNameFromCountryAndRegion` using the `regionNames` file. |
| 49 | + |
| 50 | +## 6) Data quality checklist |
| 51 | +- Region codes must be valid ISO 3166-2 for the country. |
| 52 | +- `regionNames` should be English and cover every region code present in `regions/ISO3.json`. |
| 53 | +- Postal-code coverage should include territories and edge prefixes (e.g., US territories, Canadian northern prefixes). |
| 54 | +- Prefer ascending ordering of `regions` entries to keep matching predictable. |
| 55 | +- Avoid empty mappings; placeholders (e.g., empty lists) will yield null regions and fall back to Google. |
0 commit comments