API Reference v2

REST API Documentation – v2

Version 2 introduces structured resource responses using Laravel API Resources, highly consistent field names, and pre-calculated counts on details endpoints.

Base URL: https://psgc.cloud/api/v2

Need v1? View v1 docs.

Endpoint Overview

Regions

LIST GET https://psgc.cloud/api/v2/regions

SHOW GET https://psgc.cloud/api/v2/regions/{code_name}

Payload Fields

List Payload: code, name
Detail Payload: code, name, provinces_count, cities_municipalities_count, barangays_count

Nested Sub-Resources

Provinces: GET https://psgc.cloud/api/v2/regions/{code_name}/provinces
Cities & Municipalities: GET https://psgc.cloud/api/v2/regions/{code_name}/cities-municipalities
Cities: GET https://psgc.cloud/api/v2/regions/{code_name}/cities
Municipalities: GET https://psgc.cloud/api/v2/regions/{code_name}/municipalities
Sub-Municipalities: GET https://psgc.cloud/api/v2/regions/{code_name}/sub-municipalities
Barangays: GET https://psgc.cloud/api/v2/regions/{code_name}/barangays

Example cURL & Fetch Requests

# curl list
curl -s https://psgc.cloud/api/v2/regions | jq '.[0]'

# curl detail (replace CODE_OR_NAME)
curl -s https://psgc.cloud/api/v2/regions/CODE_OR_NAME | jq

# fetch JavaScript example
const res = await fetch('https://psgc.cloud/api/v2/regions');
const items = await res.json();
console.log(items[0]);

Provinces

LIST GET https://psgc.cloud/api/v2/provinces

SHOW GET https://psgc.cloud/api/v2/provinces/{code_name}

Payload Fields

List Payload: code, name, region
Detail Payload: code, name, region, cities_municipalities_count, barangays_count

Nested Sub-Resources

Cities & Municipalities: GET https://psgc.cloud/api/v2/provinces/{code_name}/cities-municipalities
Cities: GET https://psgc.cloud/api/v2/provinces/{code_name}/cities
Municipalities: GET https://psgc.cloud/api/v2/provinces/{code_name}/municipalities
Sub-Municipalities: GET https://psgc.cloud/api/v2/provinces/{code_name}/sub-municipalities
Barangays: GET https://psgc.cloud/api/v2/provinces/{code_name}/barangays

Example cURL & Fetch Requests

# curl list
curl -s https://psgc.cloud/api/v2/provinces | jq '.[0]'

# curl detail (replace CODE_OR_NAME)
curl -s https://psgc.cloud/api/v2/provinces/CODE_OR_NAME | jq

# fetch JavaScript example
const res = await fetch('https://psgc.cloud/api/v2/provinces');
const items = await res.json();
console.log(items[0]);

Cities & Municipalities

LIST GET https://psgc.cloud/api/v2/cities-municipalities

SHOW GET https://psgc.cloud/api/v2/cities-municipalities/{code_name}

Payload Fields

List Payload: code, name, type, region, province
Detail Payload: code, name, type, region, province, barangays_count

Nested Sub-Resources

Barangays: GET https://psgc.cloud/api/v2/cities-municipalities/{code_name}/barangays

Example cURL & Fetch Requests

# curl list
curl -s https://psgc.cloud/api/v2/cities-municipalities | jq '.[0]'

# curl detail (replace CODE_OR_NAME)
curl -s https://psgc.cloud/api/v2/cities-municipalities/CODE_OR_NAME | jq

# fetch JavaScript example
const res = await fetch('https://psgc.cloud/api/v2/cities-municipalities');
const items = await res.json();
console.log(items[0]);

Barangays

LIST GET https://psgc.cloud/api/v2/barangays

SHOW GET https://psgc.cloud/api/v2/barangays/{code_name}

Payload Fields

List Payload: code, name, status, region, province, city_municipality
Detail Payload: code, name, status, region, province, city_municipality

Example cURL & Fetch Requests

# curl list
curl -s https://psgc.cloud/api/v2/barangays | jq '.[0]'

# curl detail (replace CODE_OR_NAME)
curl -s https://psgc.cloud/api/v2/barangays/CODE_OR_NAME | jq

# fetch JavaScript example
const res = await fetch('https://psgc.cloud/api/v2/barangays');
const items = await res.json();
console.log(items[0]);

Chainable Nested Paths

Traverse the full geographic hierarchy with automatic ancestry validation. Each segment along the route is strictly validated against its parents—an ancestry mismatch triggers an immediate 404 Not Found.

GET https://psgc.cloud/api/v2/regions/{region}/provinces/{province}

GET https://psgc.cloud/api/v2/regions/{region}/provinces/{province}/cities-municipalities

GET https://psgc.cloud/api/v2/regions/{region}/provinces/{province}/cities-municipalities/{city_municipality}

GET https://psgc.cloud/api/v2/regions/{region}/provinces/{province}/cities-municipalities/{city_municipality}/barangays

GET https://psgc.cloud/api/v2/regions/{region}/provinces/{province}/cities-municipalities/{city_municipality}/barangays/{barangay}

Ancestry cURL & JS Examples

# List cities/municipalities for a province inside a region
curl -s "https://psgc.cloud/api/v2/regions/Region V (Bicol Region)/provinces/Albay/cities-municipalities" | jq '.[0]'

# Fetch a barangay validating full ancestry
curl -s "https://psgc.cloud/api/v2/regions/Region V (Bicol Region)/provinces/Albay/cities-municipalities/City of Tabaco/barangays/Mariroc" | jq

# JS fetch example
const url = 'https://psgc.cloud/api/v2/regions/Region V (Bicol Region)/provinces/Albay/cities-municipalities/City of Tabaco/barangays';
const brgys = await (await fetch(url)).json();
console.log(brgys.length);

Note: Use direct resource paths when you do not need strict parent validation.

Pre-calculated Counts

Fields ending in _count appear exclusively on single detail resources to display totals of their children (e.g. `barangays_count`). Collection endpoints deliberately omit count calculations to remain incredibly lean and fast.

Error Responses

When a queried resource code or name is unknown, a clean JSON payload is returned with a 404 response:

{
  "message": "Region not found"
}

API v2 Changelog

v2.1.0

Introduced full chainable nested hierarchy endpoints with strict ancestry checks up to barangays.

v2.0.0

Introduced unified Laravel API Resource mapping layouts and child resource counters.