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
Surface raw PSA region: 3A records as regionSubCode: 'III-A'
Return distinct barangay names for dropdown-friendly PSA barangay lists
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: ^5.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-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 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(),
);

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.

📝 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 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.