# 12 questions to ask when choosing a hotel mapping API

> URL: https://hotelmapping.org/en/guide/12-questions-hotel-mapping-api/ · Language: English · Last updated: 2026-11-15

**When choosing a hotel mapping API, ask how accuracy is measured, whether coverage applies to your regions, how uncertain matches are handled, how permanent the IDs are, room and board type support, delivery methods, the error-correction process and exit terms. Verify each answer with a trial on your own supplier data.**

## How to use this list

Most hotel mapping providers promise high accuracy, broad coverage and easy integration. When the promises look alike, the choice easily boils down to price and demo impressions. Yet the differences are in the details: how accuracy is measured, what happens to uncertain records, how an ID behaves when a hotel closes, whether room and board type are included in coverage.

The 12 questions below group the topics to ask about when evaluating a hotel mapping API under five headings. For each question we wrote **why it matters** and **how to verify the answer**. The list is neutral; it can be applied in the same way to every provider, including hotelmapping.org.

If you are new to the subject, we recommend reading the [what is hotel mapping](https://hotelmapping.org/en/guide/what-is-hotel-mapping/) guide first. We described the static and dynamic sides of supplier connections in the [hotel XML integration](https://hotelmapping.org/en/guide/what-is-hotel-xml-integration/) article.

## Data quality

### 1. How is accuracy measured, and what is the wrong-match rate?

**Why it matters:** A wrong match is often more expensive than a missed one. If two different hotels merge into one record, a customer may book the wrong hotel; that means cancellation, complaints and extra cost. The word "accuracy" may not mean the same thing at every provider: the rate may be computed only over automatic matches, or including records that went through human review.

**How to verify:** Ask which test set the measurement was done on: how many hotel pairs, from which regions, labeled by whom, and when was it last measured? Ask for the wrong-match rate (false positive) and the missed-match rate (false negative) separately. Then send a sample from your own supplier data and check the results manually with your team.

### 2. Which regions and suppliers does the coverage rate apply to?

**Why it matters:** A global coverage rate may not show the situation in the regions you sell. Mediterranean resort regions are a hard area, with many properties sharing the same name and close locations. Coverage also depends on whether the provider already processes your suppliers' data.

**How to verify:** Provide the list of suppliers you work with and ask for a separate coverage rate for each. For the destinations you sell the most (e.g. Antalya, Muğla, Istanbul), ask for results by region. Ask whether the coverage rate is computed over total records or over active, sellable records.

### 3. How are uncertain matches handled?

**Why it matters:** Most mapping systems produce a [match score](https://hotelmapping.org/en/glossary/match-score/) and use threshold values. What is done with records whose score is not definitive directly determines quality: are they matched automatically anyway, does an expert review them, or is a new record opened?

**How to verify:** Ask for the threshold values and what happens in each range. Ask for the share of records that fall to human review and the average decision time. Check whether the score is returned to you in the API response; if it is, you can apply a stricter threshold on your side.

## Identity and lifecycle

### 4. Is the ID permanent; what happens to closed, merged and split hotels?

**Why it matters:** The mapping ID is written into your booking history, content tables and reports. If an ID is reissued to a different hotel or silently deleted, your historical data breaks.

**How to verify:** Ask in writing whether an ID is ever reissued to a different hotel. Ask for a sample response showing whether the old ID is redirected to the new one when two hotels merge and how this appears in the API (e.g. a `status` or `merged_into` field). Check whether closed hotels are marked as inactive.

### 5. Can they carry over your existing IDs and codes?

**Why it matters:** Most teams do not start from scratch. You may have your own hotel codes or the IDs of a mapping service you used before. If the new provider cannot store them as cross-references, the switching cost rises.

**How to verify:** Send a sample from your existing mapping table and check whether the old IDs come back along with the new IDs. In case of conflict (when your table and the provider's result differ), ask which one takes precedence and whether these differences are reported to you.

### 6. How are supplier code changes communicated?

**Why it matters:** Suppliers delete codes, issue new ones, and relist a hotel under a different code. If these changes do not reach you, your mapping table silently goes stale and missing hotels or [duplicate records](https://hotelmapping.org/en/glossary/deduplication/) appear in search.

**How to verify:** Ask through which channel changes are communicated: [delta dump](https://hotelmapping.org/en/glossary/delta-dump/), webhook or a change-history endpoint. Check whether deleted and merged records appear explicitly in the delta. Ask for a sample delta file from the last month.

## Depth of coverage

### 7. Is there room mapping and how does it work?

**Why it matters:** Hotel mapping alone is not enough for price comparison. If "DBL SV", "Double Room Sea View" and "Deniz Manzaralı Çift Kişilik Oda" are the same room, they need to be linked to a single ID too. Otherwise the same room appears several times on the same hotel card.

**How to verify:** Ask whether room mapping is a separate product or included in hotel mapping. Find out whether it works instantly (per call) or in bulk. Send hard room names from your own data (abbreviated, multilingual, family rooms, connecting rooms) and look at the results. For details, see our [room mapping](https://hotelmapping.org/en/products/room-mapping-solutions/) page.

### 8. Are board type and destination mapping supported?

**Why it matters:** In the resort market, board type is one of the main factors determining price. If spellings like "AI", "All Inclusive", "Ultra Her Şey Dahil" and "Soft AI" are not translated to a standard code, different boards can be compared on the same price line. On the destination side, suppliers send the same region with different hierarchies (e.g. one supplier sends "Antalya", another "Belek").

**How to verify:** Ask for the list of supported standard board codes. Send the board spellings coming from your own suppliers and check which code they are translated to. For destinations, ask whether the country, province, district and resort-area levels are kept separately.

### 9. How are multilingual names and addresses processed?

**Why it matters:** The same hotel may arrive in Latin script from one supplier and in Cyrillic or Arabic script from another. Turkish characters (ç, ğ, ı, ö, ş, ü) get corrupted or dropped in some systems. These differences make name-similarity-based matching harder.

**How to verify:** Ask how transliteration and character normalization are done. Include in the sample hotels that arrive with Russian or Arabic names and records with corrupted Turkish characters. Evaluate results separately on this subgroup.

## Technical integration and operations

### 10. What are the delivery methods, limits and freshness?

**Why it matters:** The mapping result is used at search time. Going to a remote API on every search can create latency; most teams keep the results on their side as a table. That is why bulk file (dump) delivery matters as much as the API.

**How to verify:** Ask for the following details in writing:

- API endpoints and sample requests/responses
- Call limits (per minute, day, month) and what happens when they are exceeded
- Full and delta dump formats (CSV, JSON, Parquet, etc.) and publication frequency
- Webhook support
- Time to match a new supplier file
- Whether a test environment (sandbox) and the documentation are publicly available

In the test environment, run a flow close to your real workload for a few days.

### 11. What happens when a wrong match is reported?

**Why it matters:** No system is error-free. The difference is how quickly an error is corrected and whether the same error recurs. If the correction process is unclear, your team has to patch wrong records manually on its own side.

**How to verify:** Ask about the error-reporting channel (API, portal, email) and the target correction time. Find out whether a correction applies only in your account or to all customers. Check whether the contract has a service level agreement (SLA) and whether the support language suits your team. During the trial, deliberately report an error and follow the process end to end.

## Commercial terms

### 12. What are the pricing model, trial and exit terms?

**Why it matters:** Mapping services can be priced by number of suppliers, number of hotels, number of calls or product module. If the model does not fit your growth plan, cost rises unexpectedly. Also, whether you can keep using your mapping results when the contract ends determines the switching cost.

**How to verify:** Check whether the price is stated openly, which modules are included and whether there is an extra supplier fee. Ask whether a free trial or a test environment (sandbox) is available. Ask in writing in which format data can be exported at the end of the contract and about the license terms.

## The 12 questions at a glance

| # | Question | Evidence to request | Warning sign |
| --- | --- | --- | --- |
| 1 | How is accuracy measured? | Test set description, result on your own sample | A single rate with no stated method |
| 2 | What is coverage in your regions? | Rate by supplier and region | Only a global rate |
| 3 | What happens to uncertain matches? | Threshold values, human review rate | Score not returned by the API |
| 4 | Is the ID permanent? | Sample response for merges and closures | IDs that can be reused |
| 5 | Can existing IDs be carried over? | Sample output with cross-references | Loss of old codes |
| 6 | Are code changes communicated? | Sample delta file | Deleted records absent from the delta |
| 7 | Is there room mapping? | Test result with hard room names | Returning only free text |
| 8 | Are board and destination covered? | Standard code list, hierarchy example | Board type outside the scope |
| 9 | Are multilingual names handled? | Test with Cyrillic and Arabic records | Marked drop in this subgroup |
| 10 | What are delivery and limits? | Documentation, sandbox, dump sample | No bulk delivery option |
| 11 | How are errors corrected? | Reporting channel, target time, SLA | Unclear correction process |
| 12 | What are the price and exit terms? | Written price, export right | Data unusable at contract end |

## Example: what to look for in a mapping response

The API responses you receive during evaluation answer many of the questions above at a glance. Below we show, as an example for a fictional hotel, the response of hotelmapping.org API v1's `POST /v1/match`; other providers' field names may differ.

Request:

```json
{
  "reference": "res-20417",
  "name": "Kemer Pine Garden Hotel",
  "address": "Göynük Mah. Atatürk Cad. No:45, Kemer, Antalya",
  "lat": 36.6515,
  "lng": 30.5601,
  "supplier": "C",
  "supplier_code": "KPG-7781"
}
```

Response:

```json
{
  "reference": "res-20417",
  "hm_id": "HM-1061590",
  "confidence": 0.984,
  "decision": "auto_match",
  "status": "active",
  "merged_into": null,
  "destination_id": "TR-07-KEMER-GOYNUK",
  "external_ids": { "client": "OTL-2231" },
  "supplier_codes": { "A": "KPGH-1102", "C": "KPG-7781" },
  "matched_at": "2026-11-15T09:20:00Z"
}
```

This is sample data; the hotel name, address and codes do not belong to a real property. The field names follow API v1 and may change. In this response, look for the following:

- `confidence` and `decision`: Are the score and the type of decision returned? (Question 3)
- `status` and `merged_into`: Are closure and merge states visible? (Question 4)
- `external_ids`: Are your own hotel codes or your existing provider's IDs carried over? (Question 5)
- `supplier_codes`: Are the other supplier codes of the same hotel in a single record? (Question 6)
- `destination_id`: Does the destination hierarchy arrive with a standard ID? (Question 8)

Details of the Find Match API are on the [matching API](https://hotelmapping.org/en/products/find-match-api-solutions/) and [hotel mapping](https://hotelmapping.org/en/products/hotel-mapping-solutions/) pages, and the endpoint list is on the [developers](https://hotelmapping.org/en/developers/) page.

## How should you set up the trial?

To get answers to the questions from data rather than presentations, a short trial plan is enough:

1. **Prepare a sample:** Pull a list of records made up of all your suppliers, the regions you sell the most and hard cases (hotels with the same name, closely located properties, multilingual names).
2. **Determine the right answers in advance:** Match part of this list by hand with your team. This is the yardstick against which you will compare the provider's results.
3. **Send the same data to all candidates:** For the comparison to be fair, every provider should receive the same file.
4. **Measure results separately:** Produce separate numbers for wrong matches, missed matches, records falling to human review and delivery time.
5. **Test operations:** Report an error, request a delta file, try the API limits.
6. **Get the contract terms in writing:** Price, SLA and data export rights should appear clearly in the offer.

Calculating how much duplicate records cost your business helps you translate trial results into business impact. For that, see the [duplicate hotel cost](https://hotelmapping.org/en/guide/cost-of-duplicate-hotel-listings/) article.

## Ask hotelmapping.org these questions too

We did not prepare this list in favor of any one provider; we expect you to ask hotelmapping.org the same questions. Our measured accuracy and coverage values will be published on the [coverage](https://hotelmapping.org/en/coverage/) page once the test set is complete. We explained on the [quote page](https://hotelmapping.org/en/get-a-quote/) how pricing is determined by module and number of suppliers. If you are comparing multiple providers, measure results on the same data set; we described how to read accuracy and coverage figures together in [accuracy or coverage in mapping?](https://hotelmapping.org/en/guide/accuracy-or-coverage-in-hotel-mapping/).

## Frequently asked questions

### What is the difference between accuracy and coverage?

Accuracy shows how many of the matches made are actually correct. Coverage shows how many supplier records could be linked to a hotel. One can be high while the other is low; that is why you need to ask for both separately and on the same data set.

### How much data is enough for a trial?

There is no exact number. What matters is that the sample represents your real inventory: the regions you sell the most, hard cases (hotels with the same name, Cyrillic or Arabic names, properties in close proximity) and all of your suppliers should be in the sample.

### If I switch providers, will I lose my mappings?

This depends on the contract and data ownership terms. Before choosing, ask in writing in which format you can export the mapping results and whether you can keep using this data after the contract ends.

### Can we ask these questions to hotelmapping.org too?

Yes. The list was prepared neutrally and can be applied to every provider in the same way, including hotelmapping.org. A trial on your own data is the most reliable way to compare.

## Related products

- [Find Match API solutions](https://hotelmapping.org/en/products/find-match-api-solutions/)
- [Hotel mapping solutions](https://hotelmapping.org/en/products/hotel-mapping-solutions/)
- [Room mapping solutions](https://hotelmapping.org/en/products/room-mapping-solutions/)

## Related articles

- [What is hotel mapping? How it works: a complete guide](https://hotelmapping.org/en/guide/what-is-hotel-mapping/)
- [Accuracy or coverage in mapping? What 99.99% really means](https://hotelmapping.org/en/guide/accuracy-or-coverage-in-hotel-mapping/)
- [What duplicate hotel listings cost an agency: conversion, cancellations and complaints](https://hotelmapping.org/en/guide/cost-of-duplicate-hotel-listings/)
- [What is hotel XML integration? Static vs. dynamic data](https://hotelmapping.org/en/guide/what-is-hotel-xml-integration/)

## Related terms

- [Match score](https://hotelmapping.org/en/glossary/match-score/)
- [HM ID](https://hotelmapping.org/en/glossary/hm-id/)
- [Deduplication](https://hotelmapping.org/en/glossary/deduplication/)
- [Delta dump](https://hotelmapping.org/en/glossary/delta-dump/)
- [Supplier code](https://hotelmapping.org/en/glossary/supplier-code/)
