Regions API

Philippine administrative regions (top of the PSGC hierarchy).

Endpoints

List Regions

GET /v1/regions

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

No parent filter is required for GeoJSON (there are few regions).

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.
`search`	`string`	No	Case-insensitive partial match on name or code.
`codes`	`string` / `string[]`	No	Filter by one or more region codes.
`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/regions?page=1&limit=5"

Example Response (JSON)

{
  "data": [
    {
      "id": 1,
      "name": "Ilocos Region",
      "code": "0100000000"
    }
  ],
  "meta": {
    "total": 18,
    "page": 1,
    "limit": 5,
    "totalPages": 4,
    "links": {
      "self": "...",
      "next": "...",
      "prev": null
    }
  },
  "error": null
}

Example — GeoJSON layer (all regions, simple geometry)

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

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

Example Response (GeoJSON)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [ ... ]
      },
      "properties": {
        "id": 1,
        "name": "Ilocos Region",
        "code": "0100000000"
      }
    }
  ]
}

Get Single Region

GET /v1/regions/{id}

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

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Region PSGC code (digits only), e.g. `0700000000` or `0100000000`.

Query Parameters

Parameter	Type	Required	Description
`format`	`json` \| `geojson`	No	Default `json` → `{ data, error }`. `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/regions/0100000000"

Example Response (JSON)

{
  "data": {
    "id": 1,
    "name": "Ilocos Region",
    "code": "0100000000"
  },
  "error": null
}

Example Request (GeoJSON Feature)

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

Example Response (GeoJSON Feature)

{
  "type": "Feature",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [ ... ]
  },
  "properties": {
    "id": 1,
    "name": "Ilocos Region",
    "code": "0100000000"
  }
}

Batch search by codes

POST /v1/regions/search

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

Request Body

Field	Type	Required	Description
`ids`	`string[]`	Yes	List of PSGC region 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 '{"ids":["0100000000","1300000000"],"geometry":"simple","format":"geojson"}' \
     "https://api.gis.ph/v1/regions/search"

Example Response (GeoJSON)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "MultiPolygon", "coordinates": [ ... ] },
      "properties": {
        "id": 1,
        "name": "Ilocos Region",
        "code": "0100000000"
      }
    }
  ]
}

Example Response (JSON, Legacy fallback when format omitted)

[
  {
    "id": 1,
    "name": "Ilocos Region",
    "code": "0100000000"
  }
]