Hotels

Overview

The Hotels resource provides fake hotel data with names, descriptions, star ratings, contact information, and coordinates.

Endpoints

Method	Endpoint	Description
GET	/v1/hotels	List all hotels
GET	/v1/hotels/:id	Get a specific hotel
GET	/v1/hotels/:id/rooms	Get hotel's rooms
GET	/v1/hotels/:id/reviews	Get hotel's reviews

Hotel Object

{
  "id": 1,
  "cityId": 1,
  "name": "The Grand Hotel",
  "slug": "the-grand-hotel",
  "description": "A luxurious five-star hotel in the heart of the city.",
  "stars": 5,
  "address": "123 Main Street",
  "phone": "+1-555-0100",
  "email": "info@grandhotel.example.com",
  "website": "https://grandhotel.example.com",
  "latitude": 40.758,
  "longitude": -73.9855,
  "image": "https://example.com/images/grand-hotel.jpg",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

Field	Type	Description
id	number	Unique identifier
cityId	number	ID of the city
name	string	Hotel name
slug	string	URL-friendly unique slug
description	string	Hotel description
stars	number	Star rating (1–5)
address	string	Street address
phone	string	Contact phone number
email	string	Contact email
website	string	Hotel website URL
latitude	number	Latitude coordinate
longitude	number	Longitude coordinate
image	string	Hotel image URL
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

List Hotels

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

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
cityId	number	—	Filter by city ID
stars	number	—	Filter by star rating

Response

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

Get Hotel by ID

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

Response

{
  "data": {
    "id": 1,
    "cityId": 1,
    "name": "The Grand Hotel",
    "slug": "the-grand-hotel",
    "description": "A luxurious five-star hotel in the heart of the city.",
    "stars": 5,
    "address": "123 Main Street",
    "phone": "+1-555-0100",
    "email": "info@grandhotel.example.com",
    "website": "https://grandhotel.example.com",
    "latitude": 40.758,
    "longitude": -73.9855
  }
}

Get Hotel’s Rooms

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

Response

{
  "data": [
    {
      "id": 1,
      "hotelId": 1,
      "name": "Deluxe Suite",
      "type": "suite",
      "price": 299.99,
      "currency": "USD",
      "capacity": 2,
      "available": true
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get Hotel’s Reviews

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

Response

{
  "data": [
    {
      "id": 1,
      "hotelId": 1,
      "userId": 1,
      "rating": 5,
      "title": "Amazing stay!",
      "comment": "The service was exceptional."
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Examples

Search Hotels

curl "https://api.phantomjson.app/v1/hotels?q=grand"

Filter by City

curl "https://api.phantomjson.app/v1/hotels?cityId=1"

Filter by Star Rating

curl "https://api.phantomjson.app/v1/hotels?stars=5"

Sort by Stars

# Lowest first
curl "https://api.phantomjson.app/v1/hotels?sort=stars:asc"

# Highest first
curl "https://api.phantomjson.app/v1/hotels?sort=stars:desc"

Sort by Name

curl "https://api.phantomjson.app/v1/hotels?sort=name:asc"

Field Selection

curl "https://api.phantomjson.app/v1/hotels?fields=id,name,stars,cityId"

Combined Query

# Five-star hotels in city 1
curl "https://api.phantomjson.app/v1/hotels?cityId=1&stars=5&sort=name:asc"

Relations

• City — Each hotel belongs to a city (cityId)
• Rooms — Each hotel has many rooms (access via /v1/hotels/:id/rooms)
• Reviews — Each hotel has many reviews (access via /v1/hotels/:id/reviews)