ph_address_finder 5.0.1

Offline Flutter package for Philippine PSA/PSGC and PCIC address lookups with bundled province, municipality, and barangay data.

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/<provinceCode>.json.gz

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
• Surface raw PSA region: 3A records as regionSubCode: 'III-A'
• Return distinct barangay names for dropdown-friendly PSA barangay lists
• Discover PCIC regionNo values and region options such as 3A
• Cascade PCIC lookups from RegionNo with optional region options such as 3A
• Preserve matching PCIC barangays even when dataset rows are split across duplicate or drifting municipality records
• 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: ^5.0.1

---

🔎 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-A',
  );

  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 exposes an effective PSA region subcode. When a record's raw region column is 3A, query it as III-A and expect returned province, municipality, barangay, and address data to use regionSubCode: 'III-A'.

getBarangaysByMunicipality() also returns distinct barangayName entries so duplicate rows in the source data do not create duplicate dropdown options.

PSA Migration

If you're upgrading from 4.x:

• Query Aurora and Nueva Ecija through regionSubCode: 'III-A' instead of III.
• Expect AddressService results for affected records to return regionSubCode: 'III-A'.
• Expect getBarangaysByMunicipality() to return distinct barangay names for dropdown use.

---

🌾 PCIC Usage

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

final regionNumbers = await PcicAddressService.getRegionNumbers();

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

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

final aurora = provinces.firstWhere(
  (province) => province['provinceName'] == 'Aurora',
);

final municipalities = await PcicAddressService.getMunicipalities(
  regionNo: '1',
  provinceCode: aurora['provinceCode'].toString(),
  provinceId: aurora['provinceId'].toString(),
);

final baler = municipalities.firstWhere(
  (municipality) => municipality['municipalityName'] == 'Baler',
);

final barangays = await PcicAddressService.getBarangays(
  regionNo: '1',
  provinceCode: aurora['provinceCode'].toString(),
  municipalityCode: baler['municipalityCode'].toString(),
  provinceId: aurora['provinceId'].toString(),
  municipalityId: baler['municipalityId'].toString(),
);

final address = await PcicAddressService.getAddress(
  regionNo: '1',
  provinceCode: aurora['provinceCode'].toString(),
  municipalityCode: baler['municipalityCode'].toString(),
  barangayCode: barangays.first['barangayCode'].toString(),
);

getRegionNumbers() is a good entry point for building a PCIC region picker because it returns each regionNo plus any special options, including 3A.

When cascading PCIC data, pass the selected provinceId into getMunicipalities() and the selected municipalityId into getBarangays(). This keeps duplicate province and municipality codes aligned with the item the user actually selected.

getBarangays() also supplements exact municipality matches with non-conflicting fallback rows. This helps preserve valid addresses when the bundled PCIC dataset splits a municipality across slightly different records.

---

📝 Notes

• AddressService is for PSA/PSGC-style region-subcode lookups and normalizes raw 3A region entries into regionSubCode: 'III-A'.
• AddressService.getBarangaysByMunicipality() deduplicates by barangayName to keep barangay dropdowns clean.
• PcicAddressService is for PCIC RegionNo lookups, exposes 3A where the PCIC dataset requires it, and supports duplicate-safe province and municipality cascades through provinceId and municipalityId.
• The package loads bundled JSON assets at runtime and does not require network access.
• Barangay data is packaged as province-based json.gz shards and is loaded lazily to keep package uploads and runtime memory usage manageable.