Cities

Overview

The Cities resource provides fake city data with names, descriptions, populations, coordinates, and geographic information.

Endpoints

Method	Endpoint	Description
GET	/v1/cities	List all cities
GET	/v1/cities/:id	Get a specific city
GET	/v1/cities/:id/airports	Get city's airports
GET	/v1/cities/:id/hotels	Get city's hotels

City Object

{
  "id": 1,
  "countryId": 1,
  "name": "New York",
  "slug": "new-york",
  "description": "The largest city in the United States.",
  "population": 8336817,
  "area": 783.8,
  "latitude": 40.7127753,
  "longitude": -74.0059728,
  "timezone": "America/New_York",
  "image": "https://example.com/images/new-york.jpg",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

Field	Type	Description
id	number	Unique identifier
countryId	number	ID of the country
name	string	City name
slug	string	URL-friendly unique slug
description	string	City description
population	number	Population count
area	number	Area in square kilometers
latitude	number	Latitude coordinate
longitude	number	Longitude coordinate
timezone	string	Timezone
image	string	City image URL
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

List Cities

curl https://api.phantomjson.app/v1/cities

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max: 100)
sort	string	—	Sort field and direction
q	string	—	Search query
fields	string	—	Fields to return
countryId	number	—	Filter by country ID

Response

{
  "data": [
    {
      "id": 1,
      "countryId": 1,
      "name": "New York",
      "slug": "new-york",
      "population": 8336817
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}

Get City by ID

curl https://api.phantomjson.app/v1/cities/1

Response

{
  "data": {
    "id": 1,
    "countryId": 1,
    "name": "New York",
    "slug": "new-york",
    "description": "The largest city in the United States.",
    "population": 8336817,
    "area": 783.8,
    "latitude": 40.7127753,
    "longitude": -74.0059728,
    "timezone": "America/New_York"
  }
}

Get City’s Airports

curl https://api.phantomjson.app/v1/cities/1/airports

Response

{
  "data": [
    {
      "id": 1,
      "cityId": 1,
      "name": "John F. Kennedy International Airport",
      "code": "JFK",
      "iataCode": "JFK"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get City’s Hotels

curl https://api.phantomjson.app/v1/cities/1/hotels

Response

{
  "data": [
    {
      "id": 1,
      "cityId": 1,
      "name": "The Grand Hotel",
      "slug": "the-grand-hotel",
      "stars": 5
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Examples

Search Cities

curl "https://api.phantomjson.app/v1/cities?q=new"

Filter by Country

curl "https://api.phantomjson.app/v1/cities?countryId=1"

Sort by Population

# Smallest first
curl "https://api.phantomjson.app/v1/cities?sort=population:asc"

# Largest first
curl "https://api.phantomjson.app/v1/cities?sort=population:desc"

Field Selection

curl "https://api.phantomjson.app/v1/cities?fields=id,name,countryId,population"

Combined Query

# Large cities in the US
curl "https://api.phantomjson.app/v1/cities?countryId=1&population[gte]=1000000&sort=population:desc"

Relations

• Country — Each city belongs to a country (countryId)
• Airports — Each city has many airports (access via /v1/cities/:id/airports)
• Hotels — Each city has many hotels (access via /v1/cities/:id/hotels)
• Destinations — Each city has many destinations