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": "The upstream service could not complete the request.",
  "error_code": "UPSTREAM_ERROR"
}
```

Request

```curl
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"
```

Response

```json
{
  "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": "The upstream service could not complete the request.",
  "error_code": "UPSTREAM_ERROR"
}
```