Basics Main guide

What is hotel mapping? How it works: a complete guide

Hotel mapping is the process of merging the different names, codes, addresses and coordinates that different suppliers send for the same hotel into a single permanent ID. Records are normalized, compared against nearby candidates and given a score between 0 and 1: a high score is matched automatically, a borderline record goes to human review, and a low score creates a new hotel.

Author
hotelmapping.org Editorial Team
Last updated:
14 min read

When an agency works with a single supplier, the hotel list is simple: whatever the supplier sends gets listed. Once a second and third supplier are added, the same hotel comes back under different names, different codes and coordinates a few dozen meters apart. Hotel mapping is the work of detecting that these records belong to the same physical property and grouping them under a single ID. This guide explains why mapping is necessary, how a mapping engine works step by step, how quality is measured and what approaches exist in the market.

What does hotel mapping mean in short?

Hotel mapping links each supplier’s hotel code in its own system (supplier code) to a shared ID. hotelmapping.org calls this shared ID the HM ID; for example, HM-1048213. The agency merges search results, prices and content through this ID. As a result, each hotel appears in the list only once, and offers from different suppliers are compared on the same card.

The input to mapping is what is called static hotel data: hotel name, address, coordinates, phone, website, star rating, chain and photos. Dynamic data such as prices and availability does not enter mapping; it is merged through this ID after mapping is done. You can find the difference between static and dynamic data in detail in the hotel XML integration guide.

Why does the same hotel look different?

A multi-supplier agency works with several bedbanks, booking platforms and sometimes direct hotel connections at the same time. Each supplier collects hotel information from its own source, under its own rules. Some get data from the hotel’s sales team, some from the channel manager, some from another wholesaler. The result is a picture like this for the same property:

Field Supplier A Supplier B Supplier C
Hotel name Sunset Bay Resort & Spa SUNSET BAY RESORT SPA Sunset Bay Rsrt. & Spa - Adults
Hotel code HTL-88213 40917 TR-ANT-551
City Belek Serik Antalya
Coordinates 36.8541, 31.0552 36.8543, 31.0549 36.8539, 31.0556
Website www.sunsetbay-example.com sunsetbay-example.com/tr —

The data in the table is an example; the hotel name, codes and addresses do not belong to a real property.

The main sources of the differences are:

  • Spelling and abbreviation: “Rsrt.” instead of “Resort & Spa”, all capitals, missing punctuation, a “Hotel” or “Otel” suffix.
  • Language and script: Russian or Arabic names are converted to the Latin alphabet under different rules (transliteration).
  • Destination level: One supplier writes the resort area (Belek), another the district (Serik), a third the province (Antalya).
  • Coordinates: Some suppliers give the hotel entrance, some the center of the building, some a point generated automatically from the address (geocoding).
  • Extra information: Suffixes such as “Adults Only” or “Family Club” sometimes describe a separate property, sometimes a section of the same property, and sometimes only a sales concept.

The last point is the hardest part of mapping: two very similar records are sometimes really two separate hotels. The same chain can have two hotels on the same site. That is why simple rules that look only at the name are not enough.

What happens without mapping?

In unmapped inventory, the same hotel appears two, three or four times in the list. The customer cannot tell which card is correct, the best offer cannot be consolidated on a single card, and price comparison breaks down. Behind the scenes, the team spends time matching new records by hand. A wrong room or board match turns into cancellations and complaints. We walk through how to calculate this cost step by step in the cost of duplicate hotel listings.

How does a mapping engine work? 9 steps

Most current mapping systems combine rules, machine learning and human review. The steps below describe how the hotelmapping.org hotel mapping engine operates. Other systems in the industry go through similar stages; details and weights vary.

1. Ingestion

The supplier’s static data is ingested via API, CSV or FTP. Each record is stored in its raw form and every change is versioned. This way, when a hotel’s name or coordinates change, what changed and when can be traced back.

2. Normalization

Before comparison, data is brought into the same format. Suffixes such as “Hotel”, “Otel” and “Resort & Spa” are separated from the hotel name and stored in a separate field. Russian and Arabic names are converted to the Latin alphabet. The address is split into street, district, province and postal code. The phone number is converted to international format, and the website is reduced to the domain only: https://www.sunsetbay-example.com/en/ becomes sunsetbay-example.com. This step keeps later comparisons from tripping over spelling differences.

3. Candidate generation

Comparing each record with every hotel in the world is both slow and unnecessary. The engine selects only plausible candidates: hotels in the same geographic cell (about 500 meters), hotels with similar names, and records that share the same phone number or domain. This step greatly reduces the number of comparisons and ensures the scoring step deals only with meaningful pairs.

4. Scoring

For each candidate pair, many signals are calculated:

  • name similarity (at character and word level),
  • multilingual text embedding similarity (to catch the same name written in a different language),
  • the distance between the two coordinates,
  • phone, website and email matches,
  • star rating, chain and postal code agreement.

A classifier model combines these signals and produces a probability between 0 and 1. This value is called the match score. The score shows how confident the model is about the question “are these two records the same hotel?” No single signal decides on its own: two records with identical names but 3 kilometers apart can get a low score; two records with differently written names but the same phone and domain can get a high score.

5. Decision

The score is divided into three zones. Thresholds are not fixed; they are tuned against results on a manually labeled test set.

Score Decision What happens?
0.97 and above Automatic match (auto_match) The record is linked to the existing HM ID
Between 0.80 and 0.97 Human review (review) The record goes to the specialist queue
Below 0.80 New hotel (new_id) A new HM ID is created for the record

This table describes the bulk ingestion flow. The Find Match API, which queries a single record, does not create a new ID below 0.80; it returns a no_match decision and the hm_id field comes back empty (null).

6. Human review

Records in the borderline zone go to a data review specialist. The review screen shows the two records side by side with a map, photos and field differences. The specialist decides “same hotel” or “different hotel” and sets aside records they are not sure about for further research. Every decision is added to the model as new training data. Over time the model produces more accurate scores on similar cases, and the share of records falling into the queue shrinks.

7. Clustering and conflict checks

Individual matches are merged in a graph structure: if record A is matched to B and B to C, all three are gathered in the same cluster. A consistency rule applies here. If two different codes from the same supplier land on the same hotel, this record is not automatically accepted and goes to the conflict queue. This indicates either that the supplier has a duplicate record in its own system or that two separate properties were merged by mistake.

8. Lifecycle

Hotels close, change hands, merge or split in two. The value of a permanent ID comes from not breaking through these changes. An HM ID is never reassigned to another hotel. When a hotel closes, its status (status) becomes closed; when two records merge, the old ID’s status becomes merged and the merged_into field points to the new ID. This way, an old ID stored in the agency’s system still reaches the right hotel.

9. Delivery

Results can be queried instantly via the REST API; they can also be downloaded as daily full and delta dumps in CSV, JSON or Parquet format. Webhooks for change notifications are planned. To query a single supplier code or search for candidates by name and coordinates, use the mapping API; the list of endpoints is on the developers page.

Example: from three raw records to a single ID

After the three supplier records in the table above pass through the engine, the standard output looks like this:

{
  "hm_id": "HM-1048213",
  "name": "Sunset Bay Resort & Spa",
  "destination_id": "TR-07-SERIK-BELEK",
  "geo": { "lat": 36.8541, "lng": 31.0552 },
  "website": "sunsetbay-example.com",
  "supplier_codes": [
    { "supplier": "A", "code": "HTL-88213", "confidence": null, "decision": "new_id" },
    { "supplier": "B", "code": "40917", "confidence": 0.984, "decision": "auto_match" },
    { "supplier": "C", "code": "TR-ANT-551", "confidence": 0.912, "decision": "review" }
  ],
  "external_ids": { "client": "OTL-2231" },
  "status": "active"
}

Record A arrived first and so created a new HM ID (new_id). Record B was matched automatically (auto_match) thanks to agreement on name, coordinates and domain. Record C stayed in the borderline zone (review) because of the “Adults” suffix and the city written at province level, and was linked after specialist approval. The external_ids field carries the hotel code in the agency’s own system as a cross-reference. The status field shows not the match decision but the lifecycle of the hotel record (active, closed, merged). This is sample data; the codes and scores do not belong to a real property.

Mapping does not end with the hotel ID

Even if the hotel ID is correct, the problem is not fully solved if the agency cannot compare the same room and board type across suppliers. That is why mapping usually continues with three layers.

Room mapping

“Dbl Sea View Balcony”, “Double Room SV with balcony” and “DZ Meerblick Balkon” can be the same room. The room name is split into words; each word is assigned to one of the type, class, view, bed, feature and capacity labels. First a rule dictionary containing Turkish, English, German and Russian abbreviations runs, then a labeling model. Rooms of the same hotel are grouped using these labels. Details are in what is room mapping and on the room mapping product page.

Board type mapping

A common source of errors in the Turkey and Mediterranean resort market is the board type. Spellings such as “All Inclusive”, “Her Şey Dahil”, “AI”, “Ultra All Inclusive”, “UAI” and “Soft All Inclusive” can describe the same or different services. The standard code list consists of RO, BB, HB, HB+, FB, FB+, AI, AI+, UAI and SAI (Soft AI). A synonym dictionary is maintained for each language. Spellings not in the dictionary are suggested by similarity score and added to the dictionary after human approval. The meaning of the codes is explained in the board types guide, and conversion to the standard code is explained on the board type mapping page.

Destination mapping

Suppliers code destinations at different levels. A shared hierarchy closes this gap: country → province → district → resort area. For example, the chain Turkey → Antalya → Serik → Belek is represented by the ID TR-07-SERIK-BELEK. Supplier destination codes and IATA codes are tied to this hierarchy. This way, a search for “Belek hotels” also covers hotels from suppliers that code the area at district or province level. Details are on the destination mapping page.

How is mapping quality measured?

“Accuracy rate” alone can be misleading. A sound measurement reports three metrics together:

Metric What it measures Why it matters
Accuracy (false match rate) How many of the matched pairs are truly the same hotel A false match means selling the customer the wrong hotel
Coverage How much of the supplier records are linked to an HM ID Low coverage means duplicates stay in the list
Human queue rate How much of the records fall into specialist review Determines delivery time and operating cost

These metrics affect one another. Raising the auto-match threshold reduces false matches but grows the human queue. Raising the new-hotel threshold prevents false merges but increases the risk that records that are truly the same stay separate. So instead of looking at a single figure like “99.99% accuracy”, you should ask these questions: Were all three metrics measured on the same test set? Which regions and how many pairs does the test set consist of? What happened to the records outside coverage?

hotelmapping.org plans to measure quality with a test set of at least 5,000 manually labeled hotel pairs. The set is planned to give particular weight to hotels in Antalya, Muğla, Istanbul, Dubai and Egypt. When measurement is complete, results will be published on the coverage page.

Approaches in the market

The need for hotel mapping is met in several different ways. The table below summarizes the main types of approaches you will encounter when choosing a service and what to look for in each.

Approach How it works Strength What to watch for
In-house, rule-based mapping The team writes its own rules for name, address and coordinates; fixes ambiguous records by hand. Full control, no extra license cost Maintenance burden and error rate grow as the number of suppliers grows.
Global mapping provider Offers a ready hotel ID database via API or bulk file. Wide geographic coverage, fast start Coverage and accuracy must be tested separately in your regions; room and board layers may be separate products.
Region-focused mapping service Focuses in depth on the data of specific markets, for example resort regions. Precision on local spellings, board types and destination detail Ask what coverage looks like outside the focus regions.
Hybrid approach The ID from the service is kept together with the team’s own hotel codes. Preserves existing work, eases migration Which source prevails in conflicting decisions must be set up front.

Whichever approach you choose, the accuracy and coverage figures providers highlight are usually their own claims, not an independent measurement. The real differences show up in which regions coverage is strong, in the delivery format (API, bulk file, web interface), in whether prices are public, and in whether additional layers such as room, board and destination are offered. We cover the balance between accuracy and coverage in detail in accuracy or coverage in mapping?. hotelmapping.org works with 3.5 million hotels worldwide; it offers board type and destination mapping together with hotel mapping as standard.

An important point for teams with existing mapping: we store the hotel IDs from your current mapping provider or your own system as cross-references. So moving to HM ID does not require throwing away your existing mapping.

Build your own mapping or buy a service?

For a team working with a single supplier and a small inventory, simple rules and occasional manual fixes may be enough. As the number of suppliers grows, the work grows, because mapping is not a one-time job but a continuous process. If you build your own system, you also take on:

  • normalization rules for every new supplier format,
  • a regularly updated, manually labeled test set,
  • a multilingual team to review borderline records,
  • tracking of hotels that close, merge or change codes,
  • delivery of daily updates into your systems.

Buying a service hands off this load but brings a new dependency. When deciding, ask about the data format, the permanence of IDs, the transparency of quality measurement and what happens to your data when the contract ends. The full list of these questions is in 12 questions to ask when choosing a hotel mapping API.

Where to start?

  1. Measure the current state. Work out how many hotel cards are in your list and how many unique hotels they correspond to.
  2. Collect your supplier codes in one table. Keep which supplier uses which code in one place, together with the IDs from your current mapping provider, if you have one, and your own internal codes.
  3. Hotel first, then room and board. Room and board mapping do not work reliably until the hotel ID is settled.
  4. Track quality metrics together. Follow accuracy, coverage and human queue rate on the same test set.
  5. Prepare for change. Set up an update flow that takes only changed records instead of full data; reflect closed and merged hotels in your system.

Frequently asked questions

What is the difference between hotel mapping and room mapping?

Hotel mapping determines that records from different suppliers belong to the same property and links them to a single ID. Room mapping comes next: within the same hotel, it groups the same room type that suppliers send under different names. Room mapping cannot work reliably until the hotel ID is established correctly.

Is mapping done entirely by AI?

Generally no. In the hotelmapping.org engine, normalization is rule-based and scoring is done by a machine learning model. Records in the borderline zone, where the model is not sure, go to a data review specialist. Every decision by the specialist is added to the model as new training data.

What does a match score of 0.97 mean?

The score shows, on a scale from 0 to 1, how confident the model is that two records are the same hotel. In the hotelmapping.org engine, 0.97 and above is matched automatically, 0.80 to 0.97 goes to human review, and below 0.80 creates a new HM ID. Thresholds are tuned against results on the test set.

If we already use a mapping service, do we still need hotel mapping?

If your existing mapping meets your needs, keeping it makes sense. Additional needs usually arise in the board type, room and destination layers, or for records with no shared ID. HM ID stores the hotel IDs from your current mapping provider or your own system as cross-references, so switching does not reset your mapping.

What happens when a new supplier is added?

The new supplier's static data is ingested, normalized and compared against existing HM IDs. High-scoring records are linked automatically to existing hotels, borderline ones go to the review queue, and those with no counterpart get a new ID.

hotelmapping.org Editorial Team

DIJI.TECH hotel data team

The DIJI.TECH team working on hotel mapping, supplier integration and travel software.