ph_address_finder

Offline Flutter package for retrieving Philippine address details using both PSA/PSGC-style lookups and PCIC RegionNo cascades.

This package contains:

• provinces.json
• municipalities.json
• barangays.json

All based on official PSA PSGC data.

---

🚀 Features

• Convert PSA province, municipality, and barangay codes into a full address
• Cascade PSA lookups from region subcode to province, municipality, and barangay
• Cascade PCIC lookups from RegionNo with optional region options such as 3A
• Ship complete province, municipality, and barangay datasets with the package
• Work fully offline with bundled JSON assets
• Support Android, iOS, Linux, macOS, and Windows

---

📦 Installation

Add to your pubspec.yaml:

dependencies:
  ph_address_finder: ^4.0.0

---

🔎 PSA Usage

Use AddressService for PSA/PSGC-style lookups:

import 'package:flutter/widgets.dart';
import 'package:ph_address_finder/ph_address_finder.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final provinces = await AddressService.getProvincesByRegion(
    regionSubCode: 'III',
  );

  final municipalities = await AddressService.getMunicipalitiesByProvince(
    provinceCode: '23',
  );

  final barangays = await AddressService.getBarangaysByMunicipality(
    provinceCode: '23',
    municipalityCode: '1',
  );

  final address = await AddressService.getAddress(
    provinceCode: '23',
    municipalityCode: '1',
    barangayCode: '1',
  );
}

AddressService now follows the stored PSA regionSubCode values directly. For Aurora and Nueva Ecija, use III instead of 3A.

---

🌾 PCIC Usage

Use PcicAddressService for PCIC RegionNo flows, including the special 3A region option:

final regionOptions = await PcicAddressService.getRegionOptions(
  regionNo: '1',
);

final provinces = await PcicAddressService.getProvinces(
  regionNo: '1',
  regionOption: '3A',
);

final address = await PcicAddressService.getAddress(
  regionNo: '1',
  provinceCode: '23',
  municipalityCode: '1',
  barangayCode: '1',
);

---

📝 Notes

• AddressService is for PSA/PSGC-style region-subcode lookups.
• PcicAddressService is for PCIC RegionNo lookups and still exposes 3A where the PCIC dataset requires it.
• The package loads its bundled JSON files at runtime and does not require network access.