{"_id":"country-iso-search","_rev":"11-ea6c6d8b2a72cd45f28782e363155c2e","name":"country-iso-search","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"country-iso-search","version":"0.1.0","keywords":["iso","iso-3166","iso-3166-1","country","countries","country-codes","alpha-3","alpha-2","m49","un-m49"],"author":{"name":"Plotly, Inc."},"license":"MIT","_id":"country-iso-search@0.1.0","maintainers":[{"name":"packages-team-plotly","email":"packages@plot.ly"}],"contributors":[{"name":"Cameron DeCoster","email":"cameron.decoster@plot.ly"}],"homepage":"https://github.com/plotly/country-iso-search#readme","bugs":{"url":"https://github.com/plotly/country-iso-search/issues"},"dist":{"shasum":"7f4a9bff915f528e2202d8c4e4795e99e160d8c9","tarball":"https://registry.npmjs.org/country-iso-search/-/country-iso-search-0.1.0.tgz","fileCount":9,"integrity":"sha512-/nxJqaLw6ryFD+ZsCJO8qEPivuB1o7cnDfa/a18+lkDKYMUH2lY59W0pCa7idlZbtxxYqJjfR3ii8Zr9OsvVtA==","signatures":[{"sig":"MEUCICD0DeDB2Ai+xINfvvu5c/c/pM8KmIauqJVFOiCCLs9qAiEA8JJycFEEUrPgfP2V8x0oKJHPZZ8ezMAPCEmh7I2srBU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":204277},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"8e61bd4bd431f81ea0dfe106367c2725536f2bc5","scripts":{"lint":"biome check .","test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --clean","format":"biome check --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"packages-team-plotly","email":"packages@plot.ly"},"repository":{"url":"git+https://github.com/plotly/country-iso-search.git","type":"git"},"_npmVersion":"10.9.8","description":"Resolve country names, codes, and aliases to canonical ISO 3166-1 alpha-3 codes.","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.9","typescript":"^6.0.3","@biomejs/biome":"^2.5.0"},"_npmOperationalInternal":{"tmp":"tmp/country-iso-search_0.1.0_1782144503512_0.8519693904543302","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"country-iso-search","version":"0.1.1","keywords":["iso","iso-3166","iso-3166-1","country","countries","country-codes","alpha-3","alpha-2","m49","un-m49"],"author":{"name":"Plotly, Inc."},"license":"MIT","_id":"country-iso-search@0.1.1","maintainers":[{"name":"packages-team-plotly","email":"packages@plot.ly"}],"contributors":[{"name":"Cameron DeCoster","email":"cameron.decoster@plot.ly"}],"homepage":"https://github.com/plotly/country-iso-search#readme","bugs":{"url":"https://github.com/plotly/country-iso-search/issues"},"dist":{"shasum":"ac3b1d9e86e113770e67723bac455c5499a66562","tarball":"https://registry.npmjs.org/country-iso-search/-/country-iso-search-0.1.1.tgz","fileCount":9,"integrity":"sha512-JJxdoVmgZW3F4DdQ4Jq3NuVfqsk6XoHq8PE8QXNIv1BVwAKyJum2dahC7hsW+v60xwH7pm7g8BwCJ05aUabApg==","signatures":[{"sig":"MEQCIHiTLFSlWiBNw25xK5z40wNlLe4qkzbAlrHiMdWgtQaZAiBSpmNQTuKdCuizf2OBR/VQudjeXWRzpmTm1v0nCDFy3Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":207808},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"878c3a8a140aade85e109088d3e8edbc34fcda9d","scripts":{"lint":"biome check .","test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --clean","format":"biome check --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"packages-team-plotly","email":"packages@plot.ly"},"repository":{"url":"git+https://github.com/plotly/country-iso-search.git","type":"git"},"_npmVersion":"10.9.8","description":"Resolve country names, codes, and aliases to canonical ISO 3166-1 alpha-3 codes.","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.9","typescript":"^6.0.3","@biomejs/biome":"^2.5.0"},"_npmOperationalInternal":{"tmp":"tmp/country-iso-search_0.1.1_1782151740099_0.19909285715325375","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"country-iso-search","version":"0.1.2","keywords":["iso","iso-3166","iso-3166-1","country","countries","country-codes","alpha-3","alpha-2","m49","un-m49"],"author":{"name":"Plotly, Inc."},"license":"MIT","_id":"country-iso-search@0.1.2","maintainers":[{"name":"chriddyp","email":"chris@plot.ly"},{"name":"bpostlethwaite","email":"post.ben.here@gmail.com"},{"name":"antrg","email":"antoine@plot.ly"},{"name":"bronsolo","email":"chuck@plot.ly"},{"name":"t4rk","email":"t4rk@outlook.com"},{"name":"ndrezner","email":"nathan@drezner.xyz"},{"name":"roman-nb","email":"roman@plot.ly"},{"name":"camdecoster","email":"cameron.decoster@gmail.com"},{"name":"alexcjohnson","email":"alex@plot.ly"},{"name":"emilykl-plotly","email":"emily@plot.ly"},{"name":"packages-team-plotly","email":"packages@plot.ly"}],"contributors":[{"name":"Cameron DeCoster","email":"cameron.decoster@plot.ly"}],"homepage":"https://github.com/plotly/country-iso-search#readme","bugs":{"url":"https://github.com/plotly/country-iso-search/issues"},"dist":{"shasum":"7b294927bc9a810caa16a46dcf3524f1c3d0f22e","tarball":"https://registry.npmjs.org/country-iso-search/-/country-iso-search-0.1.2.tgz","fileCount":9,"integrity":"sha512-7VMhhWPSNg/ivAUwp3BvxEGDycCfqiTggaV+hAW+N5+F+jzbEuY5HqvSMnGeP9CxKXBWO0fydbUgLUHmKj89vA==","signatures":[{"sig":"MEYCIQCvyGMFfQ7YlVhn0n0fDweM2/yOswZ9Y6+jAZaL9vw1BwIhAM6ZbNGb5nmkHUCp/frt7ARnO9Y4uv4Un0p7PDz+OtIh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":209267},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=20"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"e3786706bf73fdbab56c92f98e8086962b454100","scripts":{"lint":"biome check .","test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --clean","format":"biome check --write .","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"camdecoster","email":"cameron.decoster@gmail.com"},"repository":{"url":"git+https://github.com/plotly/country-iso-search.git","type":"git"},"_npmVersion":"10.9.8","description":"Resolve country names, codes, and aliases to canonical ISO 3166-1 alpha-3 codes.","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.9","alpinejs":"^3.15.12","typescript":"^6.0.3","@biomejs/biome":"^2.5.0"},"_npmOperationalInternal":{"tmp":"tmp/country-iso-search_0.1.2_1787855264542_0.022659016913746166","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-22T16:08:23.455Z","modified":"2026-09-14T15:41:53.129Z","0.1.0":"2026-06-22T16:08:23.653Z","0.1.1":"2026-06-22T18:09:00.269Z","0.1.2":"2026-08-27T18:27:44.695Z"},"bugs":{"url":"https://github.com/plotly/country-iso-search/issues"},"author":{"name":"Plotly, Inc."},"license":"MIT","homepage":"https://github.com/plotly/country-iso-search#readme","keywords":["iso","iso-3166","iso-3166-1","country","countries","country-codes","alpha-3","alpha-2","m49","un-m49"],"repository":{"url":"git+https://github.com/plotly/country-iso-search.git","type":"git"},"description":"Resolve country names, codes, and aliases to canonical ISO 3166-1 alpha-3 codes.","contributors":[{"name":"Cameron DeCoster","email":"cameron.decoster@plot.ly"}],"maintainers":[{"email":"chris@plot.ly","name":"chriddyp"},{"email":"post.ben.here@gmail.com","name":"bpostlethwaite"},{"email":"antoine@plot.ly","name":"antrg"},{"email":"chuck@plot.ly","name":"bronsolo"},{"email":"t4rk@outlook.com","name":"t4rk"},{"email":"roman@plot.ly","name":"roman-nb"},{"email":"cameron.decoster@gmail.com","name":"camdecoster"},{"email":"alex@plot.ly","name":"alexcjohnson"},{"email":"adrian.borrmann@plot.ly","name":"aborrmann"},{"email":"emily@plot.ly","name":"emilykl-plotly"},{"email":"packages@plot.ly","name":"packages-team-plotly"}],"readme":"# country-iso-search\n\n[![npm](https://img.shields.io/npm/v/country-iso-search)](https://www.npmjs.com/package/country-iso-search)\n[![Test](https://github.com/plotly/country-iso-search/actions/workflows/test.yml/badge.svg)](https://github.com/plotly/country-iso-search/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/npm/l/country-iso-search)](LICENSE)\n\nResolve country names and codes to their canonical ISO 3166-1 alpha-3 form.\n\n<br/>\n<div align=\"center\">\n  <a href=\"https://dash.plotly.com/project-maintenance\">\n    <img src=\"https://dash.plotly.com/assets/images/maintained-by-plotly.png\" width=\"400px\" alt=\"Maintained by Plotly\">\n  </a>\n</div>\n<br/>\n\n---\n\n**[Try it in the browser →](https://plotly.github.io/country-iso-search/demo/)** — enter a query and see what resolves. Source in [`demo/`](demo/).\n\nAccepts alpha-3 (`\"FRA\"`), alpha-2 (`\"FR\"`), UN M49 numeric (`250`, `\"250\"`, `\"04\"`, or `\"0250\"` — leading zeros are stripped and the result is zero-padded to 3 digits), or a country name / alias. Name/alias matching is case-insensitive and input is sanitized before comparison: diacritics are stripped (`Türkiye` → `turkiye`), apostrophes and `.` `()` `[]` `,` are dropped, `&` becomes `and`, `-`/`–`/`—` become spaces, `st` expands to `saint`, `the` is dropped when it leads the input or follows `,`/`(` (so ISO short-name forms like `Korea (the Republic of)` and `Korea, the Republic of` both resolve), and internal whitespace is collapsed. Returns the canonical alpha-3, or `undefined` when no record matches.\n\n## Install\n\n```bash\nnpm install country-iso-search\n```\n\n## Usage\n\n```ts\nimport { lookup, lookupAlpha3 } from 'country-iso-search';\n\nlookupAlpha3('FRA');                 // 'FRA'\nlookupAlpha3('FR');                  // 'FRA'\nlookupAlpha3(250);                   // 'FRA' (M49 numeric)\nlookupAlpha3('04');                  // 'AFG' (zero-padded to '004')\nlookupAlpha3('0250');                // 'FRA' (leading zeros stripped)\nlookupAlpha3('France');              // 'FRA'\nlookupAlpha3('Burma');               // 'MMR' (historical name)\nlookupAlpha3('Türkiye');             // 'TUR'\nlookupAlpha3('cote d ivoire');       // 'CIV' (apostrophes / diacritics ignored)\nlookupAlpha3('St. Kitts and Nevis'); // 'KNA'\nlookupAlpha3('🇯🇵');                  // 'JPN' (flag emoji)\nlookupAlpha3('not a country');       // undefined\n\n// `lookup` returns the full record:\nlookup('France')?.iso2;              // 'FR'\nlookup('France')?.m49;               // '250'\n```\n\n## Custom records\n\nNeed codes for sub-national regions, historical countries, disputed areas, or anything else outside ISO 3166-1? Pass your own records to `createLookup` and use the returned scoped helpers. Spread `COUNTRIES` to layer custom records on top of the canonical data:\n\n```ts\nimport { createLookup, COUNTRIES, type CountryRecord } from 'country-iso-search';\n\nconst CUSTOM: CountryRecord[] = [\n    { iso3: 'XAC', iso2: '', m49: '', name: 'Aksai Chin', aliases: [] },\n    { iso3: 'XJK', iso2: '', m49: '', name: 'Jammu and Kashmir', aliases: [] },\n];\n\nconst { lookupAlpha3, lookup, byAlpha3, byAlpha2, byM49 } = createLookup([\n    ...COUNTRIES,\n    ...CUSTOM,\n]);\n\nlookupAlpha3('FRA');               // 'FRA' (canonical)\nlookupAlpha3('XAC');               // 'XAC' (custom)\nlookupAlpha3('Aksai Chin');        // 'XAC'\n```\n\nLeave `iso2` and `m49` blank on user-assigned codes — `createLookup` skips blank values when building the `byAlpha2` and `byM49` maps. Cross-country alias collisions throw at construction time so they can be fixed before any lookups happen.\n\n## API\n\n### `lookupAlpha3(input)`\n\n- `input: string | number` — country identifier in any supported form.\n- Returns `string | undefined`.\n\n### `lookup(input)`\n\nSame input shape as `lookupAlpha3`, but returns the full `CountryRecord` (or `undefined`). Use this when you need `iso2`, `m49`, the canonical `name`, or the `aliases` list instead of just the alpha-3.\n\n### `createLookup(records)`\n\n- `records: ReadonlyArray<CountryRecord>` — every record the returned lookup should resolve.\n- Returns `{ lookup, lookupAlpha3, byAlpha3, byAlpha2, byM49 }` scoped to those records.\n- Throws on cross-record name/alias collisions (after sanitization).\n\nThe top-level `lookup` / `lookupAlpha3` and `byAlpha3` / `byAlpha2` / `byM49` exports are a `createLookup(COUNTRIES)` instance.\n\n### `sanitize(input)`\n\n- `input: string` — text to normalize.\n- Returns the same string lowercased with diacritics / apostrophes / `.` `()` `[]` `,` stripped, `&` mapped to `and`, hyphen-likes turned into spaces, `st` expanded to `saint`, and `the` dropped when it leads the input or follows `,`/`(`. Exported for advanced use — call it to produce keys consistent with the internal name/alias index.\n\n### Exports\n\n- `COUNTRIES: ReadonlyArray<CountryRecord>` — the bundled ISO 3166-1 / M49 records.\n- `byAlpha3`, `byAlpha2`, `byM49` — `ReadonlyMap<string, CountryRecord>` lookups over `COUNTRIES` (use `.get(key)`; e.g. `byAlpha3.get('FRA')?.name`).\n- `CountryRecord`, `CountryLookup` — TypeScript types.\n\n### `CountryRecord`\n\n```ts\ninterface CountryRecord {\n    iso3: string;               // ISO 3166-1 alpha-3\n    iso2: string;               // ISO 3166-1 alpha-2 (may be blank on custom records)\n    m49: string;                // UN M49, 3-digit zero-padded (may be blank on custom records)\n    name: string;               // English short name from UN M49\n    aliases: readonly string[]; // additional lowercased forms — historical names,\n                                //   common alternates, native-language variants,\n                                //   and the country's flag emoji\n}\n```\n\n## Data\n\n`COUNTRIES` mirrors UN M49 / ISO 3166-1 for `iso3`, `iso2`, `m49`, and `name`. The ~1,700 aliases were assembled from CLDR, Wikidata (filtered to languages tagged official via P37), and GeoNames, then **curated by hand** to resolve substring collisions (e.g. Niger vs. Nigeria, Guinea vs. Guinea-Bissau vs. Equatorial Guinea vs. Papua New Guinea), normalize transliterations, and drop variants that would produce false matches. Aliases are stored in their sanitized form (diacritics / apostrophes / punctuation stripped, hyphens turned into spaces, `st` expanded to `saint`), so don't add accented or punctuated variants by hand — `lookupAlpha3` applies the same transform to user input at lookup time. To add an alias or fix an entry, edit [src/countries.ts](src/countries.ts) directly and open a pull request.\n\nGeoNames (CC BY 4.0) and Unicode CLDR (Unicode License V3) require attribution. The full third-party notices live in [NOTICE](NOTICE) in this repository — **consult that file before redistributing this package or its data**, since it carries the attribution texts those licenses require to travel with downstream redistributions. Wikidata is CC0 and is acknowledged there as a courtesy.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Third-party data attributions: [NOTICE](NOTICE).\n","readmeFilename":"README.md"}