Locations API

Read Ghana administrative locations used by LEAP: /api/v1/regions, /api/v1/districts, and /api/v1/communities. Authenticate with a session that has access to CONFIGURATION, USERS_MANAGEMENT, or PSP_PORTAL.

GET
On this page
Overview Authentication GET regions GET districts GET communities Errors
Overview

Locations are hierarchical: region → district → community. Districts reference a region via parent_code. Communities reference a district via parent_code.

  • Content type: application/json
  • List vs single: omit id/code for an array; pass either for a single object in data
Authentication

Sign in with POST /api/v1/session, then send the session token on every request: 

token: YOUR_SESSION_TOKEN
Authorization: Bearer YOUR_SESSION_TOKEN
x-access-token: YOUR_SESSION_TOKEN

GET requires module access to any of: CONFIGURATION, USERS_MANAGEMENT, or PSP_PORTAL. Missing access returns 403.

GET regions
GET /api/v1/regions

Lists regions from lpm_regions, ordered by name. Each row includes a live district_count of active districts.

Query parameters
Name Type Description
id integer Optional. Return a single region by internal id.
code string Optional. Return a single region by code (1–2 chars). Used if id is omitted.
Response fields
Field Notes
codeRegion code.
nameRegion name.
capitalRegional capital, or null.
leap_idLEAP / external numeric id, or null.
district_countCount of active districts under this region.
Example request
curl -X GET "https://YOUR_HOST/api/v1/regions" \
  -H "token: YOUR_SESSION_TOKEN"

curl -X GET "https://YOUR_HOST/api/v1/regions?code=02" \
  -H "token: YOUR_SESSION_TOKEN"
Example list response
{
  "successful": true,
  "data": [
    {
      "code": "02",
      "name": "Ashanti",
      "capital": "Kumasi",
      "leap_id": "2",
      "district_count": 43
    }
  ]
}
Example single response
{
  "successful": true,
  "data": {
    "code": "02",
    "name": "Ashanti",
    "capital": "Kumasi",
    "leap_id": "2",
    "district_count": 43
  }
}
GET districts
GET /api/v1/districts

Lists districts from lpm_districts, joined to the parent region, ordered by district name.

Query parameters
Name Type Description
id integer Optional. Return a single district by internal id.
code string Optional. Return a single district by code (max 20 chars).
region_code string Optional. Filter districts whose parent_code matches this region. Aliases: parent_code, regionCode.
Response fields
Field Notes
codeDistrict code (e.g. 02-03).
nameDistrict name.
parent_codeParent region code.
leap_idLEAP / external numeric id, or null.
region_nameParent region name, or null.
region_capitalParent region capital, or null.
Example request
curl -X GET "https://YOUR_HOST/api/v1/districts?region_code=02" \
  -H "token: YOUR_SESSION_TOKEN"

curl -X GET "https://YOUR_HOST/api/v1/districts?code=02-03" \
  -H "token: YOUR_SESSION_TOKEN"
Example list response
{
  "successful": true,
  "data": [
    {
      "code": "02-03",
      "name": "Example District",
      "parent_code": "02",
      "leap_id": "88",
      "region_name": "Ashanti",
      "region_capital": "Kumasi"
    }
  ],
  "filter": {
    "region_code": "02"
  }
}

List responses include filter when region_code was applied; otherwise filter is null. Single-item lookups omit filter.

GET communities
GET /api/v1/communities

Lists communities from lpm_communities, joined to parent district and region, ordered by community name.

Query parameters
Name Type Description
id integer Optional. Return a single community by internal id.
code string Optional. Return a single community by code (max 50 chars).
district_code string Optional. Filter communities whose parent_code matches this district. Aliases: parent_code, districtCode.
region_code string Optional. Filter by parent district’s region code. Alias: regionCode.
Response fields
Field Notes
codeCommunity code (e.g. 02-03-006).
nameCommunity name.
parent_codeParent district code.
district_nameParent district name, or null.
region_codeParent region code, or null.
region_nameParent region name, or null.
Example request
curl -X GET "https://YOUR_HOST/api/v1/communities?district_code=02-03" \
  -H "token: YOUR_SESSION_TOKEN"

curl -X GET "https://YOUR_HOST/api/v1/communities?region_code=02&district_code=02-03" \
  -H "token: YOUR_SESSION_TOKEN"

curl -X GET "https://YOUR_HOST/api/v1/communities?code=02-03-006" \
  -H "token: YOUR_SESSION_TOKEN"
Example list response
{
  "successful": true,
  "data": [
    {
      "code": "02-03-006",
      "name": "Example Community",
      "parent_code": "02-03",
      "district_name": "Example District",
      "region_code": "02",
      "region_name": "Ashanti"
    }
  ],
  "filter": {
    "district_code": "02-03",
    "region_code": "02"
  }
}

List responses include filter when district and/or region filters were applied; otherwise filter is null.

Errors
HTTP When
403 No session, or session lacks CONFIGURATION / USERS_MANAGEMENT / PSP_PORTAL access.
404 Single lookup by id or code found no matching row.
405 Unsupported method on the docs page (API supports more methods for CONFIGURATION users).
500 Database or server error.