# @bluehive/zipcodes 中文文档

规范地址：https://npmcn.com/package/%40bluehive/zipcodes/

版本：8\.0\.4
npm 元数据更新时间：2024-04-11T16:23:38.875Z
中文译文更新时间：2026-11-08T08:30:52.984Z
软件包许可：BSD

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bluehive/zipcodes
原文对照：https://npmcn.com/package/%40bluehive/zipcodes/?lang=original
项目主页：https://github.com/bluehive-health/zipcodes#readme
源码仓库：https://github.com/bluehive-health/zipcodes

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.9 MB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2024-04-11T04:26:30.231Z
- 最新版本发布：2024-04-11T04:26:30.575Z
- 近 30 天下载量：22309（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

有帮助方法的有用zipcode数据库(更新)

## 安装

```sh
npm install @bluehive/zipcodes
```

也可以使用：`pnpm add @bluehive/zipcodes`、`yarn add @bluehive/zipcodes`、`bun add @bluehive/zipcodes`

## README

# 美国Zip代码查询(数据最后更新,2024年4月10日)

本地化( 平面文件) zipcode 查询( 只有美国)

美国的拉链代码来自: [https://postalpro.usps.com/ZIP locale Detail (英语)](https://postalpro.usps.com/ZIP_Locale_Detail)

被转换成JSON对象后再用一些帮助方法包裹.

## 使用量

```
const zipcodes = require('zipcodes');
```

### Zipcode 查询

```
const hills = zipcodes.lookup(90210);

{
  zip: '90210',
  latitude: 34.088808,
  longitude: -118.406125,
  city: 'Beverly Hills',
  state: 'CA',
  country: 'US'
}
```

### 距离

这不是驾驶距离 而是视线距离

```
var dist = zipcodes.distance(62959, 90210); //In Miles
// dist = 1662

var kilo = zipcodes.toKilometers(dist); //Convert to Kilometers
// kilo = 2675

var miles = zipcodes.toMiles(zipcodes.toKilometers(dist)); //Convert to Kilometers, then to miles
// miles = 1662
```

### 按名称查找

_这对加拿大的数据不起作用,数据文件没有包含这个细节._

```
var l = zipcodes.lookupByName('Cupertino', 'CA');

//Always returns an array, since cities can have multiple zip codes
[
  {
    zip: '95015',
    latitude: 37.323,
    longitude: -122.0527,
    city: 'Cupertino',
    state: 'CA',
    country: 'US'
  }
]
```

### 半径搜索

获取此zipcode 的 milage 半径范围内的所有 zipcode

```
var rad = zipcodes.radius(95014, 50);
// rad.length == 385

[ '93901',
  '93902',
  '93905',
  '93906',
  '93907',
  '93912',
  '93933',
  '93942',
  '93944',
  '93950',
  ...
  '95377',
  '95378',
  '95385',
  '95387',
  '95391' 
]
```

### 随机编程

```
var zipObj = zipcodes.random();

{ 
  zip: '90210',
  latitude: 34.088808,
  longitude: -118.406125,
  city: 'Beverly Hills',
  state: 'CA',
  country: 'US'
}
```

## 开始

添加导入到 MongoDB 或 CouchDB 的支援, 以加速搜索 .

## 发展

我用于此数据的 CSV 原始文件没有包含在本 repo 中, 但我确实收尾了 用于获取数据的最佳方式以及如何将其转换成本模块使用的格式.

为了开发这个模块 `make` 它将获取最新的zipcode并重新处理.

```
make
```

要获取和处理zipcode:

```
make codes
```

要运行非常简单的测试套件:

```
make tests
```

## 常见问题

### @bluehive/zipcodes 是什么？

有帮助方法的有用zipcode数据库\(更新\)

### 如何安装 @bluehive/zipcodes？

在项目目录运行 npm install @bluehive/zipcodes，或使用 pnpm add / yarn add / bun add。

### @bluehive/zipcodes 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bluehive\_\_zipcodes 是否存在。

### @bluehive/zipcodes 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bluehive/zipcodes 可以商用吗？

@bluehive/zipcodes 使用 BSD 许可。声明的许可为 BSD，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @bluehive/zipcodes 的下载量有多少？

根据 npm 官方下载统计，@bluehive/zipcodes 在 2026/10/09 – 2026/11/07 这 30 天内被下载 22,309 次，日均约 744 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bluehive/zipcodes 还在维护吗？

最新版本 8\.0\.4 发布于 2024/04/11（2 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。