Skip to content
GIS.PH Documentation

Reverse geocode

Reverse geocode answers: which admin unit contains this point? You send WGS84 lat / lng; the API returns region → province → city/municipality → barangay (PSGC codes and names).

It is the opposite of a place-name search. It is not a street-address geocoder (no house number or road).

EndpointGET /v1/geocode/reverse
AuthAPI key / Bearer required. Scope: read:boundaries. Not free-tier.
MethodPoint-in-polygon on admin boundary GeoJSON (geometry=simple by default)

Request access if you do not have a key yet.

Sample call

Section titled “Sample call”

Cebu City (IT Park area):

Terminal window
curl -sS "https://api.gis.ph/v1/geocode/reverse?lat=10.3157&lng=123.8854" \
  -H "Authorization: Bearer $API_KEY"

Without a key: 401 {"message":"Unauthorized"}.

Example — point on land

Section titled “Example — point on land”

Shape of a successful match (codes and names depend on the exact point):

{
  "data": {
    "lat": 10.3157,
    "lng": 123.8854,
    "region": { "code": "0700000000", "name": "Central Visayas" },
    "province": { "code": "0702200000", "name": "Cebu" },
    "municity": { "code": "0730600000", "name": "Cebu City" },
    "barangay": { "code": "0730600xxx", "name": "…" },
    "region_code": "0700000000",
    "province_code": "0702200000",
    "municity_code": "0730600000",
    "barangay_code": "0730600xxx",
    "method": "pip",
    "unmatched_reason": null
  },
  "error": null
}

Use nested region / province / municity / barangay (code + name) in new clients. Flat *_code fields are kept for compatibility.

Example — ocean / outside PH

Section titled “Example — ocean / outside PH”

A miss is still 200, with null codes — not 404.

Terminal window
curl -sS "https://api.gis.ph/v1/geocode/reverse?lat=15.0&lng=130.0" \
  -H "Authorization: Bearer $API_KEY"
{
  "data": {
    "lat": 15.0,
    "lng": 130.0,
    "region": { "code": null, "name": null },
    "province": { "code": null, "name": null },
    "municity": { "code": null, "name": null },
    "barangay": { "code": null, "name": null },
    "region_code": null,
    "province_code": null,
    "municity_code": null,
    "barangay_code": null,
    "method": "pip:none",
    "unmatched_reason": "outside_all_regions"
  },
  "error": null
}

Typical unmatched_reason values: outside_all_regions, outside_all_provinces_in_region, outside_all_municities_in_province, outside_all_barangays_in_municity.

Query parameters

Section titled “Query parameters”
ParameterRequiredDescription
latYesWGS84 latitude (−90…90)
lngYesWGS84 longitude (−180…180)
levelsNoComma-separated subset: region, province, municity, barangay. Default: all four.
geometryNoBoundary resolution used for the polygon test: simple (default, fastest), medium, detailed.

Invalid lat/lng or an unusable levels string → 400. Missing credentials → 401.

Stop early if you only need province:

Terminal window
curl -sS "https://api.gis.ph/v1/geocode/reverse?lat=10.3157&lng=123.8854&levels=region,province" \
  -H "Authorization: Bearer $API_KEY"

How to use it

Section titled “How to use it”
  • Map click or GPS ping → fill an address form with the barangay.
  • Attach a custom place to PSGC without the user picking the LGU.
  • Gate content by province/city from a device location.

Do not use this for street routing or “what’s the postal address of this building.”

Section titled “Related”