📡 Global Production Endpoint

Use this endpoint for all live rate lookups. Average latency: ~650ms.

POST https://www.businesshotels.com/mcp-server.php?route=tools/get_live_hotel_rates

Header: X-API-KEY: test-live-hotel-rates2025
Content-Type: application/json

💡 Production Ready: This key is ready for AI agent integration and general use. For enterprise deployments or commercial applications, contact ai@businesshotels.com for dedicated support.

🛠️ Request Tool Schema (MCP/OpenAI)

Use this schema in LLM tool definitions or function calling (OpenAI, Gemini, Claude, etc.).

Tool Definition

{
  "name": "get_live_hotel_rates",
  "description": "Retrieve real-time rates for a specific hotel from a 2 million property database. Best for: Exact hotel matches with price-locked booking links.",
  "parameters": {
    "type": "object",
    "properties": {
      "hotelName": {
        "type": "string",
        "description": "REQUIRED. Detailed name + City + Country. Example: 'InterContinental Mark Hopkins, San Francisco, US'. Providing the country code ensures 99.9% match accuracy."
      },
      "checkinDate": {
        "type": "string",
        "format": "date",
        "description": "Check-in date in YYYY-MM-DD format."
      },
      "checkoutDate": {
        "type": "string",
        "format": "date",
        "description": "Check-out date in YYYY-MM-DD format."
      },
      "adults": {
        "type": "integer",
        "default": 1,
        "description": "Number of adult guests (1–4)."
      },
      "currency": {
        "type": "string",
        "default": "USD",
        "description": "3-letter ISO code (USD, EUR, GBP)."
      }
    },
    "required": ["hotelName", "checkinDate", "checkoutDate"],
    "additionalProperties": false
  }
}

🧩 MCP Tools Array Example

Use this JSON in your MCP server’s tools/list response to register the tool via inputSchema.

MCP tools entry

{
  "tools": [
    {
      "name": "get_live_hotel_rates",
      "title": "BusinessHotels Live Hotel Rates",
      "description": "Retrieve real-time rates for a specific hotel from a 2M+ property database, returning a booking URL with a price-locked ppn_bundle.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "hotelName": {
            "type": "string",
            "description": "REQUIRED. Detailed name + City + Country. Example: 'InterContinental Mark Hopkins, San Francisco, US'."
          },
          "checkinDate": {
            "type": "string",
            "format": "date",
            "description": "Check-in date in YYYY-MM-DD format."
          },
          "checkoutDate": {
            "type": "string",
            "format": "date",
            "description": "Check-out date in YYYY-MM-DD format."
          },
          "adults": {
            "type": "integer",
            "default": 1,
            "description": "Number of adult guests (1–4)."
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "3-letter ISO code (USD, EUR, GBP)."
          }
        },
        "required": ["hotelName", "checkinDate", "checkoutDate"],
        "additionalProperties": false
      }
    }
  ]
}

📖 Intelligent Response Mapping

Response Key	Agent Instruction / Logical Mapping
`hotel_name`	Confirm this identity with the user.
`hotel_address`	Display for logistical clarity (Street, City, Zip).
`latitude` / `longitude`	Map Trigger: Use for map pins/distance calculation.
`display_all_in_total`	Display as the single, all-inclusive "Final Price".
`booking_page_live_rates`	Present as the primary checkout action.
`ppn_bundle`	Internal inventory token. Locked for 20 minutes.
`best_match_score`	If score < 0.85, clarify hotel identity with user.

📖 Response Data Model

Field	Type	Agent Action
`hotel_id`	String (9-digit)	Store for session persistence.
`display_all_in_total`	Float	Quote as the Final Price (includes all taxes).
`booking_page_live_rates`	URL	Present as a direct booking button/link.

🧠 Match Verification Logic

Score > 0.85: Procedural/direct match. Present the price and "Book Now" link immediately.
Score 0.60 – 0.85: Ambiguous match. Ask: "I found [Hotel Name] in [City]. Is this the correct property?"
Score < 0.60: No reliable match. Ask for a more specific hotel name or address.

⚠️ Critical Error Handling

If the API returns a 400 Validation Error, verify that hotelName is present. The system always requires a name string, even if a hotel_id is known internally.

🛠️ Quick Integration Steps

Authentication: Pass your key via api_key in the JSON body or X-API-KEY in the header.
Date Formatting: Convert relative dates (e.g., "next Friday") into YYYY-MM-DD strings.
Rich Data: Use latitude and longitude to display maps or nearby POIs.
Booking Handoff: Always use the booking_page_live_rates URL; it contains the ppn_bundle which locks the rate for 20 minutes.

💻 Code Examples

Test the API in your preferred language. All examples demonstrate the same request with identical parameters.

Bash / Terminal – Copy and paste into your terminal (macOS/Linux/WSL).

cURL

curl -X POST "https://www.businesshotels.com/mcp-server.php?route=tools/get_live_hotel_rates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: test-live-hotel-rates2025" \
  -d '{
    "hotelName": "Luxor Las Vegas, Las Vegas, US",
    "checkinDate": "2026-02-15",
    "checkoutDate": "2026-02-17",
    "adults": 2,
    "currency": "USD"
  }'

💡 Platform-specific notes:

Windows CMD: Replace single quotes with double quotes and escape inner quotes.
PowerShell: Use backtick ` for line continuation instead of backslash \.
Multi-line JSON: Keeping JSON on a single line avoids shell parsing issues.

Python 3 – Requires requests library.

Python

import requests

url = "https://www.businesshotels.com/mcp-server.php?route=tools/get_live_hotel_rates"
headers = {
    "X-API-KEY": "test-live-hotel-rates2025",
    "Content-Type": "application/json"
}
payload = {
    "hotelName": "Luxor Las Vegas, Las Vegas, US",
    "checkinDate": "2026-02-15",
    "checkoutDate": "2026-02-17",
    "adults": 2,
    "currency": "USD"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

# Access specific fields
print(f"Hotel: {data['hotel_name']}")
print(f"Price: ${data['rates']['display_all_in_total']} {data['rates']['currency']}")
print(f"Booking URL: {data['booking_page_live_rates']}")

JavaScript (Node.js or Browser) – Uses native fetch API.

JavaScript

const url = "https://www.businesshotels.com/mcp-server.php?route=tools/get_live_hotel_rates";
const payload = {
  hotelName: "Luxor Las Vegas, Las Vegas, US",
  checkinDate: "2026-02-15",
  checkoutDate: "2026-02-17",
  adults: 2,
  currency: "USD"
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "test-live-hotel-rates2025"
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
    console.log(`Hotel: ${data.hotel_name}`);
    console.log(`Price: $${data.rates.display_all_in_total} ${data.rates.currency}`);
    console.log(`Booking URL: ${data.booking_page_live_rates}`);
  })
  .catch(error => console.error("Error:", error));

Alternative: Using your existing helper function

Browser Console

(async () => {
  const result = await window.businessHotelsAPI.getHotelRates(
    "Luxor Las Vegas, Las Vegas, US",
    "2026-02-15",
    "2026-02-17",
    2,
    "USD"
  );
  console.log(result);
})();

📦 Expected Response:

JSON Response (200 OK)

{
    "hotel_id": "700076955",
  "hotel_name": "Luxor",
  "hotel_address": "3900 Las Vegas Boulevard South",
  "city_name": "Las Vegas",
  "state_code": "NV",
  "country_code": "US",
  "postal_code": "89119",
  "latitude": "36.096806",
  "longitude": "-115.173001",
  "booking_page_live_rates": "https://www.businesshotels.com/reservation.php?hotel-id=...",
  "rates": {
    "display_all_in_total": "356.06",
    "currency": "USD",
    "price_info": "Price includes all tax and fees",
    "ppn_bundle": "HEA_OqStb8TUtNnSS-nry..."
  },
  "best_match_score": 0.87
}

🏨 BusinessHotels Universal Agentic API

🤖 Universal Agent Instructions