UBIO Hotel Universe API

# Tools Reference: Search & Hotels

These six tools are available to all accounts with hotels:view permission.

# search_hotels

Search for hotels matching a set of structured filters. Returns hotel previews with pagination.

All filter parameters are optional — omitting them returns all accessible hotels.

# Parameters

Parameter Type Description
name string Hotel name (partial match)
country string[] ISO 3166-1 alpha-2 codes, e.g. ["GB","FR"]
city string[] City names (OR-combined)
state string[] State or province names
postalCode string[] Postal or ZIP codes
stars integer[] Star ratings 0–5 (0 = unrated)
features string[] Amenity keywords, e.g. ["pool","spa"]
propertyType string[] Property type codes, e.g. ["hotel","resort","hostel"]
brand string[] Brand names, e.g. ["Marriott","Hilton"]
minRating number Minimum user rating (0–5)
minReviews integer Minimum review count
languagesSpoken string[] ISO 639-1 language codes, e.g. ["en","fr"]
minRooms integer Minimum room count
maxRooms integer Maximum room count
hotelIdType string ID system: huId, GoogleHotels, Booking, etc.
hotelId string[] Specific hotel IDs (up to 50)
hotelIdFilterMode string "include" (default) or "exclude"
hasLocation boolean Only hotels with location data
hasFeatures boolean Only hotels with features/amenities
hasRating boolean Only hotels with a user rating
hasReviews boolean Only hotels with reviews
hasImages boolean Only hotels with images
hasRooms boolean Only hotels with room data
lat number Latitude (-90–90). Requires lon and radius.
lon number Longitude (-180–180). Requires lat and radius.
radius number Search radius in metres (1–10,000,000). Requires lat and lon.
geometry string geometryRef from geocode_location — constrains results to a polygon
geometryMultiplier number Scale factor for the polygon area. Requires geometry.
pageToken string Pagination cursor from a previous response's nextPageToken

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_hotels",
      "arguments": {
        "country": ["ES"],
        "city": ["Barcelona"],
        "stars": [4, 5],
        "features": ["pool"]
      }
    }
  }'

# Response

{
  "total": 47,
  "nextPageToken": "eyJvZmZzZXQiOjIwfQ",
  "hotels": [
    {
      "huId": "HU4A2BC9",
      "name": "Hotel Arts Barcelona",
      "address": "Carrer de la Marina, 19-21, Barcelona",
      "stars": 5,
      "lat": 41.3874,
      "lon": 2.1965
    }
  ]
}

nextPageToken is null when there are no more results. Pass it as pageToken in the next call to retrieve the following page.

# search_hotels_nearby

Find hotels within a radius of a geographic point, sorted nearest first. Returns lightweight previews: huId, name, address, lat, lon.

# Parameters

Parameter Type Required Description
lat number Yes Latitude (-90–90)
lon number Yes Longitude (-180–180)
radius number Yes Search radius in metres
limit integer (1–200) No Max results (default 50)

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_hotels_nearby",
      "arguments": {
        "lat": 51.5074,
        "lon": -0.1278,
        "radius": 500,
        "limit": 10
      }
    }
  }'

# Response

{
  "hotels": [
    {
      "huId": "HU7C3DE1",
      "name": "The Trafalgar St. James",
      "address": "2 Spring Gardens, London",
      "lat": 51.5073,
      "lon": -0.1285
    }
  ]
}

# search_hotels_natural_language

Search hotels using a free-form description. The server extracts structured filters via an LLM and returns them alongside hotel previews — useful for refining a follow-up search_hotels call.

# Parameters

Parameter Type Required Description
query string (1–1000 chars) Yes Free-form description of the hotels you are looking for
pageToken string No Pagination cursor from a previous response's nextPageToken

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_hotels_natural_language",
      "arguments": {
        "query": "4-star resorts in Sicily with a pool"
      }
    }
  }'

# Response

{
  "filters": {
    "stars": [4],
    "features": ["pool"],
    "country": ["IT"],
    "propertyType": ["resort"]
  },
  "total": 12,
  "nextPageToken": null,
  "hotels": [...]
}

The filters object shows what the LLM extracted from your query. Inspect it to verify intent and use those fields directly in a search_hotels call for subsequent pages.

# get_hotel

Get the full canonical profile for a single hotel by its Hotel Universe ID.

Trial tier limit

Trial accounts can access at most 100 unique hotels. Calls beyond this limit return an error with a prompt to upgrade.

# Parameters

Parameter Type Required Description
huId string Yes Hotel Universe ID (e.g. "HU4A2BC9")

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_hotel",
      "arguments": {
        "huId": "HU4A2BC9"
      }
    }
  }'

The response includes the full hotel profile: name, address, location, stars, amenities, room types, images, ratings, and all cross-reference IDs (Booking.com, Google Hotels, etc.).

# get_hotel_reviews

Fetch guest reviews for a hotel.

Full tier only

get_hotel_reviews is not available on Trial tier accounts. Attempting to call it returns an error. Upgrade at hello@ubio.ai to enable access.

Requires permission: reviews:view

# Parameters

Parameter Type Required Description
huId string Yes Hotel Universe ID
limit integer (1–100) No Maximum reviews to return (default 20)
offset integer No Reviews to skip from the start (default 0)

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_hotel_reviews",
      "arguments": {
        "huId": "HU4A2BC9",
        "limit": 5,
        "offset": 0
      }
    }
  }'

# Response

{
  "total": 842,
  "offset": 0,
  "limit": 5,
  "returned": 5,
  "reviews": [
    {
      "title": "Outstanding location",
      "text": "Perfect stay, right in the centre of everything.",
      "rating": 9.2,
      "date": "2025-09-14"
    }
  ]
}

# geocode_location

Resolve a free-text location string into coordinates and polygon boundaries. Use the returned geometryRef as the geometry parameter in search_hotels to constrain results to that polygon.

# Parameters

Parameter Type Required Description
query string Yes Free-text location (e.g. "Shoreditch, London")

# Example

curl -X POST https://api.hotel-universe.travel/mcp \
  -H "Authorization: Bearer pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "geocode_location",
      "arguments": {
        "query": "Notting Hill, London"
      }
    }
  }'

# Response

[
  {
    "place_id": 282408217,
    "geometryRef": "Notting Hill, London-282408217",
    "lat": 51.5090,
    "lon": -0.2010,
    "displayName": "Notting Hill, Royal Borough of Kensington and Chelsea, London, England",
    "addressType": "suburb",
    "polygon": {
      "type": "Polygon",
      "coordinates": [[[-0.215, 51.502], [-0.195, 51.502], [-0.195, 51.516], [-0.215, 51.516], [-0.215, 51.502]]]
    }
  }
]

Multiple results may be returned when the query is ambiguous. Pick the most relevant entry by displayName.

# Geocode then search workflow

Step 1 — geocode_location({ query: "Notting Hill, London" })
         → geometryRef: "Notting Hill, London-282408217"

Step 2 — search_hotels({ geometry: "Notting Hill, London-282408217", stars: [4, 5] })
         → hotels within the Notting Hill polygon

Use geometryMultiplier in search_hotels to expand the polygon area if results are too few (e.g. geometryMultiplier: 1.5 expands by 50%).

← Tools Reference: List Management →