Barangays API

Philippine barangays (lowest admin unit in this hierarchy).

Endpoints

List Barangays

GET /v1/barangays

Province is always required for list.

Mode	Extra parent rules	Pagination
`format=json` (default)	`municipality` optional	Yes (`page` / `limit`)
`format=geojson`	`municipality` required (with `province`)	No — full FeatureCollection for that LGU

Province-wide barangay GeoJSON dumps are not supported (payload / cost safety).

Query Parameters

Parameter	Type	Required	Description
`province`	`string`	Yes	Exact (case-insensitive) province name.
`municipality`	`string`	Conditional	Starts-with municipality/city name. Required when `format=geojson`.
`name`	`string`	No	Starts-with barangay 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/barangays?province=Cebu&municipality=Poro&limit=5"

Example — GeoJSON for one LGU

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

Body: RFC 7946 FeatureCollection
Header: Content-Type: application/geo+json
Not paginated

Example — rejected GeoJSON (missing municipality)

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/barangays?province=Bohol&format=geojson"
# → 400 { "message": "...", "code": "parent_required" }

Search Barangays (autocomplete)

GET /v1/barangays/search

Global free-text search. JSON only (no format=geojson in v1).

Multi-word queries are tokenized on spaces/commas; every token must match name, municipality, province, region, or full address (fullName). Examples: poblacion cebu, Lahug NIR, Poblacion, Batangas.

Used by the Vue and Laravel search components.

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Free text (min 2 chars).
`limit`	`integer`	No	Max results (default: `20`).

Example Request

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/barangays/search?q=Lahug%20Cebu"

Example Response

{
  "data": [
    {
      "id": 75322,
      "name": "Lahug",
      "municipality": "City of Cebu",
      "province": "Cebu",
      "region": "Region VII (Central Visayas)",
      "fullName": "Lahug, City of Cebu, Cebu, Region VII (Central Visayas)",
      "code": "0730600041",
      "lCode": "0730600000",
      "pCode": "0702200000",
      "rCode": "0700000000"
    }
  ],
  "error": null
}

Field	Description
`name`	Barangay name
`municipality`	City or municipality name
`province`	Province name
`region`	Region name
`fullName`	Barangay, LGU, province, region (comma-separated)
`code`	Barangay 10-digit PSGC (use this for get-by-id)
`lCode`	City / municipality PSGC
`pCode`	Province PSGC
`rCode`	Region PSGC
`id`	Internal row id (not used in URLs)

Get Single Barangay

GET /v1/barangays/{id}

Returns detailed information about a single barangay. {id} is the PSGC code (not the internal serial row id). Prefer the 10-digit form (e.g. 0730600041); 9-digit variants are expanded when possible.

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Barangay PSGC code (digits only), e.g. `0730600041`.

Query Parameters

Parameter	Type	Required	Description
`format`	`json` \| `geojson`	No	Default `json`. `geojson` → bare Feature.
`geometry`	`simple` \| `medium` \| `detailed`	No	Defaults to `simple` when `format=geojson`.

Example Request (JSON)

curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/barangays/0730600041"

Example Request (GeoJSON Feature)

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

Example Response (GeoJSON Feature)

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [ ... ]
  },
  "properties": {
    "id": 75322,
    "name": "Lahug",
    "type": "Urban",
    "code": "0730600041",
    "l_code": "0730600000",
    "p_code": "0702200000",
    "r_code": "0700000000"
  }
}

Batch search by codes

POST /v1/barangays/search

Accepts a list of PSGC barangay codes and returns matching barangays. Supports both JSON and GeoJSON output formats.

Request Body

Field	Type	Required	Description
`codes`	`string[]`	Yes	List of PSGC barangay codes (e.g. `"0701201001"`).
`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":["0701201001","0701201006"],"geometry":"simple","format":"geojson"}' \
     "https://api.gis.ph/v1/barangays/search"

Example Response (GeoJSON)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Polygon", "coordinates": [ ... ] },
      "properties": {
        "id": 12345,
        "name": "Bahi",
        "code": "0701201001"
      }
    }
  ]
}

Example Response (JSON, Legacy fallback when format omitted)

[
  {
    "id": 12345,
    "name": "Bahi",
    "type": "Rural",
    "code": "0701201001",
    "l_code": "0701201000",
    "p_code": "0701200000",
    "r_code": "0700000000",
    "municity_name": "Alburquerque",
    "province_name": "Bohol"
  }
]