PSGC Terminology FHIR Implementation Guide
0.1.0 - ci-build Philippines flag

PSGC Terminology FHIR Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Logical Model

The PSGC source data is published by PSA as quarterly XLSX files. This page defines the logical model — the structure of the source data before it is mapped into FHIR terminology resources.

PSA Publication Data Structure

Releaseversion : stringeffectiveDate : datesource : uriformat : FormatEntrycode : string {10 digits, positional}name : string {gazetted name}correspondenceCode? : string {legacy 9-digit}geographicLevel : GeographicLeveloldNames? : string {former name}cityClass? : CityClassincomeClassification? : IncomeClassurbanRural? : UrbanRuralpopulation? : integer {census count}status? : EntryStatusGeographicLevelRegProvCityMunSubMunBgyCityClassHUC {Highly Urbanized}ICC {Independent Component}CC {Component City}IncomeClass1st .. 6thUrbanRuralU {Urban}R {Rural}EntryStatusPob. {Poblacion}CapitalFormatmodern {10-digit, Q1 2022+}legacy {9-digit, pre-2022}Positional hierarchy:[1-2] Region[3-5] Province[6-7] City/Mun[8-10] BarangayTrailing zeros = higher levelOnly for level=CityPer Local Government CodeOnly for level=BgyPer Census of Population~43000cities onlyProv/City/MunBgy onlyparent (derived)


Two Publication Formats

PSA has used two distinct XLSX layouts:

Era Header Column Code Length Key Difference
Pre-2022 "Code" 9 digits No correspondence code column
Q1 2022+ "10-digit PSGC" 10 digits Includes 9-digit correspondence code

Legacy normalisation rule: a 9-digit code is converted to 10 digits by appending a trailing zero (right-pad), per the PSA migration scheme.

Hierarchy Derivation

The parent of any PSGC code is derived algorithmically from the positional structure:

Input: 10-digit codeyesdigits 8-10 != "000"?Level = BarangayParent = digits[1-7] + "000"yesdigits 6-7 != "00"?Level = City/MunicipalityParent = digits[1-5] + "00000"yesdigits 3-5 != "000"?Level = ProvinceParent = digits[1-2] + "00000000"Level = RegionParent = (none)


FHIRPath Formal Specification

The parent derivation is formally specified in FHIRPath:

// Barangay parent
code.substring(7) != '000'
  implies parent = code.substring(0,7) + '000'

// City/Municipality parent
(code.substring(5,2) != '00' and code.substring(7) = '000')
  implies parent = code.substring(0,5) + '00000'

// Province parent
(code.substring(2,3) != '000' and code.substring(5) = '00000')
  implies parent = code.substring(0,2) + '00000000'

// Region has no parent
code.substring(2) = '00000000' implies parent.empty()

Mapping to FHIR

Logical Model Field FHIR Representation
code CodeSystem.concept.code / Coding.code
name CodeSystem.concept.display / Coding.display
geographicLevel CodeSystem.concept.property[level]
parent (derived) CodeSystem.concept.property[parent]
incomeClassification CodeSystem.concept.property[incomeClassification]
urbanRural CodeSystem.concept.property[urbanRural]
oldNames CodeSystem.concept.designation (use=old)
population CodeSystem.concept.property[population]
correspondenceCode Not exposed (internal normalisation reference)