Authentication

Base URL:

• Production: https://api.gis.ph

Most /v1/* endpoints require an Authorization: Bearer … header. Admin boundary metadata is the exception (see free tier below).

Something broken against the API or dashboard? Report a bug (public intake — do not paste keys).

For the full operation list and try-it-out UI, use the live API reference (Scalar). Guides on this site stay high-level; field-level detail comes from OpenAPI on the API.

---

Free tier (boundary metadata)

No API key required for read-only JSON admin geography:

Allowed without auth	Not free (auth required)
GET /v1/regions, /v1/provinces, /v1/municities, /v1/barangays (and get-by-id) as JSON	format=geojson or output=geojson
List / search metadata (subject to route query rules, e.g. province= for municities/barangays)	geometry=simple|medium|detailed (or legacy true)
Rate limited (~30 requests/minute per client IP)	Datasets, places, keys, reverse geocode (guide), tiles sessions (Waterways), writes, admin

Unauthenticated heavy geometry returns 403 with code: "FREE_TIER_GEOMETRY_DENIED". Use an API key (or dashboard session) for GeoJSON and geometry.

Successful free responses may include:

• X-Gis-Tier: free
• X-RateLimit-Limit / Remaining / Reset

Try it

# Free — JSON metadata
curl "https://api.gis.ph/v1/regions?limit=5"

curl "https://api.gis.ph/v1/provinces?limit=5"

curl "https://api.gis.ph/v1/municities?province=Bohol&limit=5"

# Needs a key — GeoJSON / geometry
curl -H "Authorization: Bearer gis_sk_live_…" \
  "https://api.gis.ph/v1/regions?format=geojson"

---

Request access (API keys)

For GeoJSON, higher rate limits, datasets, and production apps, request access or use the dashboard to create a user API key (gis_sk_live_… / gis_sk_test_…).

Keys support scopes and rate limits (enforced). See Managing API Keys and Scalar (tag API Keys).

---

Authentication methods

User API keys (recommended)

GET https://api.gis.ph/v1/provinces?format=geojson
Authorization: Bearer gis_sk_live_…

Best for apps, SDKs, CLI, and server integrations. Create keys while signed in to the dashboard.

Dashboard session (JWT)

Browser/dashboard flows use a Clerk-issued JWT accepted by the API (same Authorization: Bearer header). Not for embedding in public frontends as a long-lived secret.

Master token

Internal/admin only. Full access; do not ship in client apps.

---

Testing with REST clients

cURL (free metadata)

curl "https://api.gis.ph/v1/provinces?limit=10"

cURL (authenticated)

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

VS Code REST Client

@baseUrl = https://api.gis.ph
@token = your_api_key

### Free JSON
GET {{baseUrl}}/v1/regions?limit=5

### Authenticated GeoJSON
GET {{baseUrl}}/v1/regions?format=geojson
Authorization: Bearer {{token}}

Postman

1. Create a GET request to https://api.gis.ph/v1/regions?limit=5 (no auth for free JSON).
2. For GeoJSON, set Authorization → Bearer Token to your API key.

---

Security best practices

1. Never commit keys — use env vars; keep .env out of git.
2. Prefer server-side keys — do not embed live keys in public browser apps.
3. Scope keys when possible; use separate test/live keys.

---

Error responses

401 Unauthorized

Missing or invalid token on a route that requires auth:

{ "message": "Unauthorized" }

403 Forbidden — free tier geometry

{
  "message": "Free tier allows boundary metadata (JSON) only. …",
  "code": "FREE_TIER_GEOMETRY_DENIED",
  "hint": "Omit format=geojson / geometry=… for free JSON, or send Authorization: Bearer <gis_sk_… | JWT>."
}

429 Too Many Requests

Free tier or API key rate limit exceeded (code: "RATE_LIMIT_EXCEEDED"). Respect Retry-After and X-RateLimit-* headers.

404 Not Found

Resource missing or not visible to the caller.