> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# States & LGAs

> Nigerian geography lookups — fetch all states, then the Local Government Areas within a state. For address forms, validation, and location-based logic.

<div className="dj-endpoint">
  <span className={`dj-method dj-method-get`}>GET</span>
  <code>/api/v1/general/states</code>
</div>

Two utility lookups for Nigerian geography: fetch all 36 states (plus the FCT), then fetch the Local Government Areas within any one of them. Use them to populate address forms, validate user input, and drive location-based logic.

## Headers

| Header          | Required | Description                                         |
| --------------- | -------- | --------------------------------------------------- |
| `Authorization` | Yes      | Your app's secret key, sent as-is — *not* `Bearer`. |
| `AppId`         | Yes      | The App ID from your dashboard.                     |

## List of states

Call `GET /api/v1/general/states` with no query parameters. Returns a `states` array of every Nigerian state name (including the Federal Capital Territory).

```json 200 — OK theme={null}
{
  "states": [
    "Abia", "Adamawa", "Akwa Ibom", "Anambra",
    "Bauchi", "Bayelsa", "Benue", "Borno",
    "Cross River", "Delta", "Ebonyi", "Edo",
    "Ekiti", "Enugu", "Federal Capital Territory",
    "Gombe", "Imo", "Jigawa", "Kaduna",
    "Kano", "Katsina", "Kebbi", "Kogi",
    "Kwara", "Lagos", "Nasarawa", "Niger",
    "Ogun", "Ondo", "Osun", "Oyo",
    "Plateau", "Rivers", "Sokoto", "Taraba",
    "Yobe", "Zamfara"
  ]
}
```

## List of LGAs

Call `GET /api/v1/general/states/lgas` with a `state` query parameter (a state name from the list above). Returns an `lgas` array of the Local Government Areas in that state.

| Parameter | Type   | Required | Description                                                                |
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
| `state`   | string | Yes      | The state name obtained from the [states](#states) endpoint, e.g. `Lagos`. |

```http GET /api/v1/general/states/lgas theme={null}
curl --request GET "https://api.dojah.io/api/v1/general/states/lgas?state=Lagos" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}"
```

```json 200 — OK theme={null}
{
  "lgas": [
    "Agege", "Ajeromi-Ifelodun", "Alimosho",
    "Amuwo-Odofin", "Apapa", "Badagry",
    "Epe", "Eti-Osa", "Ibeju-Lekki",
    "Ifako-Ijaiye", "Ikeja", "Ikorodu",
    "Kosofe", "Lagos Island", "Lagos Mainland",
    "Mushin", "Ojo", "Oshodi-Isolo",
    "Shomolu", "Surulere"
  ]
}
```

## Errors

| Code  | Meaning                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------- |
| `400` | Bad request — for the LGA lookup, the `state` parameter is missing or not a recognised state name. |
| `401` | Unauthorized — check your secret key and `AppId` (no `Bearer` prefix).                             |
| `429` | Too many requests — back off and retry.                                                            |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    "https://api.dojah.io/api/v1/general/states" \
    -H "Authorization: {{secret_key}}" \
    -H "AppId: {{app_id}}"
  ```

  ```js Node.js theme={null}
  // States — no params. For LGAs add ?state=Lagos
  const res = await fetch("https://api.dojah.io/api/v1/general/states", {
    headers: {
      Authorization: process.env.DOJAH_SECRET_KEY,
      AppId: process.env.DOJAH_APP_ID,
    },
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os, requests  # States — no params. LGAs: params={"state": "Lagos"}

  res = requests.get(
      "https://api.dojah.io/api/v1/general/states",
      headers={
          "Authorization": os.environ["DOJAH_SECRET_KEY"],
          "AppId": os.environ["DOJAH_APP_ID"],
      },
  )
  data = res.json()
  ```
</RequestExample>

<ResponseExample>
  ```json GET /api/v1/general/states theme={null}
  {
    "states": [
      "Abia", "Adamawa", "Akwa Ibom",
      "…", "Lagos", "…", "Zamfara"
    ]
  }
  ```
</ResponseExample>