@ 国家/ 国家

官方国家、州和城市数据库有iOS/Safari支持,最小捆绑大小.

环境: 🖥️ 仅服务器侧 (Node.js, Next.js API线路,快递等)

升级到 3. 0

此版本使用 v5.2.0-出口。审查 上游 v5 迁移说明 在更新所储存的身份证之前:一些记录被退役或被修复。 城市状态链接现在可以无效 。 全国城市装载机包括这些记录。 保留供应 NOTICE-*.txt 带有重新分配数据的文件。 见 软件包迁移指南。 。 。 .

较早的移徙: 2.0.0

现在的数据来自上游 v 4.0出口.50. v3.2 → v 4.0 过渡取消了4,486个城市标识(重复,美国各县迁移到一个单独的县数据集,不设地),将7,527个城市重新分配到不同的州,在退休时又增加了27个州. 存储的ID和每个州的结果都可以改变;美国县不再作为城市返回. 后来的导出更正包含在本快照中.

在升级存储的城市/州编号之前, 使用 removed_ids_v3.2_to_v4.0.csv 页:1 上游 v 4.0 释放它确定了合并的身份证及其幸存者、迁移到新身份证的县以及退休的州及其继任者。 符合 record, (中文(简体) ), outcome,以及 new_table 使用前的列 new_id;一个县ID不是城市ID. 根据这个快照刷新存储的州协会 .

城市 type 使用标准术语(municipality, (中文(简体) ), city, (中文(简体) ), town, (中文(简体) ), village, (中文(简体) ), locality, (中文(简体) ), section对于移徙国家;其他国家可以保留较早的用语,例如: adm1编号 :adm2。本套件有意对上游领域进行子集项目: type_local, (中文(简体) ), county_id, (中文(简体) ), level,以及 parent_id 在城市/州记录中省略,不运出县数据集。 城市翻译为空对象;包含国家翻译. 当您需要正式的本地术语、 县级链接或分级时, 使用上游出口 .

* 特性

• 🌍 完整数据:250+国家,5 000+州,15万+城市
• 📱 iOS 兼容: Safari/iOS 浏览器上没有堆栈溢出错误
• 🚀 最小套装: < 10KB 初始负载, 懒散地装入其他所有负载
• 🔄 懒惰装入: 动态进口,以达到最佳性能
• 🌐 翻译: 支持18+语言
• ⏰ 时区数据: 每个地点的全时区信息
• 📝 类型脚本: 包括完整类型定义
• 🔧 可树动: 只捆绑您使用的

为什么是这个包裹?

大众 country-state-city 软件包(162K每周下载)有关键问题:

• QQ 8MB 捆绑大小( 包括全部数据)
• iOS Safari 有堆叠溢出错误的崩溃
• 未保存2年以上
• 静态进口强制整捆

此套件解决了其中每一个问题:

• 最小捆绑( < 10KB 初始)
• 动态导入和懒惰加载
• iOS/Safari 兼容
• QQ 总是从权威数据库更新
• & 代码可分割

* 安装

npm install @countrystatecity/countries
# or
yarn add @countrystatecity/countries
# or
pnpm add @countrystatecity/countries

仅使用服务器:此软件包需要Node.js文件系统访问,无法在浏览器环境中被使用. 用于前端, 安装 @countrystatecity/countries-browser 相反——相同的API,在React/Vue/Svelte/Vite中工作.

QQ 快速启动

import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries';

// Get all countries (lightweight - ~5KB)
const countries = await getCountries();
console.log(countries[0]);
// { id: 1, name: "United States", iso2: "US", emoji: "🇺🇸", ... }

// Get all states in a country (~10-100KB depending on country)
const states = await getStatesOfCountry('US');
console.log(states[0]);
// { id: 1, name: "California", iso2: "CA", ... }

// Get all cities in a state (~5-200KB depending on state)
const cities = await getCitiesOfState('US', 'CA');
console.log(cities[0]);
// { id: 1, name: "Los Angeles", latitude: "34.05", ... }

本地包还是活的API?

这个软件包传输了一个免费的,离线能力的数据快照——当应用程序必须离线工作时,这仍然是正确的选择,周期快照就足够了,或者你只需要简单的看/倒.

这个 国家 API 当您需要时, 值得同时加入:

• 新鲜度 ——不发布新包版本而更新的数据.
• 搜索 模糊、耐打字、服务器侧搜索(csc.search.fuzzy(...)),而不只是精确匹配的本地外观.
• 缩放支持( S) ——可配置的速率限制和超过捆绑快照的支持.

每月有3 000个请求免费开始. 比较计划 或者说 获取 API 密钥。 。 。 .

npm install @countrystatecity/sdk

// Before
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries';

const countries = await getCountries();
const states = await getStatesOfCountry('US');
const cities = await getCitiesOfState('US', 'CA');

// After
import { createCSCClient } from '@countrystatecity/sdk';

const csc = createCSCClient({ apiKey: process.env.CSC_API_KEY! });

const { data: countries } = await csc.countries.list();
const { data: states } = await csc.states.list({ country: 'US' });
const { data: cities } = await csc.cities.list({ country: 'US', state: 'CA' });

见 完整移徙指南 用于错误处理、重试等等.

API 参考

核心职能

getCountries()

获得所有国家的轻量级列表(仅基本信息).

• 回返情况: Promise<ICountry[]>
• 套装影响 : ~ 5KB 键

getCountryByCode(countryCode: string)

获得完整的国家元数据,包括时区和翻译.

• 参数: countryCode - ISO2代码(例如“美国”)
• 回返情况: Promise<ICountryMeta | null>
• 套装影响 : 每个国家~5KB

getStatesOfCountry(countryCode: string)

为一国取出一切州/道.

• 参数: countryCode - ISO2 代码
• 回返情况: Promise<IState[]>
• 套装影响 : ~10-100KB,视国家而定

getStateByCode(countryCode: string, stateCode: string)

获取具体状态细节.

• 参数: countryCode, (中文(简体) ), stateCode
• 回返情况: Promise<IState | null>

getCitiesOfState(countryCode: string, stateCode: string)

将所有城市都控制在特定状态.

• 参数: countryCode, (中文(简体) ), stateCode
• 回返情况: Promise<ICity[]>
• 套装影响 : ~5-200KB 取决于状态

getAllCitiesOfCountry(countryCode: string)

把全国的城市都找来.

• 警告: 较大数据大小, 少用
• 回返情况: Promise<ICity[]>

getAllCitiesInWorld()

遍及全球.

• 警告: MASSIVE数据(8MB+),极少需要
• 回返情况: Promise<ICity[]>

getRegions()

获取所有地区(大陆)列表.

• 回返情况: Promise<IRegion[]>
• 套装影响 : ~ 3KB 键

getSubregions()

获取所有分区列表 .

• 回返情况: Promise<ISubregion[]>
• 套装影响 : ~13KB (英语)

工具函数

isValidCountryCode(countryCode: string)

检查国家代码是否存在 .

• 回返情况: Promise<boolean>

isValidStateCode(countryCode: string, stateCode: string)

检查一个国家是否存在国家代码 .

• 回返情况: Promise<boolean>

searchCitiesByName(countryCode: string, stateCode: string, searchTerm: string)

以部分名称匹配搜索城市.

• 回返情况: Promise<ICity[]>

getCountryNameByCode(countryCode: string)

从代码中获取国名.

• 回返情况: Promise<string | null>

getStateNameByCode(countryCode: string, stateCode: string)

从代码中获取州名.

• 回返情况: Promise<string | null>

getTimezoneForCity(countryCode: string, stateCode: string, cityName: string)

获取特定城市的时区.

• 回返情况: Promise<string | null>

getCountryTimezones(countryCode: string)

得到所有的时间区 一个国家.

• 回返情况: Promise<string[]>

getSubregionsOfRegion(regionId: number)

把属于某个区域的所有次区域都弄来.

• 回返情况: Promise<ISubregion[]>

getCountriesByRegion(region: string | number)

将区域内的所有国家按名称排列(如对案件不敏感). 'Europe')或区域身份证.

• 回返情况: Promise<ICountry[]>

getCountriesBySubregion(subregion: string | number)

将分区域的所有国家按名称排列(对案件不敏感,例如:. 'South America'或次区域身份证.

• 回返情况: Promise<ICountry[]>

QQ 类型脚本

import type { ICountry, ICountryMeta, IState, ICity, IRegion, ISubregion, ITimezone } from '@countrystatecity/countries';

QQ 套装大小

160个小包!

测试

# Run all tests
npm test

# Run iOS compatibility tests specifically
npm run test:ios

# Watch mode
npm run test:watch

所有软件包包括全面测试:

• 单位测试
• 综合测试
• iOS/Safari兼容性测试

++CI/CD和自动化

持续整合

每一次推和公关自动:

• QQ 运行类型检查
• * 执行全面测试
• QQ 构建软件包
• 校验捆绑大小
• iOS/Safari 兼容性测试

自动出版

自动向国家预防机制发布版本变化:

• QQ 检测软件包中的版本出错. json
• 发布前的构建和测试
• 国家防范机制登记册出版物
• QQ 创建带有更改日志的 GitHub 发布

许可证

ODbL-1.0. 导弹 © 驱动器5hn

此软件包及其数据由开放数据库许可证(ODbL)v1.0许可. 数据来源于 国家城市数据库 也根据ODbL-1.0获得许可证.

您可以自由分享,创建,并修改这个数据库,只要您将原始源属性化,在同一许可证下发布修改,并且不要使用技术限制来锁定数据.

捐款

欢迎捐款! 请打开一个问题或公关.

数据相关问题 (不正确的国名、缺失的城市、错误的坐标等) 国家城市数据库 寄存器,是此软件包的数据源.

成套生态系统

此软件包是 @ 国家状态包生态系统数字 :

• @ 国家/ 国家 (本套件)——服务器侧国家,州,和城市数据库. 环境:Node.js, Next.js API路线,快通. Bundle: <10KB初始负载.

• @ 国家状态/ 国家浏览器 – 有jsDelivr CDN和懒惰加载的浏览器-本地版本. 环境:React,Vue,Svelte,Vite,任意浏览器. 与这个软件包相同的 API——零配置,只是导入和使用.

• @ 国家状态/ 时区 - 具有转换功能的综合时区数据。 环境:只有服务器侧. Bundle: <20KB初始负载.

环境指南

使用此软件包( E)@countrystatecity/countries当:

• QQ 构建 API 端点或后端
• 使用 Next.js App 路由器服务器组件
• QQ 在 Node.js 中运行,无服务器功能(Vercel, AWS Lambda)
• QQ 有文件系统访问
• 建设命令行工具

浏览器/ 前端使用 :

使用 @countrystatecity/countries-browser ——同名API,直接在React,Vue,Svelte,Vite工作:

npm install @countrystatecity/countries-browser

import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

const countries = await getCountries();
const states = await getStatesOfCountry('US');
const cities = await getCitiesOfState('US', 'CA');

链接

• GitHub 仓库
• 问题
• 国家防范机制一揽子计划
• 国家预防机制组织