API Documentation - Hotels API

Overview

Hotels API provides global hotel data with fast search and geo search.

Base URL

https://hotels-api.com/api

Authentication

All requests require your API key in the X-API-KEY header.

curl -H "X-API-KEY: YOUR_API_KEY" \
  "https://hotels-api.com/api/hotels/search?city=Madrid"

Quick Start

Create an account and get your API key from the dashboard.
Make your first search request.
Use page + limit to paginate.

Response Format

By default, endpoints return a standard wrapper with success, data and timestamp.

Minimal hotel object (fields)

{
  "id": 12345,
  "name": "Hotel Barcelona Center",
  "city": "Barcelona",
  "country": "Spain",
  "countryCode": "ES",
  "address": "Carrer de Balmes, 123, 08007",
  "rating": 4,
  "latitude": 41.3851,
  "longitude": 2.1734,
  "amenities": ["parking", "restaurant", "bar", "wifi"]
}

Raw mode (no wrapper): add raw=1 to return a plain JSON array/object.

https://hotels-api.com/api/hotels/search?city=Madrid&limit=2&raw=1

Endpoints

Search Hotels

GET /hotels/search

Query Params

city (string)
country (string)
countryCode (string)
name (string)
rating (number)
min_rating (number)
page (number)
limit (number, max 500)
raw (1 to return plain JSON)

GET /hotels/search?city=Madrid&min_rating=4&limit=20&page=1

List Hotels

GET /hotels

Query Params

page (number)
limit (number, max 500)
raw (1 to return plain JSON)

GET /hotels?page=1&limit=50

Nearby Hotels (Geo Search)

GET /hotels/nearby

This endpoint requires a plan that includes geo-search.

Query Params

lat (number, required)
lng (number, required)
radius (number, km; default 10)
page (number)
limit (number, max 500)
raw (1 to return plain JSON)

GET /hotels/nearby?lat=40.4168&lng=-3.7038&radius=10&limit=20

Hotel Detail

GET /hotels/{id}

Path Params

id (number, required)

GET /hotels/698731

Errors

Errors are returned with standard HTTP status codes.

401 Missing or invalid API key
429 Rate limit exceeded
500 Server error

Rate Limits

Your plan defines the monthly request limit. If you exceed it, you will receive a 429 response.

Support

Need help? Contact alabannere@me.com.