PSGC Terminology FHIR Implementation Guide
0.1.0 - ci-build
PSGC Terminology FHIR Implementation Guide
0.1.0 - ci-build
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
The Philippine Standard Geographic Code (PSGC) classifies every administrative area in the Philippines — from the 17 regions down to over 42,000 barangays. It is published quarterly by the Philippine Statistics Authority as Excel spreadsheets, with codes evolving as provinces split, regions are created or abolished, and municipalities are reclassified.
Each code is a 10-digit string whose positional structure encodes the geographic hierarchy:
This positional encoding is what makes hierarchy operations trivial — ancestor testing is prefix comparison, and parent derivation is digit zeroing. No graph database required.
A conformant server SHALL expose these ValueSets, resolved dynamically via standard $expand:
| ValueSet | URL | Filter | Expected count |
|---|---|---|---|
psgc-regions |
.../ValueSet/psgc-regions |
level = Reg | ~17 |
psgc-provinces |
.../ValueSet/psgc-provinces |
level = Prov | ~88 |
psgc-cities |
.../ValueSet/psgc-cities |
level = City | ~146 |
psgc-barangays |
.../ValueSet/psgc-barangays |
level = Bgy | ~42,000 |
psgc-all |
.../ValueSet/psgc-all |
(none) | ~43,000 |
These are compose-based ValueSets filtering the PSGC CodeSystem by the level property. They support:
$expand — returns all codes at that level$expand?filter=Makati — text search within that level$expand?count=10 — paginated resultsThey are bindable — profiles can reference ValueSet/psgc-regions as a binding on address fields.
GET /fhir/ValueSet/psgc-regions/$expand
GET /fhir/ValueSet/psgc-cities/$expand?filter=Makati
GET /fhir/ValueSet/psgc-barangays/$expand?filter=Bangkal&count=5
A conformant server SHALL support these standard FHIR operations on the PSGC CodeSystem:
| Operation | Purpose |
|---|---|
$validate-code |
Validate that a code exists in a specific version |
$lookup |
Return display name, properties (level, parent, income, urbanRural), and designations (old names) |
$subsumes |
Test part-of hierarchy relationship between codes |
$translate |
Map a code between quarterly releases via ConceptMap |
Full-text search across area names. Returns a ValueSet expansion. Differs from the implicit ValueSets in that it searches across all levels simultaneously.
GET /fhir/CodeSystem/$expand-psgc?filter=Makati&count=5
Query by parent code prefix and geographic level — the combination case that implicit ValueSets cannot express.
GET /fhir/CodeSystem/$geo-lookup?parent=01&level=Prov
→ All provinces in Region I
GET /fhir/CodeSystem/$geo-lookup?parent=13006&level=Bgy
→ All barangays in Makati
Resolve full ancestry path for a code in a single call.
GET /fhir/CodeSystem/$geo-hierarchy?code=0102801001
→ Region I > Ilocos Norte > Adams (Mun) > Adams (Bgy)
Reverse geocoding via point-in-polygon spatial query.
GET /fhir/Location/$resolve-psgc?lat=14.5547&lon=121.0244
→ Barangay code + full hierarchy