GET

Hotel Match API

Match hotel names from your database to their canonical URLs on major OTA platforms. Perfect for normalizing hotel data across different systems.

Overview

Primary Use Case

Ideal for matching hotels in your database to their exact OTA pages when hotel names may vary (e.g., "Sheraton NYC" vs "Sheraton New York Times Square Hotel").

The Hotel Match endpoint uses intelligent search to find the exact OTA page for a hotel you have in your database. It validates that the result is actually a hotel page on the specified platform, returning null if no confident match is found.

Endpoint URL

GET https://api.stayapi.com/v1/meta/match

Parameters

Parameter	Type	Required	Description
name	string	Required	The hotel name from your database to match. Can include location for better accuracy.
platform	string	Required	Target OTA platform. One of: `booking`, `agoda`, `tripadvisor`, `expedia`, `priceline`, `tripcom`

Pro Tip

Include location in the name parameter for better matching accuracy. For example: "Sheraton New York Times Square" instead of just "Sheraton NYC".

Supported Platforms

booking

Booking.com hotel pages

Pattern: booking.com/hotel/{cc}/{slug}.html

agoda

Agoda hotel pages

Pattern: agoda.com/{slug}/hotel/{city}-{cc}.html

tripadvisor

TripAdvisor hotel review pages

Pattern: tripadvisor.com/Hotel_Review-{id}-...

expedia

Expedia hotel information pages

Pattern: expedia.com/{city}-Hotels-{name}.h{id}.Hotel-Information

priceline

Priceline hotel deal pages

Pattern: priceline.com/hotel-deals/.../H{id}/...

tripcom

Trip.com hotel detail pages

Pattern: trip.com/hotels/{city}-hotel-detail-{id}/...

Response Format

Success Response (200 OK)

Field	Type	Description
success	boolean	Always `true` for successful requests
query.name	string	The hotel name used for matching
query.platform	string	The platform used for matching
match	object \| null	Matched hotel data, or `null` if no confident match found
match.title	string	Hotel title from the OTA platform
match.description	string	Meta description snippet from the search result
match.url	string	Canonical URL on the OTA platform
message	string \| null	Optional status message (e.g., reason for null match)

Common Use Cases

Hotel Data Normalization

Match hotels from your database to their canonical OTA URLs when names may vary across systems.

Standardize your hotel inventory

Multi-Platform Linking

Build a mapping table of hotel URLs across different OTA platforms for your hotel database.

Connect hotels across platforms

Affiliate Link Generation

Generate verified OTA URLs for hotels to use in affiliate marketing campaigns.

Monetize your hotel content

Data Enrichment

Enrich your hotel records with verified URLs from major booking platforms.

Complete your hotel data

Error Responses

400 Bad Request

Missing required parameters or invalid platform value.

{
  "detail": [
    {
      "loc": ["query", "platform"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}

404 No Match Found

No matching hotel page found on the specified platform.

{
  "type": "https://api.stayapi.com/errors/not-found",
  "title": "No Match Found",
  "status": 404,
  "detail": "No matching hotel page found on Booking.com",
  "error_code": "NO_MATCH",
  "name": "Some Unknown Hotel ABC",
  "platform": "booking"
}

Error codes: NO_RESULTS (no search results) or NO_MATCH (results found but URL pattern didn't match).

502 Upstream Error

Search service temporarily unavailable.

{
  "type": "https://api.stayapi.com/errors/upstream-error",
  "title": "Upstream Error",
  "status": 502,
  "detail": "Search API error: 429",
  "error_code": "UPSTREAM_ERROR"
}

Request

curl -X GET "https://api.stayapi.com/v1/meta/match?name=Sheraton%20New%20York%20Times%20Square&platform=booking" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch("https://api.stayapi.com/v1/meta/match?" +
  new URLSearchParams({
    name: "Sheraton New York Times Square",
    platform: "booking"
  }), {
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

const data = await response.json();

if (response.ok) {
  console.log(`Matched: ${data.match.title}`);
  console.log(`URL: ${data.match.url}`);
} else if (response.status === 404) {
  console.log(`No match: ${data.error_code} - ${data.detail}`);
} else {
  console.log(`Error: ${data.detail}`);
}

import requests

url = "https://api.stayapi.com/v1/meta/match"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "name": "Sheraton New York Times Square",
    "platform": "booking"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

if response.status_code == 200:
    print(f"Matched: {data[\"match\"][\"title\"]}")
    print(f"URL: {data[\"match\"][\"url\"]}")
elif response.status_code == 404:
    print(f"No match: {data[\"error_code\"]} - {data[\"detail\"]}")
else:
    print(f"Error: {data.get(\"detail\")}")

<?php
$url = "https://api.stayapi.com/v1/meta/match";
$params = http_build_query([
    "name" => "Sheraton New York Times Square",
    "platform" => "booking"
]);

$headers = [
    "x-api-key: YOUR_API_KEY",
    "Content-Type: application/json"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "?" . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($response, true);
curl_close($ch);

if ($http_code === 200) {
    echo "Matched: " . $data["match"]["title"] . "\n";
    echo "URL: " . $data["match"]["url"] . "\n";
} elseif ($http_code === 404) {
    echo "No match: " . $data["error_code"] . " - " . $data["detail"] . "\n";
} else {
    echo "Error: " . $data["detail"] . "\n";
}
?>

require "net/http"
require "uri"
require "json"

uri = URI("https://api.stayapi.com/v1/meta/match")
uri.query = URI.encode_www_form({
  name: "Sheraton New York Times Square",
  platform: "booking"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["x-api-key"] = "YOUR_API_KEY"
request["Content-Type"] = "application/json"

response = http.request(request)
data = JSON.parse(response.body)

case response.code
when "200"
  puts "Matched: #{data[\"match\"][\"title\"]}"
  puts "URL: #{data[\"match\"][\"url\"]}"
when "404"
  puts "No match: #{data[\"error_code\"]} - #{data[\"detail\"]}"
else
  puts "Error: #{data[\"detail\"]}"
end

Response

{
  "success": true,
  "query": {
    "name": "Sheraton New York Times Square",
    "platform": "booking"
  },
  "match": {
    "title": "Sheraton New York Times Square Hotel",
    "description": "Featuring an extensive health center and a ticket service for popular New York shows, Sheraton New York Times Square Hotel is 180 feet from the 7th Avenue.",
    "url": "https://www.booking.com/hotel/us/sheraton-new-york-towers.html"
  },
  "message": null
}

{
  "type": "https://api.stayapi.com/errors/not-found",
  "title": "No Match Found",
  "status": 404,
  "detail": "No matching hotel page found on Booking.com",
  "error_code": "NO_MATCH",
  "name": "Some Unknown Hotel ABC",
  "platform": "booking"
}

{
  "type": "https://api.stayapi.com/errors/upstream-error",
  "title": "Upstream Error",
  "status": 502,
  "detail": "Search API error: 429",
  "error_code": "UPSTREAM_ERROR"
}