🏨 BusinessHotels Universal Agentic API

MCP (Model Context Protocol) 1.0 UCP (Universal Control Protocol) READY RESTful

Optimized for Model Context Protocol (MCP) & 2M+ Property Inventory

● API Online
Production v1.3.9

🤖 Universal Agent Instructions

Execute POST for travel intent. Crucial Requirement: To ensure a unique property match, you must pass the hotelName as a descriptive string including "Hotel Name, City, State (if applicable), Country Code". If the user does not provide city or country, infer them from context when possible; otherwise ask a brief clarifying question before calling this tool.

💡 Precision-Matching Tip: Always include the City and Country.
✅ Good: "Luxor Las Vegas, Las Vegas, US"
❌ Bad: "Luxor"

📡 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

MCP tools discovery (tools/list):
GET https://www.businesshotels.com/mcp-server.php?route=tools
Returns the MCP envelope with protocol, version, and tools.

💡 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 (LLM Function Calling)

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

Tool Definition (function-calling)
{
  "name": "get_live_hotel_rates",
  "description": "Use this tool whenever the user asks for live price, total cost with taxes and fees, availability, or a booking/checkout link for a specific hotel for given dates. It returns an all-in final price (including taxes) and a direct, price-locked booking URL for that property.",
  "parameters": {
    "type": "object",
    "properties": {
      "hotelName": {
        "type": "string",
        "description": "REQUIRED. Detailed hotel name plus City and Country. Example: 'InterContinental Mark Hopkins, San Francisco, US'. Providing city and 2-letter country code maximizes match accuracy. If the user does not specify city or country, infer them from context when possible; otherwise ask the user a brief clarifying question before calling this tool."
      },
      "checkinDate": {
        "type": "string",
        "format": "date",
        "description": "Check-in date in YYYY-MM-DD format. Convert any relative dates (e.g. 'next Friday', 'tomorrow') into this format before calling."
      },
      "checkoutDate": {
        "type": "string",
        "format": "date",
        "description": "Check-out date in YYYY-MM-DD format. Must be after check-in. Convert relative dates into this format before calling."
      },
      "adults": {
        "type": "integer",
        "default": 1,
        "description": "Number of adult guests (1–4). If the user does not specify, assume 2 adults for standard business/leisure stays."
      },
      "currency": {
        "type": "string",
        "default": "USD",
        "description": "3-letter ISO currency code (USD, EUR, GBP, etc.). Use the user's preferred or local currency when known; otherwise default to USD."
      }
    },
    "required": ["hotelName", "checkinDate", "checkoutDate"],
    "additionalProperties": false
  }
}

🧩 MCP Tools Discovery Response

Use this JSON as your MCP server’s tools/list response (?route=tools) so clients can register the tool via input_schema.

MCP tools/list result
{
  "protocol": "mcp",
  "version": "1.0",
  "server_name": "BusinessHotels MCP Server",
  "tools": [
    {
      "name": "get_live_hotel_rates",
      "title": "BusinessHotels Live Hotel Rates",
      "description": "Use this tool whenever a user asks for live price, total cost (including taxes and fees), availability, or a booking/checkout link for a specific named hotel and dates. It returns an all-in final price and a direct booking URL with a price-locked ppn_bundle for that property.",
      "input_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "hotelName": {
            "type": "string",
            "description": "REQUIRED. Detailed hotel name plus City and Country. Example: 'InterContinental Mark Hopkins, San Francisco, US'. If the user omits city or country, infer them from context or ask a brief clarification before calling."
          },
          "checkinDate": {
            "type": "string",
            "format": "date",
            "description": "Check-in date in YYYY-MM-DD format. Convert relative dates like 'next Friday' into this format before calling."
          },
          "checkoutDate": {
            "type": "string",
            "format": "date",
            "description": "Check-out date in YYYY-MM-DD format. Must be after check-in. Convert relative dates into this format before calling."
          },
          "adults": {
            "type": "integer",
            "default": 1,
            "description": "Number of adult guests (1–4). If unspecified, default to 2 adults."
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "3-letter ISO currency code (USD, EUR, GBP, etc.). Prefer the user's local or requested currency when known."
          },
          "api_key": {
            "type": "string",
            "description": "Optional API key; can also be sent via X-API-KEY header."
          }
        },
        "required": ["hotelName", "checkinDate", "checkoutDate"],
        "additionalProperties": false
      }
    }
  ]
}

📖 Intelligent Response Mapping

Response Key Agent Instruction / Logical Mapping
hotel_name Confirm this identity with the user when helpful, especially for ambiguous queries or lower match scores.
hotel_address Display for logistical clarity (Street, City, Zip) to help the user confirm it is the correct property.
latitude / longitude Map Trigger: Use for map pins, distance calculations, or neighborhood descriptions.
display_all_in_total Display as the single, all-inclusive “Final Price” for the entire stay, including all taxes and mandatory fees.
booking_page_live_rates Present as the primary checkout action (e.g., “Book Now” button or link).
ppn_bundle Internal inventory token. Locked for ~20 minutes; do not modify. It is already embedded in the booking URL.
best_match_score If score < 0.85, clarify hotel identity with the user before treating this as a confirmed match.

📖 Response Data Model

Field Type Agent Action
hotel_id String (9-digit) Store for session persistence or follow-up questions about the same property.
display_all_in_total Float Quote as the Final Price (includes all taxes and mandatory fees) for the full stay.
booking_page_live_rates URL Present as a direct booking button/link for the user to complete the reservation.

🧠 Match Verification Logic

⚠️ Critical Error Handling

If the API returns a 400 Validation Error, verify that hotelName, checkinDate, and checkoutDate are present and properly formatted. The system always requires a hotelName string, even if a hotel_id is known internally.

💡 Agent Reasoning Tip: When the API returns a booking_page_live_rates URL, the ppn_bundle is already embedded. Tell the user their rate is locked for a short time window and provide the link as a clear “Book Now” action.

🛠️ Quick Integration Steps

  1. Authentication: Pass your key via api_key in the JSON body or X-API-KEY in the header.
  2. Date Formatting: Convert relative dates (e.g., “next Friday”) into YYYY-MM-DD strings before calling.
  3. Rich Data: Use latitude and longitude to display maps, distances, or nearby POIs.
  4. Booking Handoff: Always use the booking_page_live_rates URL; it contains the ppn_bundle which locks the rate for approximately 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.

📦 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
}