Cities & Municipalities

Full contract

See Scalar (tag Municities) for the live OpenAPI contract. This page is a high-level guide only.

Philippine cities and municipalities (municities).

Endpoints

List Cities and Municipalities

GET /v1/municities

Filtering by province is always required.

Returns a paginated JSON envelope by default, or an unpaginated GeoJSON FeatureCollection for that province when format=geojson.

Province membership (scope)

By default the list is geographic so address forms and cascade UIs match how people think about place:

scope	Default	What is included
geographic	Yes	Component cities & municipalities and HUC/ICC cities hosted in that province (e.g. Cebu City, Lapu-Lapu, Mandaue under province=Cebu)
admin	No	Only LGUs whose admin PSGC parent is the province — excludes highly urbanized cities that are region peers

# Default — geographic (includes hosted HUCs)
curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities?province=Cebu"

# Explicit geographic
curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities?province=Cebu&scope=geographic"

# Strict admin hierarchy (no Cebu City / Lapu-Lapu / Mandaue)
curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities?province=Cebu&scope=admin"

Useful response fields:

Field	Description
p_code	Admin parent province code (null for region-level HUC/ICC)
host_province_code	Geographic host province (for HUCs: e.g. Cebu)
city_class	HUC, ICC, or omitted/null for component cities

Query Parameters

Parameter	Type	Required	Description
province	string	Yes	Exact (case-insensitive) province name. Required for geojson.
scope	geographic | admin	No	Membership model. Default: geographic.
name	string	No	Starts-with search for city/municipality name.
page	integer	No	Page number (default: 1). JSON only.
limit	integer	No	Items per page (default: 10, max: 100). JSON only.
format	json | geojson	No	Response shape. Default json.
output	json | geojson	No	Deprecated alias of format.
geometry	simple | medium | detailed	No	For json: omit = no geometry. For geojson: defaults to simple.

Example — JSON list

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities?province=Bohol&name=Al&limit=2"

Example Response (JSON)

{
  "data": [
    {
      "id": 1595,
      "name": "Alburquerque",
      "type": "Municipal",
      "code": "0701201000",
      "p_code": "0701200000",
      "host_province_code": "0701200000",
      "city_class": null,
      "province_name": "Bohol",
      "scope": "geographic"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 2,
    "totalPages": 1,
    "links": {
      "self": "https://api.gis.ph/v1/municities?province=Bohol&name=Al&limit=2",
      "next": null,
      "prev": null
    }
  },
  "error": null
}

Example — GeoJSON map layer (one province)

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities?province=Bohol&format=geojson"

• Body: FeatureCollection of all matching municities for the active scope
• Header: Content-Type: application/geo+json
• Not paginated
• Missing province → 400

Search Cities and Municipalities

GET /v1/municities/search

Cross-province text search for autocomplete. JSON only (no format=geojson in v1).

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query (minimum 2 characters).
limit	integer	No	Max results to return (default: 20).

Example Request

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities/search?q=Tagbilaran"

Example Response

{
  "data": [
    {
      "id": 729,
      "name": "City of Tagbilaran",
      "type": "City",
      "code": "0701244000",
      "host_province_code": "0701200000",
      "province_name": "Bohol"
    }
  ],
  "error": null
}

Get Single Municipality

GET /v1/municities/{id}

Returns detailed information about a single city or municipality. {id} is the PSGC code (not the internal serial row id). Prefer the 10-digit form (e.g. 0730600000 for City of Cebu).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	City/municipality PSGC code (digits only), e.g. 0701201000 or 0730600000.

Query Parameters

Parameter	Type	Required	Description
format	json | geojson	No	Default json. geojson → bare Feature.
geometry	simple | medium | detailed | true	No	Boundary level, or legacy true for nested barangay GeoJSON on JSON responses. For format=geojson, defaults to simple.

Example Request (GeoJSON Feature)

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities/0701201000?format=geojson"

Example Response (GeoJSON Feature)

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [ ... ]
  },
  "properties": {
    "id": 1595,
    "name": "Alburquerque",
    "type": "Municipal",
    "code": "0701201000",
    "host_province_code": "0701200000",
    "province_name": "Bohol"
  }
}

Example Request (Legacy nested JSON)

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/municities/0701201000?geometry=true"

Batch search by codes

POST /v1/municities/search

Accepts a list of PSGC municity codes and returns matching cities/municipalities. Supports both JSON and GeoJSON output formats.

Request Body

Field	Type	Required	Description
codes	string[]	Yes	List of PSGC city/municipality codes (1–100 items).
geometry	string	No	Geometry level to include: simple (default), medium, or detailed.
format	string	No	Output format: json or geojson.
output	string	No	Deprecated alias of format.

Example Request

curl -X POST \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"codes":["0730600000","0702219000"],"geometry":"simple","format":"geojson"}' \
     "https://api.gis.ph/v1/municities/search"

Example Response (GeoJSON)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "MultiPolygon", "coordinates": [ ... ] },
      "properties": {
        "id": 1595,
        "name": "Alburquerque",
        "code": "0701201000",
        "province_name": "Bohol"
      }
    }
  ]
}

Example Response (JSON, Legacy fallback when format omitted)

[
  {
    "id": 1595,
    "name": "Alburquerque",
    "code": "0701201000",
    "province_name": "Bohol"
  }
]