PH-地址

包含官员的轻量级菲律宾地址数据包 菲律宾标准地理代码 截至2026年6月30日的地理等级和单独的邮政编码绘图.

探索菲律宾地址数据

特征

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

节点.js和浏览器支持

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

地址数据模型

PSGC 地理代码

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

邮政编码

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

性能特征

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

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

格式 基准

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

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

版本

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

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

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

安装

# Using npm
npm install @aivangogh/ph-address

# Using yarn
yarn add @aivangogh/ph-address

# Using pnpm
pnpm add @aivangogh/ph-address

API 参考

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

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

函数签名

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

代码和地址查询

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

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

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

getAllRegions()

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

示例

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[],按字母顺序排序.

示例

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代码.

示例

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代码.

示例

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数据中,"市"一词既指市也指市.

示例

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等级分开,因为一个市镇可以 有多个交货地点和代码.

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

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

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

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

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

类型

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

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

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市时 或城市,或城市.

数据来源

地理数据来源于季度 菲律宾标准地理守则出版物 会 议 日 程 和 议 程 菲律宾统计局。 。 。 .

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

许可证

麻省理工学院