--- title: Administrative Units API - Get Country Subdivisions & Admin Units version: 1.0.0 description: Retrieve administrative units (states, provinces, governorates, districts) for any country using ISO 3166-1 alpha-2 country codes. Each result includes the unit name, admin code, and admin level type. Optionally filter results by one or more administrative levels using the `admin_level` parameter with comma-separated level names; a level name that matches nothing returns a 200 with an empty admin_units array, not an error. A valid country code is required; countries without published admin units return a 404. openapi: 3.1.1 servers: - https://api.apifreaks.com/v1.0 paths: 1 operations: 1 schemas: 3 --- ## Table of Contents - [Administrative Units API - Get Country Subdivisions & Admin Units v1.0.0](#administrative-units-api-get-country-subdivisions-admin-units-v100) - [Authentication](#authentication) - [GeoDB APIs](#geodb-apis) - [getAdminUnits](#getadminunits) - [Parameters](#parameters) - [Responses](#responses) - [Schemas](#schemas) - [AdminUnitsResponse](#adminunitsresponse) - [AdminUnit](#adminunit) - [ErrorResponse](#errorresponse) # Administrative Units API - Get Country Subdivisions & Admin Units v1.0.0 Retrieve administrative units (states, provinces, governorates, districts) for any country using ISO 3166-1 alpha-2 country codes. Each result includes the unit name, admin code, and admin level type. Optionally filter results by one or more administrative levels using the `admin_level` parameter with comma-separated level names; a level name that matches nothing returns a 200 with an empty admin_units array, not an error. A valid country code is required; countries without published admin units 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 ### getAdminUnits `GET /geo/admin-units` *Retrieve administrative units for a country with optional level filtering* Returns all administrative units (states, provinces, districts) for a country using ISO 3166-1 alpha-2 country code. Optionally filter by one or more admin levels. #### 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).| |admin_level|query|string|false|Comma-separated list to filter results by one or more administrative levels (e.g., state, district). A level name that doesn't exist for the country returns a 200 with an empty admin_units array rather than an error.| ##### Enumerated Values |Parameter|Value| |---|---| |format|json| |format|xml| > Example responses > Successful response with list of administrative units ```json { "admin_units": [ { "name": "California", "admin_code": "CA", "admin_level": "state" }, { "name": "Texas", "admin_code": "TX", "admin_level": "state" }, { "name": "New York", "admin_code": "NY", "admin_level": "state" } ] } ``` > 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-units", "status": 400, "timestamp": "2026-07-24T10:44:10.185Z" } ``` ```json { "timestamp": "2026-07-24T10:44:10.711Z", "path": "/v1/admin-units", "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 units (e.g. Vatican City) ```json { "timestamp": "2026-07-24T10:44:11.244Z", "path": "/v1/admin-units", "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 units|[AdminUnitsResponse](#adminunitsresponse)| |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 units (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 ### AdminUnitsResponse Response containing the administrative units for the requested country, optionally filtered by admin_level. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |admin_units|[[AdminUnit](#adminunit)]|true|none|An array of administrative unit objects for the specified country.| ### AdminUnit An administrative unit object. #### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |name|string|true|none|Name of the administrative unit.| |admin_code|string|true|none|Administrative code of the unit.| |admin_level|string|true|none|Level or type of the administrative unit (e.g., state, district, province).| ### 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).|