🇵🇭 Philippine Addresses & Locations

A lightweight npm package providing comprehensive Philippine geographic data including Regions, Provinces, Cities/Municipalities, and Barangays with full hierarchy, ZIP codes, and search functionality.

✨ Features

• ✅ Complete PSGC Database - All regions, provinces, cities, and barangays
• ✅ ZIP Code Support - Postal codes for cities and municipalities
• ✅ District Information - Congressional district codes
• ✅ Hierarchical Relationships - Region → Province → City → Barangay
• ✅ Search Functionality - Find locations by name
• ✅ TypeScript Support - Full type definitions included
• ✅ Zero Dependencies - Lightweight and fast
• ✅ Tree-shakeable - Only import what you need

📦 Installation

npm install ph-addresses-locations

yarn add ph-addresses-locations

pnpm add ph-addresses-locations

🚀 Quick Start

ES6 Modules (React, Vue, Angular, etc.)

import { 
  getRegions, 
  getProvinces, 
  getCities, 
  getBarangays 
} from 'ph-addresses-locations';

// Get all regions
const regions = getRegions();
console.log(regions);
// [{ code: '0100000000', name: 'Region I (Ilocos Region)' }, ...]

// Get provinces by region
const provinces = getProvinces('0400000000'); // CALABARZON
console.log(provinces);
// [{ code: '0401000000', name: 'Batangas', regionCode: '0400000000' }, ...]

// Get cities by province with ZIP codes
const cities = getCities('0402100000'); // Cavite
console.log(cities);
// [{ code: '0402105000', name: 'City of Bacoor', zipCode: '4102', ... }, ...]

// Get barangays by city
const barangays = getBarangays('0102805000'); // Batac City
console.log(barangays);
// [{ code: '0102805001', name: 'Aglipay', cityCode: '0102805000' }, ...]

CommonJS (Node.js)

const phLocations = require('ph-addresses-locations');

const regions = phLocations.getRegions();
const provinces = phLocations.getProvinces('0400000000');

Default Import

import phLocations from 'ph-addresses-locations';

const regions = phLocations.getRegions();
const address = phLocations.getFullAddress('0102805001');

📖 API Reference

Region Functions

getRegions()

Get all regions in the Philippines.

const regions = getRegions();
// Returns: Array<{ code: string, name: string }>

Example Response:

[
  { code: '0100000000', name: 'Region I (Ilocos Region)' },
  { code: '0200000000', name: 'Region II (Cagayan Valley)' },
  { code: '1300000000', name: 'NCR (National Capital Region)' },
  // ... 17 regions total
]

getRegion(regionCode)

Get a specific region by code.

const region = getRegion('1300000000');
// Returns: { code: '1300000000', name: 'NCR (National Capital Region)' }

Province Functions

getProvinces(regionCode?)

Get provinces. If regionCode is provided, returns provinces in that region only.

// Get provinces in CALABARZON
const provinces = getProvinces('0400000000');

// Get all provinces
const allProvinces = getProvinces();

Example Response:

[
  { 
    code: '0401000000', 
    name: 'Batangas', 
    regionCode: '0400000000' 
  },
  { 
    code: '0402100000', 
    name: 'Cavite', 
    regionCode: '0400000000' 
  },
  // ...
]

getProvince(provinceCode)

Get a specific province by code.

const province = getProvince('0402100000');
// Returns: { code: '0402100000', name: 'Cavite', regionCode: '0400000000' }

City/Municipality Functions

getCities(provinceCode?)

Get cities and municipalities. If provinceCode is provided, returns cities in that province only.

// Get cities in Ilocos Norte
const cities = getCities('0102800000');

// Get all cities
const allCities = getCities();

Example Response:

[
  {
    code: '0102805000',
    name: 'City of Batac',
    provinceCode: '0102800000',
    zipCode: '2906',
    districtCode: '2nd'
  },
  {
    code: '0102812000',
    name: 'City of Laoag',
    provinceCode: '0102800000',
    zipCode: '2900',
    districtCode: '1st'
  },
  // ...
]

getCity(cityCode)

Get a specific city/municipality by code.

const city = getCity('0102805000');
// Returns: { code: '0102805000', name: 'City of Batac', zipCode: '2906', ... }

Barangay Functions

getBarangays(cityCode?)

Get barangays. If cityCode is provided, returns barangays in that city only.

// Get barangays in Batac City
const barangays = getBarangays('0102805000');

// Get all barangays
const allBarangays = getBarangays();

Example Response:

[
  { 
    code: '0102805001', 
    name: 'Aglipay', 
    cityCode: '0102805000' 
  },
  { 
    code: '0102805002', 
    name: 'Baay', 
    cityCode: '0102805000' 
  },
  // ...
]

getBarangay(barangayCode)

Get a specific barangay by code.

const barangay = getBarangay('0102805001');
// Returns: { code: '0102805001', name: 'Aglipay', cityCode: '0102805000' }

Advanced Functions

getFullAddress(barangayCode)

Get complete address hierarchy from a barangay code.

const address = getFullAddress('0102805001');

Example Response:

{
  region: { 
    code: '0100000000', 
    name: 'Region I (Ilocos Region)' 
  },
  province: { 
    code: '0102800000', 
    name: 'Ilocos Norte' 
  },
  city: { 
    code: '0102805000', 
    name: 'City of Batac',
    zipCode: '2906',
    districtCode: '2nd'
  },
  barangay: { 
    code: '0102805001', 
    name: 'Aglipay' 
  }
}

getLocationHierarchy(code)

Get location hierarchy from any PSGC code (region, province, city, or barangay).

// From city code
const hierarchy = getLocationHierarchy('0102805000');
// Returns hierarchy up to city level

// From region code
const regionHierarchy = getLocationHierarchy('0100000000');
// Returns only region

searchLocations(query, type?)

Search locations by name. Type can be 'all', 'region', 'province', 'city', or 'barangay'.

// Search all location types
const results = searchLocations('batac');

// Search only cities
const cities = searchLocations('batac', 'city');

Example Response:

{
  regions: [],
  provinces: [],
  cities: [
    { 
      code: '0102805000', 
      name: 'City of Batac',
      provinceCode: '0102800000',
      zipCode: '2906'
    }
  ],
  barangays: []
}

getLocationStats()

Get statistics about available locations.

const stats = getLocationStats();
// Returns: { regions: 17, provinces: 82, cities: 1634, barangays: 42046 }

isValidPSGCCode(code, type?)

Validate PSGC code format.

isValidPSGCCode('0100000000', 'region'); // true
isValidPSGCCode('0102805000', 'city'); // true
isValidPSGCCode('12345', 'region'); // false

🎯 Usage Examples

1. Cascading Address Selector

import { 
  getRegions, 
  getProvinces, 
  getCities, 
  getBarangays 
} from 'ph-addresses-locations';

// Step 1: Load regions
const regions = getRegions();

// Step 2: User selects region
const selectedRegion = '0100000000'; // Region I
const provinces = getProvinces(selectedRegion);

// Step 3: User selects province
const selectedProvince = '0102800000'; // Ilocos Norte
const cities = getCities(selectedProvince);

// Step 4: User selects city
const selectedCity = '0102805000'; // Batac City
const barangays = getBarangays(selectedCity);

// Step 5: User selects barangay
const selectedBarangay = '0102805001'; // Aglipay
const fullAddress = getFullAddress(selectedBarangay);

console.log(fullAddress);
// Complete address with region, province, city, barangay, and ZIP code

2. React Component Example

import React, { useState, useEffect } from 'react';
import { 
  getRegions, 
  getProvinces, 
  getCities, 
  getBarangays,
  getFullAddress 
} from 'ph-addresses-locations';

function AddressSelector() {
  const [regions] = useState(getRegions());
  const [selectedRegion, setSelectedRegion] = useState('');
  const [provinces, setProvinces] = useState([]);
  const [selectedProvince, setSelectedProvince] = useState('');
  const [cities, setCities] = useState([]);
  const [selectedCity, setSelectedCity] = useState('');
  const [barangays, setBarangays] = useState([]);
  const [selectedBarangay, setSelectedBarangay] = useState('');
  const [fullAddress, setFullAddress] = useState(null);

  useEffect(() => {
    if (selectedRegion) {
      setProvinces(getProvinces(selectedRegion));
      setSelectedProvince('');
    }
  }, [selectedRegion]);

  useEffect(() => {
    if (selectedProvince) {
      setCities(getCities(selectedProvince));
      setSelectedCity('');
    }
  }, [selectedProvince]);

  useEffect(() => {
    if (selectedCity) {
      setBarangays(getBarangays(selectedCity));
      setSelectedBarangay('');
    }
  }, [selectedCity]);

  useEffect(() => {
    if (selectedBarangay) {
      setFullAddress(getFullAddress(selectedBarangay));
    }
  }, [selectedBarangay]);

  return (
    <div className="address-selector">
      <select onChange={(e) => setSelectedRegion(e.target.value)}>
        <option value="">Select Region</option>
        {regions.map(r => (
          <option key={r.code} value={r.code}>{r.name}</option>
        ))}
      </select>

      <select 
        onChange={(e) => setSelectedProvince(e.target.value)} 
        disabled={!selectedRegion}
      >
        <option value="">Select Province</option>
        {provinces.map(p => (
          <option key={p.code} value={p.code}>{p.name}</option>
        ))}
      </select>

      <select 
        onChange={(e) => setSelectedCity(e.target.value)} 
        disabled={!selectedProvince}
      >
        <option value="">Select City/Municipality</option>
        {cities.map(c => (
          <option key={c.code} value={c.code}>
            {c.name} {c.zipCode && `(${c.zipCode})`}
          </option>
        ))}
      </select>

      <select 
        onChange={(e) => setSelectedBarangay(e.target.value)} 
        disabled={!selectedCity}
      >
        <option value="">Select Barangay</option>
        {barangays.map(b => (
          <option key={b.code} value={b.code}>{b.name}</option>
        ))}
      </select>

      {fullAddress && (
        <div className="full-address">
          <h3>Complete Address:</h3>
          <p>
            {fullAddress.barangay.name}, {fullAddress.city.name}, 
            {fullAddress.province.name}, {fullAddress.region.name}
          </p>
          <p>ZIP Code: {fullAddress.city.zipCode}</p>
        </div>
      )}
    </div>
  );
}

export default AddressSelector;

3. Search Implementation

import { searchLocations } from 'ph-addresses-locations';

function handleSearch(searchTerm) {
  const results = searchLocations(searchTerm);
  
  console.log('Regions:', results.regions);
  console.log('Provinces:', results.provinces);
  console.log('Cities:', results.cities);
  console.log('Barangays:', results.barangays);
}

// Search for "batac"
handleSearch('batac');
// Returns cities and barangays matching "batac"

4. Display Full Address

import { getFullAddress } from 'ph-addresses-locations';

const barangayCode = '0102805001'; // Aglipay, Batac City
const address = getFullAddress(barangayCode);

const formatted = `
  ${address.barangay.name}, 
  ${address.city.name}, 
  ${address.province.name}, 
  ${address.region.name}
  ZIP: ${address.city.zipCode}
`;

console.log(formatted);
// Output: Aglipay, City of Batac, Ilocos Norte, Region I (Ilocos Region), ZIP: 2906

📊 Data Structure

PSGC Code Format

The Philippine Standard Geographic Code uses a 10-digit format:

0102805001
││││││││││
│││││││└└└─ Barangay (3 digits)
││││││└───── City/Municipality (3 digits)
││││└─────── Province (2 digits)
││└───────── Region (2 digits)
└─────────── Always starts with 0

Examples:

• Region: 0100000000 (Region I)
• Province: 0102800000 (Ilocos Norte)
• City: 0102805000 (City of Batac)
• Barangay: 0102805001 (Aglipay)

Data Objects

Region

{
  code: string;      // e.g., '0100000000'
  name: string;      // e.g., 'Region I (Ilocos Region)'
}

Province

{
  code: string;        // e.g., '0102800000'
  name: string;        // e.g., 'Ilocos Norte'
  regionCode: string;  // e.g., '0100000000'
}

City/Municipality

{
  code: string;          // e.g., '0102805000'
  name: string;          // e.g., 'City of Batac'
  provinceCode: string;  // e.g., '0102800000'
  zipCode: string;       // e.g., '2906'
  districtCode: string;  // e.g., '2nd' (congressional district)
}

Barangay

{
  code: string;      // e.g., '0102805001'
  name: string;      // e.g., 'Aglipay'
  cityCode: string;  // e.g., '0102805000'
}

🔧 TypeScript Support

This package includes full TypeScript definitions:

import { 
  Location, 
  Province, 
  City, 
  Barangay, 
  FullAddress,
  SearchResults,
  LocationStats,
  getRegions,
  getFullAddress
} from 'ph-addresses-locations';

const regions: Location[] = getRegions();
const address: FullAddress | null = getFullAddress('0102805001');

Available Types

interface Location {
  code: string;
  name: string;
}

interface Province extends Location {
  regionCode: string;
}

interface City extends Location {
  provinceCode: string;
  zipCode?: string;
  districtCode?: string;
}

interface Barangay extends Location {
  cityCode: string;
}

interface FullAddress {
  region: Location | null;
  province: Location | null;
  city: City | null;
  barangay: Location | null;
}

interface SearchResults {
  regions: Location[];
  provinces: Province[];
  cities: City[];
  barangays: Barangay[];
}

interface LocationStats {
  regions: number;
  provinces: number;
  cities: number;
  barangays: number;
}

📈 Database Coverage

| Type | Count | |------|-------| | Regions | 17 | | Provinces | 82+ | | Cities/Municipalities | 1,634+ | | Barangays | 42,000+ |

Data based on the latest Philippine Standard Geographic Code (PSGC) from the Philippine Statistics Authority (PSA).

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues - Found a bug or incorrect data? Open an issue
2. Submit PRs - Have a fix or improvement? Submit a pull request
3. Update Data - Help keep the PSGC data current
4. Improve Docs - Better examples or clearer explanations

Development Setup

# Clone the repository
git clone https://github.com/KuramitZui/ph-addresses-locations.git
cd ph-addresses-locations

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

📄 License

MIT © Vincent Esquivel

🙏 Acknowledgments

• Data source: Philippine Statistics Authority (PSA)
• Based on the Philippine Standard Geographic Code (PSGC)

📮 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

🔗 Links

• NPM Package
• GitHub Repository
• Documentation
• Changelog