GET
# IHG URL to Hotel ID API

Convert any ihg.com URL into the hotel mnemonic (`USMKM`, `LONHB`, etc.) you need to call the IHG Rooms API.

## Overview

The endpoint accepts a URL on `ihg.com` (or any `*.ihg.com` subdomain) and extracts the IHG hotel mnemonic. It supports both hotel-detail URLs (where the code is in the path) and booking-flow URLs (where the code is in the `qSlH` or `qHotelCode` query param).

### Endpoint URL

GET https://api.stayapi.com/v1/ihg/hotel/url-to-id 

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| url | string | Required | Any `http(s)` URL on `ihg.com` or a `*.ihg.com` subdomain. Examples: a hotel-detail URL like `https://www.ihg.com/kimptonhotels/hotels/us/en/maikhao/usmkm/hoteldetail`, or a booking-flow URL like `https://www.ihg.com/hotels/us/en/find-hotels/select-roomrate?qSlH=USMKM&...`. |

#### URL-encode the value

The `url` parameter must be URL-encoded when included in the query string. Most HTTP clients handle this automatically when you pass it as a params/query object rather than concatenating strings.

## Response Format

### Success (200 OK)

| Field | Type | Description |
| --- | --- | --- |
| success | boolean | Always `true` on a 2xx response. |
| url | string | The input URL, normalized: query string and fragment stripped, host lowercased. |
| hotel\_code | string | The extracted IHG hotel mnemonic, uppercased. Pass this directly to `/v1/ihg/rooms?hotel_code=...`. |

### Example response

```
{
  "success": true,
  "url": "https://www.ihg.com/kimptonhotels/hotels/us/en/maikhao/usmkm/hoteldetail",
  "hotel_code": "USMKM"
}
```

## Extraction sources

The extractor checks four locations in priority order and returns the first match. Both hotel-detail URLs and booking-flow URLs are supported because IHG places the mnemonic in different positions depending on the page.

| Priority | Source | Example |
| --- | --- | --- |
| 1 | qHotelCode | `?qHotelCode=USMKM` |
| 2 | qSlH | `?qSlH=USMKM` (booking-flow URLs) |
| 3 | Path segment | `.../usmkm/hoteldetail` (also `dining`, `rooms`, `amenities`, etc.) |
| 4 | qDest | Best-effort fallback. Accepted only when alphanumeric — free-text destinations like `qDest=Phuket, Thailand` are rejected. |

## Common Use Cases

### URL-to-rates pipeline

Customers paste an IHG URL into your app; you call this endpoint, then call `/v1/ihg/rooms` with the extracted code.

Two-step lookup

### Normalize affiliate links

Strip tracking params from IHG URLs and surface a canonical hotel reference in your database.

Clean URL + hotel ID

## Error Responses

All endpoint-level errors follow [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) with content type `application/problem+json`. Each carries `provider: "ihg"`, `product: "url-to-id"`, and a unique `correlation_id` for support requests.

### 400 Bad Request — invalid URL

The URL isn't on `ihg.com` / `*.ihg.com`, the scheme isn't `http(s)`, or the URL is malformed.

```
{
  "type": "https://api.stayapi.com/errors/invalid-url",
  "title": "Invalid URL",
  "status": 400,
  "detail": "URL must be an http(s) URL on ihg.com or a *.ihg.com subdomain",
  "instance": "/v1/ihg/hotel/url-to-id",
  "provider": "ihg",
  "product": "url-to-id",
  "error_code": "INVALID_URL",
  "provided_url": "https://www.booking.com/hotel/us/foo.html",
  "correlation_id": "..."
}
```

### 400 Bad Request — hotel code not found

The URL is on `ihg.com`, but no mnemonic could be extracted from any of the four sources (path, `qHotelCode`, `qSlH`, `qDest`).

```
{
  "type": "https://api.stayapi.com/errors/hotel-code-not-found",
  "title": "Hotel Code Not Found",
  "status": 400,
  "detail": "Could not extract an IHG hotel mnemonic from the URL",
  "instance": "/v1/ihg/hotel/url-to-id",
  "provider": "ihg",
  "product": "url-to-id",
  "error_code": "HOTEL_CODE_NOT_FOUND",
  "provided_url": "https://www.ihg.com/",
  "correlation_id": "..."
}
```

Request

```curl
curl -G "https://api.stayapi.com/v1/ihg/hotel/url-to-id" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "url=https://www.ihg.com/kimptonhotels/hotels/us/en/maikhao/usmkm/hoteldetail"
```

Response

```json
{
  "success": true,
  "url": "https://www.ihg.com/kimptonhotels/hotels/us/en/maikhao/usmkm/hoteldetail",
  "hotel_code": "USMKM"
}
```

```
{
  "type": "https://api.stayapi.com/errors/invalid-url",
  "title": "Invalid URL",
  "status": 400,
  "detail": "URL must be an http(s) URL on ihg.com or a *.ihg.com subdomain",
  "instance": "/v1/ihg/hotel/url-to-id",
  "provider": "ihg",
  "product": "url-to-id",
  "error_code": "INVALID_URL",
  "provided_url": "https://www.booking.com/hotel/us/foo.html",
  "correlation_id": "..."
}
```

```
{
  "type": "https://api.stayapi.com/errors/hotel-code-not-found",
  "title": "Hotel Code Not Found",
  "status": 400,
  "detail": "Could not extract an IHG hotel mnemonic from the URL",
  "instance": "/v1/ihg/hotel/url-to-id",
  "provider": "ihg",
  "product": "url-to-id",
  "error_code": "HOTEL_CODE_NOT_FOUND",
  "provided_url": "https://www.ihg.com/",
  "correlation_id": "..."
}
```