PH Regions API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/weaponsforge/ph-regions License: MIT

💡About

A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes.

⚠️ Important

This API is intended for testing and simulating RESTful API requests from client applications. Note: The location data may be outdated and does not reflect the most current official records.

🧩 Alternate Docs

Interactive API documentation (Swagger UI): https://ph-regions.vercel.app/docs

Islands

REST APIs for retrieving Philippine islands location data

List islands

List of main island group names in the Philippines

query Parameters

name	string <= 40 characters Example: name=Luzon Island name
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Main Island groups geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452af0a9414a4312e589",
"name": "Luzon"
}
]
}

List full islands

Full list of main island groups in the Philippines including regions

query Parameters

name	string <= 40 characters Example: name=Luzon Island name
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Main Island groups geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452af0a9414a4312e589",
"name": "Luzon",
"regions": [{"_id": "68bc452bf0a9414a4312e591",
"islandId": "68bc452af0a9414a4312e589",
"name": "Region IV-A",
"abbrev": "CALABARZON",
"regionalName": "CALABARZON",
"regionalCode": "4A"
}
]
}
]
}

Get island by ID

Get an island data by ID

path Parameters

id

required

string

Example: 68bc452af0a9414a4312e589

Island document ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Main Island groups geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452af0a9414a4312e589",
"name": "Luzon"
}
}

Regions

REST APIs for retrieving Philippine regional location data

List regions

List of regions in the Philippines (excluding provinces and municipalities)

query Parameters

islandId	string Example: islandId=68bc452af0a9414a4312e589 Island document ID
name	string <= 40 characters Example: name=Region IV-A Region name
abbrev	string or null <= 20 characters Example: abbrev=CALABARZON Abbreviation name or code
regionalName	string Example: regionalName=CALABARZON Long-form regional name
regionalCode	string or null <= 5 characters Example: regionalCode=4A Region code
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Regional geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452bf0a9414a4312e591",
"islandId": "68bc452af0a9414a4312e589",
"name": "Region IV-A",
"abbrev": "CALABARZON",
"regionalName": "CALABARZON",
"regionalCode": "4A"
}
]
}

List full regions

Full list of regions data in the Philippines including provinces and municipalities

query Parameters

islandId	string Example: islandId=68bc452af0a9414a4312e589 Island document ID
name	string <= 40 characters Example: name=Region IV-A Region name
abbrev	string or null <= 20 characters Example: abbrev=CALABARZON Abbreviation name or code
regionalName	string Example: regionalName=CALABARZON Long-form regional name
regionalCode	string or null <= 5 characters Example: regionalCode=4A Region code
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Regional geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452bf0a9414a4312e591",
"islandId": "68bc452af0a9414a4312e589",
"name": "Region IV-A",
"abbrev": "CALABARZON",
"regionalName": "CALABARZON",
"regionalCode": "4A",
"provinces": [{"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas",
"municipalities": [{"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
]
}
]
}
]
}

Get region by ID

Retrieves region data by ID excluding provinces and municipalities

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e591

Region ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Regional geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e591",
"islandId": "68bc452af0a9414a4312e589",
"name": "Region IV-A",
"abbrev": "CALABARZON",
"regionalName": "CALABARZON",
"regionalCode": "4A"
}
}

Get region by ID with provinces

Retrieves region data by ID including all provinces and municipalities

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e591

Region ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Regional geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e591",
"islandId": "68bc452af0a9414a4312e589",
"name": "Region IV-A",
"abbrev": "CALABARZON",
"regionalName": "CALABARZON",
"regionalCode": "4A",
"provinces": [{"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas",
"municipalities": [{"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
]
}
]
}
}

Provinces

REST APIs for retrieving Philippine provincial location data

List provinces

List of provinces in the Philippines (excluding municipalities)

query Parameters

regionId	string Example: regionId=68bc452bf0a9414a4312e591 Region ID
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Provincial geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas"
}
]
}

List full provinces

Full list of provinces in the Philippines including municipalities

query Parameters

regionId	string Example: regionId=68bc452bf0a9414a4312e591 Region ID
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Provincial geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas",
"municipalities": [{"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
]
}
]
}

Get province by ID

Get province data by ID excluding municipalities

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e5b1

Province ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Provincial geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas"
}
}

Get province by ID with municipalities

Get province data by ID including its municipalities

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e5b1

Province ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Provincial geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e5b1",
"regionId": "68bc452bf0a9414a4312e591",
"name": "Batangas",
"municipalities": [{"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
]
}
}

Municipalities

REST APIs for retrieving Philippine municipal location data

List municipalities

List of municipalities in the Philippines by region or province

query Parameters

regionId	string Example: regionId=68bc452bf0a9414a4312e591 Region ID
provinceId	string Example: provinceId=68bc452bf0a9414a4312e5b1 Province ID
includeMeta	boolean or null Default: false Example: includeMeta=false Flag to include the Mongo meta fields (eg., `createdAt`, `updatedAt`) in the response

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Municipal geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": [{"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
]
}

Get municipality by ID

Retrieves municipality data by ID

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e753

Municipality ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"total": 1,
"metadata": {"description": "Municipal geographic location data of the Philippines",
"source": "PAGASA Seasonal Rainfall Analysis Table (regions and provinces) and 10-Day Weather Forecast Excel file (provinces and municipalities)",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e753",
"regionId": "68bc452bf0a9414a4312e591",
"provinceId": "68bc452bf0a9414a4312e5b1",
"name": "Agoncillo",
"numDocs": 0
}
}

Stats

REST APIs for retrieving random test data for each Municipality

Get municipality stats by ID

Retrieves municipality stats data by ID

path Parameters

id

required

string

Example: 68bc452bf0a9414a4312e753

Municipality ID

query Parameters

includeMeta

boolean or null

Default: false

Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"metadata": {"description": "Random barangay geographic location data of the Philippines",
"source": "n/a",
"dateCreated": "2022/08/03"
},
"data": {"_id": "68bc452bf0a9414a4312e753",
"municipalityId": "68bc452bf0a9414a4312e753",
"numBrgy": 97
}
}