Developers

Connect the HM ID to your own system with a REST API, daily dumps and webhooks. The examples below show API v1, which you can try in the sandbox.

POST /v1/match
curl -X POST https://api.hotelmapping.org/v1/match \
  -H "X-API-Key: $HM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SUNSET BAY RESORT SPA",
    "address": "Belek Turizm Merkezi, Serik",
    "country": "TR",
    "lat": 36.8541,
    "lng": 31.0552
  }'

Authentication

Every request is sent over HTTPS with the X-API-Key header. Sandbox and production keys are separate.

Headers
X-API-Key: $HM_API_KEY
Content-Type: application/json
Accept-Language: tr

Endpoints

  • POST /v1/match

    Looks up a hotel by name, address and coordinates; returns the HM ID and a confidence score (Find Match API).

  • GET /v1/hotels/{hm_id}

    Returns the hotel's standard record, supplier codes and cross-referenced IDs.

  • GET /v1/suppliers/{supplier}/codes/{code}

    Resolves a supplier code to an HM ID.

  • POST /v1/rooms/map

    Breaks room names into type, class, view, bed and capacity; groups identical rooms.

  • POST /v1/boards/map

    Converts board spellings into a standard code (RO, BB, HB, FB, AI, UAI…).

  • GET /v1/destinations/{id}

    Returns the country → region → district → resort area hierarchy and supplier destination codes.

  • GET /v1/hotels/{hm_id}/content

    Returns multilingual descriptions and the factsheet.

  • GET /v1/dumps/latest

    Returns the URLs of the daily full and delta dump files (CSV, JSON, Parquet).

Sample requests and responses

POST /v1/match → 200
{
  "hm_id": "HM-1048213",
  "confidence": 0.991,
  "decision": "auto_match",
  "name": "Sunset Bay Resort & Spa",
  "destination_id": "TR-07-SERIK-BELEK",
  "external_ids": { "client": "OTL-2231" }
}
POST /v1/rooms/map
POST /v1/rooms/map
{
  "hm_id": "HM-1048213",
  "rooms": ["Dbl Sea View Balcony", "DOUBLE ROOM SEASIDE W/ BALCONY"]
}

// → 200
{
  "groups": [{
    "room_id": "HM-1048213-R03",
    "type": "room",
    "class": "standard",
    "view": "sea",
    "bed": "double",
    "features": ["balcony"],
    "max_occupancy": 3,
    "matched": ["Dbl Sea View Balcony", "DOUBLE ROOM SEASIDE W/ BALCONY"]
  }]
}
POST /v1/boards/map
POST /v1/boards/map
{ "values": ["Ultra Herşey Dahil", "UALL", "Soft All Inc.", "HB+"] }

// → 200
{
  "results": [
    { "input": "Ultra Herşey Dahil", "code": "UAI", "score": 0.99, "decision": "auto_match" },
    { "input": "UALL",               "code": "UAI", "score": 0.93, "decision": "review" },
    { "input": "Soft All Inc.",      "code": "SAI", "score": 0.98, "decision": "auto_match" },
    { "input": "HB+",                "code": "HB+", "score": 1.0,  "decision": "auto_match" }
  ]
}

Code samples are illustrative; field names may change in the v1 release.

Delivery options

  • REST API

    For real-time queries and Find Match. JSON responses, pagination and versioned endpoints.

  • Daily dump

    Full and delta files: CSV, JSON or Parquet. For bulk loading into your own database.

  • WebhookComing soon

    Notifications for closed, merged and new hotels. Planned.

14-day free sandbox

Try all endpoints with 1,000 API calls per month and sample data. No credit card required.

SDKsComing soon

.NET, PHP, Node.js and Python client libraries are in preparation. Until then, you can use plain HTTP from any language.

  • .NET
  • PHP
  • Node.js
  • Python

Rate limits

Request limits depend on your plan and are stated in your quote. For bulk jobs we recommend the dump.

Get your tailored quote

Send your request in three steps; we will email the quote to your work address. The request is non-binding.