API Documentation – v2

Version 2 introduces structured resource responses using Laravel API Resources, consistent field naming, and count fields on detail endpoints. Base URL: https://psgc.cloud/api/v2

Need v1? View v1 docs.

Endpoints Overview

Regions

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

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

List Fields: code, name

Detail Fields: code, name, provinces_count, cities_municipalities_count, barangays_count

Nested:

  • GET https://psgc.cloud/api/v2/regions/{code_name}/provinces – Provinces
  • GET https://psgc.cloud/api/v2/regions/{code_name}/cities-municipalities – Cities & Municipalities
  • GET https://psgc.cloud/api/v2/regions/{code_name}/cities – Cities
  • GET https://psgc.cloud/api/v2/regions/{code_name}/municipalities – Municipalities
  • GET https://psgc.cloud/api/v2/regions/{code_name}/sub-municipalities – Sub-Municipalities
  • GET https://psgc.cloud/api/v2/regions/{code_name}/barangays – Barangays
# 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 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

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

List Fields: code, name, region

Detail Fields: code, name, region, cities_municipalities_count, barangays_count

Nested:

  • GET https://psgc.cloud/api/v2/provinces/{code_name}/cities-municipalities – Cities & Municipalities
  • GET https://psgc.cloud/api/v2/provinces/{code_name}/cities – Cities
  • GET https://psgc.cloud/api/v2/provinces/{code_name}/municipalities – Municipalities
  • GET https://psgc.cloud/api/v2/provinces/{code_name}/sub-municipalities – Sub-Municipalities
  • GET https://psgc.cloud/api/v2/provinces/{code_name}/barangays – Barangays
# 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 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

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

List Fields: code, name, type, region, province

Detail Fields: code, name, type, region, province, barangays_count

Nested:

  • GET https://psgc.cloud/api/v2/cities-municipalities/{code_name}/barangays – Barangays
# 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 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

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

List Fields: code, name, status, region, province, city_municipality

Detail Fields: code, name, status, region, province, city_municipality

# 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 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 hierarchy with ancestry validation. Each segment must belong to the previous ones or a 404 is returned.

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} 

# 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 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);

# An ancestry mismatch -> 404

Use direct endpoints when you don't need hierarchy validation.

Counts

Fields ending in _count appear only on detail requests where the resource was queried with counts. Collection endpoints omit them to stay lean.

Errors

404 for unknown code_name. 429 when rate limited. 500 for unexpected errors.

{
  "message": "Region not found"
}

Changelog

  • V2.1.0 – Chainable nested hierarchy endpoints (regions/{region}/provinces/{province}/cities-municipalities/{city_municipality}/barangays/{barangay} & intermediate levels).
  • v2.0.0 – Introduced resource-based responses & count fields.

See also: v1 changelog.