---
title: Admin Levels API Reference
version: 1.0.0
description: Retrieve the administrative level hierarchy for any country using ISO 3166-1 alpha-2 country codes. Returns the distinct administrative level types defined for that country (e.g., state, district, province, outlying area) as a flat array of strings. Use the returned level names with the Administrative Units endpoint to filter results by one or more specific levels. A valid two-letter country code is required; invalid codes return a 400 error and countries without published admin levels return a 404.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Admin Levels API Reference v1.0.0](#admin-levels-api-reference-v100)
  - [Authentication](#authentication)
  - [GeoDB APIs](#geodb-apis)
    - [getAdminLevels](#getadminlevels)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [AdminLevelsResponse](#adminlevelsresponse)
    - [ErrorResponse](#errorresponse)



# Admin Levels API Reference v1.0.0

Retrieve the administrative level hierarchy for any country using ISO 3166-1 alpha-2 country codes. Returns the distinct administrative level types defined for that country (e.g., state, district, province, outlying area) as a flat array of strings. Use the returned level names with the Administrative Units endpoint to filter results by one or more specific levels. A valid two-letter country code is required; invalid codes return a 400 error and countries without published admin levels return a 404.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## GeoDB APIs

### getAdminLevels

`GET /geo/admin-levels`

*Retrieve administrative level types for a country*

Returns the distinct administrative level types (e.g., province, district, state) defined for a given country using ISO 3166-1 alpha-2 country code.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|country|query|string|true|Country code in ISO 3166-1 alpha-2 format (e.g., US, PK).|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful response with list of administrative levels

```json
{
  "admin_levels": [
    "outlying area",
    "district",
    "state",
    "military postal region"
  ]
}
```

> Bad Request — Missing country parameter, or country is not a valid/known ISO 3166-1 alpha-2 code

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/geo/admin-levels",
  "status": 400,
  "timestamp": "2026-07-24T10:42:02.477Z"
}
```

```json
{
  "timestamp": "2026-07-24T10:42:02.997Z",
  "path": "/v1/admin-levels",
  "status": 400,
  "error": "Invalid Country Code provided",
  "message": "Only ISO 3166-1 alpha-2 codes country codes are supported."
}
```

> Not Found — Country is a recognized ISO 3166-1 alpha-2 code but has no published admin levels (e.g. Vatican City)

```json
{
  "timestamp": "2026-07-24T10:42:15.470Z",
  "path": "/v1/admin-levels",
  "status": 404,
  "error": "No Admin Unit present in country",
  "message": "This Country does not have any admin units associated with it."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with list of administrative levels|[AdminLevelsResponse](#adminlevelsresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing country parameter, or country is not a valid/known ISO 3166-1 alpha-2 code|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — Country is a recognized ISO 3166-1 alpha-2 code but has no published admin levels (e.g. Vatican City)|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### AdminLevelsResponse

Response containing the distinct administrative level types defined for the requested country.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|admin_levels|[string]|true|none|An array of unique administrative level types defined for the specified country. Each value represents a category of administrative division, such as state, district, or outlying area.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|