---
title: Cities API - Get City Data for Any Country
version: 1.0.0
description: "Retrieve all cities for a given country with their latitude, longitude, administrative unit details, and ISO country code. Uses ISO 3166-1 alpha-2 country codes. Optionally filter by administrative unit code using the `admin_unit` parameter to narrow results to a specific region or province; an admin_unit code that doesn't exist for the country returns a 400 error here (unlike the Administrative Units endpoint's admin_level filter, which returns an empty array for an unknown level). Each city result includes name, coordinates, admin unit information (name, code, level), and the two-letter country code. There is no pagination: large countries return every city in one response. A valid country code is required."
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 4
---

## Table of Contents

- [Cities API - Get City Data for Any Country v1.0.0](#cities-api-get-city-data-for-any-country-v100)
  - [Authentication](#authentication)
  - [GeoDB APIs](#geodb-apis)
    - [getCities](#getcities)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CitiesResponse](#citiesresponse)
    - [CityItem](#cityitem)
    - [AdminUnit](#adminunit)
    - [ErrorResponse](#errorresponse)



# Cities API - Get City Data for Any Country v1.0.0

Retrieve all cities for a given country with their latitude, longitude, administrative unit details, and ISO country code. Uses ISO 3166-1 alpha-2 country codes. Optionally filter by administrative unit code using the `admin_unit` parameter to narrow results to a specific region or province; an admin_unit code that doesn't exist for the country returns a 400 error here (unlike the Administrative Units endpoint's admin_level filter, which returns an empty array for an unknown level). Each city result includes name, coordinates, admin unit information (name, code, level), and the two-letter country code. There is no pagination: large countries return every city in one response. A valid country code is required.

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

### getCities

`GET /geo/cities`

*Retrieve cities for a country with optional admin unit filtering*

Returns all cities for a country, optionally filtered by administrative unit. Each city includes name, coordinates, admin unit details, and ISO 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).|
|admin_unit|query|string|false|Administrative unit code used to filter cities within a specific region. An admin_unit code that doesn't exist for the specified country returns a 400 error, not an empty result.|

##### Enumerated Values

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

> Example responses

> Successful response with list of cities

```json
{
  "cities": [
    {
      "name": "Aberdeen",
      "latitude": 57.14369,
      "longitude": -2.09814,
      "admin_unit": {
        "name": "Aberdeen",
        "admin_code": "ABE",
        "admin_level": "council area"
      },
      "iso_alpha_2": "GB"
    },
    {
      "name": "Balmedie",
      "latitude": 57.25052,
      "longitude": -2.06163,
      "admin_unit": {
        "name": "Aberdeen",
        "admin_code": "ABE",
        "admin_level": "council area"
      },
      "iso_alpha_2": "GB"
    }
  ]
}
```

> Bad Request — Missing country parameter, invalid country code, or admin_unit code not found for the country

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

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

```json
{
  "timestamp": "2026-07-24T10:56:42.419Z",
  "path": "/v1/cities",
  "status": 400,
  "error": "Invalid Admin Code provided",
  "message": "Please provide a valid admin code."
}
```

> Not Found — Country is a recognized ISO 3166-1 alpha-2 code but has no cities in the database (e.g. Vatican City)

```json
{
  "timestamp": "2026-07-24T10:56:42.941Z",
  "path": "/v1/cities",
  "status": 404,
  "error": "No Cities present in country",
  "message": "This country does not have any cities 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 cities|[CitiesResponse](#citiesresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing country parameter, invalid country code, or admin_unit code not found for the country|[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 cities in the database (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

### CitiesResponse

Response containing every city for the requested country (optionally filtered by admin_unit), returned unpaginated in a single array.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|cities|[[CityItem](#cityitem)]|true|none|An array of city objects for the specified country, optionally filtered by admin unit.|

### CityItem

A city object containing name, coordinates, admin unit, and country code.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|The name of the city.|
|latitude|number(float)|true|none|The geographic latitude of the city in decimal degrees.|
|longitude|number(float)|true|none|The geographic longitude of the city in decimal degrees.|
|iso_alpha_2|string|true|none|The ISO 3166-1 alpha-2 country code the city belongs to.|
|admin_unit|[AdminUnit](#adminunit)|true|none|An object describing the administrative unit the city belongs to.|

### AdminUnit

An object describing the administrative unit the city belongs to.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|true|none|The full name of the administrative unit.|
|admin_code|string|true|none|The short code of the administrative unit.|
|admin_level|string|true|none|The administrative level type of the unit (e.g., province, council 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).|