# @aivangogh/ph-address 中文文档

规范地址：https://npmcn.com/package/%40aivangogh/ph-address/

版本：2026\.2\.4
npm 元数据更新时间：2026-10-07T02:12:14.969Z
中文译文更新时间：2026-11-06T00:58:35.607Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aivangogh/ph-address
原文对照：https://npmcn.com/package/%40aivangogh/ph-address/?lang=original
项目主页：https://aivangogh.dev/tools/ph-address
源码仓库：https://github.com/aivangogh/ph-address

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

- 包体积（解压后）：871 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2024-07-18T12:55:38.338Z
- 最新版本发布：2026-10-07T02:12:14.665Z
- 近 30 天下载量：7618（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 23 个）

## 中文简介

菲律宾基于PSGC的地理和邮政编码数据

## 安装

```sh
npm install @aivangogh/ph-address
```

也可以使用：`pnpm add @aivangogh/ph-address`、`yarn add @aivangogh/ph-address`、`bun add @aivangogh/ph-address`

## README

 [![](https://img.shields.io/npm/l/@aivangogh/ph-address)](https://npmcn.com/package/%40aivangogh/ph-address/LICENCE)[![](https://img.shields.io/npm/v/@aivangogh/ph-address) ](https://www.npmjs.com/package/@aivangogh/ph-address)[![](https://img.shields.io/npm/dt/@aivangogh/ph-address)](https://www.npmjs.com/package/@aivangogh/ph-address)

# PH-地址

包含官员的轻量级菲律宾地址数据包 [菲律宾标准地理代码](https://psa.gov.ph/classification/psgc/) 截至2026年6月30日的地理等级和单独的邮政编码绘图.

[探索菲律宾地址数据](https://aivangogh.dev/tools/ph-address)

## 特征

-   **地址数据**:PSGC地区,省,市,市,镇,外加菲律宾邮政编码测绘.
-   **超光度**: 使用 CSV + gzip 压缩高度优化的捆绑大小(~373 KB dist)——比上个格式小40%.
-   **快速性能**: 高效数据加载自动缓存. barangay数据(42k行)分解和剖析为~39ms的一通;之后的通话几乎是即时的.
-   **完全输入**: 以 TypeScript 写成,以获得更完善的开发者在完整类型定义方面的经验.
-   **易于使用**:一个简单而直观的API,用于检索地区,省,市,镇.
-   **0 配置**:在Node.js和浏览器环境中工作出框.

## 节点.js和浏览器支持

这个软件包支持Node.js 18或更新的和浏览器,同时具有ConferenceJS(`require()`和无害环境管理`import`) 语法. 数据直接与代码相捆绑,使用高效的压缩,因此它无缝工作而不需要文件系统访问.

## 地址数据模型

### PSGC 地理代码

![PSGC Revision 1 10-digit coding structure](https://npmcn.com/package/%40aivangogh/ph-address/assets/psgc/coding-structure.png)

PSGC 第1修订版使用10位数 `RR-PPP-MM-BBB` 结构 :

| 部分 | 含义 |
| --- | --- |
| `RR` | 地区 |
| `PPP` | 省或高度城市化的城市(HUC) |
| `MM` | 市镇或城市 |
| `BBB` | 村镇 |

### 邮政编码

菲律宾邮政编码是独立的四位数快递区标识. 它们补充了PSGC代码,但并不是从中衍生出来的:一个市镇可以有多个邮政编码,一个邮政编码可以覆盖多个地方.

### 性能特征

-   **套装大小**:~373 KB (dist/index.mjs)——比上个格式小40%
-   **初始化**: ~39 ms 给一线的村长( 降压和缓存所有数据)
-   **随后的呼叫**: < 1ms(数据被缓存于内存)

该套件使用带有gzip压缩的CSV来达到最佳大小和剖析速度. 数据在第一次使用时自动解压缩并缓存,以便在随后的通话中即时访问.

### 格式 基准

基准42,010个镇行(20个中位数):

| 格式 | 压缩大小 | 解压+解析 |
| --- | --- | --- |
| 贾森 | 586个KB | 81分钟 |
| CSV 装满 | 477个KB | 77分钟 |
| **CSV 优化** (当前) | **346个KB** | **39分钟** |

CSV优化了从10位数的PSGC代码结构中可以生成的列去除,然后在负载时间——更小的有效载荷和更小的剖析出.

## 版本

此软件包使用基于日历的版本方案 : `YYYY.Q.P`

-   `YYYY`:PSGC数据出版年份.
-   `Q`: 出版物的季度(1、2、3或4).
-   `P`:用于任何错误修复或改进包本身的补丁编号,该补丁编号随每个新的季度发布而重新发布.

例如,版本 `2025.3.1` 表示数据来自 **2025年第一季度**,与 `1` 补丁发布.

## 安装

```bash
# Using npm
npm install @aivangogh/ph-address

# Using yarn
yarn add @aivangogh/ph-address

# Using pnpm
pnpm add @aivangogh/ph-address
```

## API 参考

您可以从软件包中导入全部函数 :

```ts
import {
  getAllRegions,
  getRegionByCode,
  getAllProvinces,
  getProvinceByCode,
  getAllMunicipalities,
  getMunicipalityByCode,
  getAllBarangays,
  getBarangayByCode,
  getProvincesByRegion,
  getMunicipalitiesByProvince,
  getBarangaysByMunicipality,
  getAddressByBarangayCode,
  getAllPostalCodes,
  getLocationsByPostalCode,
  getPostalCodesByMunicipality,
} from "@aivangogh/ph-address";
```

### 函数签名

| 函数 | 返回类型 |
| --- | --- |
| `getAllRegions()` | `readonly PHRegion[]` |
| `getRegionByCode(code: string)` | `PHRegion | undefined` |
| `getAllProvinces()` | `readonly PHProvince[]` |
| `getProvinceByCode(code: string)` | `PHProvince | undefined` |
| `getProvincesByRegion(code: string)` | `readonly PHProvince[]` |
| `getAllMunicipalities()` | `readonly PHMunicipality[]` |
| `getMunicipalityByCode(code: string)` | `PHMunicipality | undefined` |
| `getMunicipalitiesByProvince(code: string)` | `readonly PHMunicipality[]` |
| `getAllBarangays()` | `readonly PHBarangay[]` |
| `getBarangayByCode(code: string)` | `PHBarangay | undefined` |
| `getBarangaysByMunicipality(code: string)` | `readonly PHBarangay[]` |
| `getAddressByBarangayCode(code: string)` | `PHAddress | undefined` |
| `getAllPostalCodes()` | `readonly PHPostalCode[]` |
| `getLocationsByPostalCode(postalCode: string)` | `readonly PHPostalCode[]` |
| `getPostalCodesByMunicipality(municipalityCode: string)` | `readonly PHPostalCode[]` |

在没有匹配的记录时,收藏搜索返回一个空的只读数组; 返回精确代码查询 `undefined`。 。 。 .

* * *

### 代码和地址查询

```ts
getBarangayByCode(code: string): PHBarangay | undefined;
getAddressByBarangayCode(code: string): PHAddress | undefined;
```

```ts
const barangay = getBarangayByCode("0730600001");
const address = getAddressByBarangayCode("0730600001");
```

返回精确检查 `undefined` 对于未知代码. `address.province` 实值 可选性——国家民事登记中心城市和PSGC特殊案例不在此列 省级以外的地区(伊萨贝拉市和巴勒马特别地理区) 区域)。 城市化程度高的城市决心去其母省.

* * *

### `getAllRegions()`

回返 `readonly PHRegion[]`,按区域顺序排序.

**示例**

```ts
import { getAllRegions } from "@aivangogh/ph-address";

const regions = getAllRegions();
console.log(regions);
/*
[
  { name: 'AUTONOMOUS REGION IN MUSLIM MINDANAO (ARMM)', psgcCode: '1900000000', designation: 'ARMM' },
  { name: 'BICOL REGION', psgcCode: '0500000000', designation: 'REGION V' },
  ...
]
*/
```

* * *

### `getAllProvinces()`

回返 `readonly PHProvince[]`,按字母顺序排序.

**示例**

```ts
import { getAllProvinces } from "@aivangogh/ph-address";

const provinces = getAllProvinces();
console.log(provinces);
/*
[
  { name: 'Abra', psgcCode: '1400100000', regionCode: '1400000000' },
  { name: 'Agusan Del Norte', psgcCode: '1600200000', regionCode: '1600000000' },
  ...
]
*/
```

* * *

### `getProvincesByRegion(regionCode)`

回返 `readonly PHProvince[]`,按字母顺序排序。 返回空数组 当地区没有相应的省份时.

-   `regionCode` (字符串):该地区的PSGC代码.

**示例**

```ts
import { getProvincesByRegion } from "@aivangogh/ph-address";

// Get all provinces in Region VII (Central Visayas)
const provinces = getProvincesByRegion("0700000000");
console.log(provinces);
/*
[
  { name: 'Bohol', psgcCode: '0701200000', regionCode: '0700000000' },
  { name: 'Cebu', psgcCode: '0702200000', regionCode: '0700000000' }
]
*/
```

* * *

### `getMunicipalitiesByProvince(provinceCode)`

回返 `readonly PHMunicipality[]`,按字母顺序排序。 返回为空 当省没有匹配的市镇或城市时.

-   `provinceCode` (字符串):本省PSGC代码.

**示例**

```ts
import { getMunicipalitiesByProvince } from "@aivangogh/ph-address";

// Get all municipalities in Cebu
const municipalities = getMunicipalitiesByProvince("0702200000");
console.log(municipalities);
/*
[
  { name: 'Alcantara', psgcCode: '0702201000', provinceCode: '0702200000' },
  { name: 'Alcoy', psgcCode: '0702202000', provinceCode: '0702200000' },
  ...
]
*/
```

* * *

### `getBarangaysByMunicipality(municipalityCode)`

回返 `readonly PHBarangay[]`,按字母顺序排序。 返回空数组 市镇或城市没有相应的村镇.

-   `municipalityCode` (字符串):市镇或城市的PSGC代码.

**说明**:在本库和PSGC数据中,"市"一词既指市也指市.

**示例**

```ts
import { getBarangaysByMunicipality } from "@aivangogh/ph-address";

// Get all barangays in Cebu City
const barangays = getBarangaysByMunicipality("0730600000");
console.log(barangays);
/*
[
  { name: 'Adlaon', psgcCode: '0730600001', municipalCityCode: '0730600000' },
  { name: 'Agsungot', psgcCode: '0730600002', municipalCityCode: '0730600000' },
  ...
]
*/
```

## 邮政编码

邮政编码与PSGC等级分开,因为一个市镇可以 有多个交货地点和代码.

```ts
getAllPostalCodes(): readonly PHPostalCode[];
getLocationsByPostalCode(postalCode: string): readonly PHPostalCode[];
getPostalCodesByMunicipality(
  municipalityCode: string,
): readonly PHPostalCode[];
```

在没有匹配的记录时, 邮政编码查询返回一个空的只读数组 .

```ts
import {
  getAllPostalCodes,
  getLocationsByPostalCode,
  getPostalCodesByMunicipality,
} from "@aivangogh/ph-address";

getLocationsByPostalCode("6000");
getPostalCodesByMunicipality("0730600000"); // Cebu City
getAllPostalCodes();
```

目前每个PSGC市镇/城市至少有一幅邮政编码映射. 通过审查解决历史名称和拼写差异 别名。 新的BARMM 特别地理区域市镇使用 PHLPost 从以前载有这些法规的市镇继承的法规 镇长 仍无法安全识别的地物名称 通过邮政编码查询而无 `municipalityCode`。 。 。 .

## 类型

您可以导入所有必要的类型用于您的 TypeScript 项目 .

```ts
import type {
  PHRegion,
  PHProvince,
  PHMunicipality,
  PHBarangay,
  PHPostalCode,
  PHAddress,
} from "@aivangogh/ph-address";
```

```ts
type PHRegion = {
  name: string;
  psgcCode: string;
  designation: string;
};

type PHProvince = {
  name: string;
  psgcCode: string;
  regionCode: string;
};

type PHMunicipality = {
  name: string;
  psgcCode: string;
  provinceCode: string;
};

type PHBarangay = {
  name: string;
  psgcCode: string;
  municipalCityCode: string;
};

type PHPostalCode = {
  postalCode: string;
  placeName: string;
  provinceName: string;
  regionName: string;
  municipalityCode?: string;
};

type PHAddress = {
  region: PHRegion;
  province?: PHProvince;
  municipality: PHMunicipality;
  barangay: PHBarangay;
};
```

`PHAddress.province` 可选: NCR 城市和 PSGC 都不存在 在省一级以外的特殊案件(Isabela市和 (原始内容存档于2018-10-25). BARM Special G地理区域. 高度城市化的城市,如宿迁市, 达沃市和碧瑶市在PSGC来源中是独立的省,但是这个 由母亲所在省份照顾他们,以便他们能够从 地区 省 市级. `PHPostalCode.municipalityCode` 可选 当交付地点无法安全地绘制到目前的PSGC市时 或城市,或城市.

## 数据来源

地理数据来源于季度 [菲律宾标准地理守则出版物](https://psa.gov.ph/classification/psgc/node/1684083815) 会 议 日 程 和 议 程 **菲律宾统计局**。 。 。 .

邮政编码数据来自 [地理名称](https://www.geonames.org/),根据 [CC BY 4.0 (英语)](https://creativecommons.org/licenses/by/4.0/)源头快照 及其读取器存储于 `assets/ph-postal-code`经审查的绘图使用了 [PHLPost ZIP 代码定位器](https://phlpost.gov.ph/zip-code-locator/) 编辑 PSA PSGC 对应数据与此软件包相捆.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40aivangogh/ph-address/LICENCE)

## 常见问题

### @aivangogh/ph-address 是什么？

菲律宾基于PSGC的地理和邮政编码数据

### 如何安装 @aivangogh/ph-address？

在项目目录运行 npm install @aivangogh/ph-address，或使用 pnpm add / yarn add / bun add。

### @aivangogh/ph-address 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aivangogh/ph-address 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @aivangogh/ph-address 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aivangogh/ph-address 可以商用吗？

@aivangogh/ph-address 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aivangogh/ph-address 的下载量有多少？

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

### @aivangogh/ph-address 还在维护吗？

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