Provinces API

Philippine provinces (and province-equivalent units).

Endpoints

List Provinces

GET /v1/provinces

Returns provinces as a paginated JSON envelope by default, or an unpaginated GeoJSON FeatureCollection when format=geojson.

For GeoJSON, the region parameter is optional (all provinces may be returned). Prefer scoping by region for map drill-down.

Query Parameters

Parameter	Type	Required	Description
`page`	`integer`	No	Page number (default: `1`). JSON only.
`limit`	`integer`	No	Items per page (default: `10`, max: `100`). JSON only.
`region`	`string`	No	Parent filter: region code or exact name. Optional for geojson.
`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/provinces?limit=5"

Example Response (JSON)

{
  "data": [
    {
      "id": 1,
      "name": "Abra",
      "code": "1401000000",
      "r_code": "1400000000"
    }
  ],
  "meta": {
    "total": 82,
    "page": 1,
    "limit": 5,
    "totalPages": 17,
    "links": {
      "self": "...",
      "next": "...",
      "prev": null
    }
  },
  "error": null
}

Example — GeoJSON (optional region)

# All provinces (simple geometry)
curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/provinces?format=geojson"

# Provinces in one region
curl -H "Authorization: Bearer <token>" \
     "https://api.gis.ph/v1/provinces?region=07&format=geojson"

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

Get Single Province

GET /v1/provinces/{id}

Returns detailed information about a single province. {id} is the PSGC code (not the internal serial row id). Prefer the 10-digit form (e.g. 0702200000 for Cebu).

Path Parameters

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

Query Parameters

Parameter	Type	Required	Description
`format`	`json` \| `geojson`	No	Default `json`. `geojson` → bare Feature.
`geometry`	`simple` \| `medium` \| `detailed` \| `true`	No	Level for boundary geometry. `true` is legacy JSON-only nested payload. For `format=geojson`, defaults to simple.

Example Request (JSON)

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

Example Response (JSON)

{
  "data": {
    "id": 94,
    "name": "Kalinga",
    "code": "1403200000",
    "r_code": "1400000000"
  },
  "error": null
}

Example Request (GeoJSON Feature)

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

Example Response (GeoJSON Feature)

{
  "type": "Feature",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [ ... ]
  },
  "properties": {
    "id": 94,
    "name": "Kalinga",
    "code": "1403200000"
  }
}

Example — Legacy nested municipalities (JSON)

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

Example Response (Legacy nested JSON)

{
  "data": {
    "id": 94,
    "name": "Kalinga",
    "code": "1403200000"
  },
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { ... },
        "properties": {
          "name": "Tabuk City"
        }
      }
    ]
  },
  "error": null
}

Batch search by codes

POST /v1/provinces/search

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

Request Body

Field	Type	Required	Description
`codes`	`string[]`	Yes	List of PSGC province 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":["1206500000","0701200000"],"geometry":"simple","format":"geojson"}' \
     "https://api.gis.ph/v1/provinces/search"

Example Response (GeoJSON)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "MultiPolygon", "coordinates": [ ... ] },
      "properties": {
        "id": 135,
        "name": "Bohol",
        "code": "0701200000"
      }
    }
  ]
}

Example Response (JSON, Legacy fallback when format omitted)

[
  {
    "id": 135,
    "name": "Bohol",
    "code": "0701200000"
  }
]