How to Integrate a Hotel Mapping API in One Afternoon (Step-by-Step with Mappin)

A hotel mapping API should take you from "we have five supplier feeds and a duplicate problem" to "every hotel in our system has one master ID" in an afternoon - not a quarter. This guide walks through a complete Mappin integration: authentication, geography lookup, fetching master hotels with their supplier codes, batch-mapping your own IDs, and keeping everything in sync daily.

All examples use plain HTTP so they translate to any language. The full API reference lists every parameter.

Before you start

You need three things:

1. A Mappin account and API key - register here (the free tier lets you try every endpoint).
2. The supplier codes your system already stores (for example Hotelbeds, Dida, RezLive, Restel or Travellanda hotel codes).
3. Somewhere to persist the master_hotel_id next to each of your hotel records.

Every request carries the key in a header:

GET /api/countries/ HTTP/1.1
Host: mappin.rpconnect.travel
X-API-KEY: your_api_key_here

Responses are JSON. Paginated endpoints return 50 items by default and accept ?limit= up to 500; follow the next link until it is null.

Step 1 - Resolve geography

Hotel mapping starts with geography: a hotel can only be matched inside the right master city. Pull the country list once, then look cities up by name or browse by country.

GET /api/countries/?search=united+arab
GET /api/cities/?country=AE&search=dubai

Each master city carries a stable city_id. Store it against your own city table - it is the key you will use for hotel queries and it never changes.

Step 2 - Fetch master hotels for a city

The quickest path from a name to hotels is the /api/city/ endpoint: search once to get the city_id, then request its hotels.

GET /api/city/?city=Dubai

{
  "results": [
    {"city_id": 2041, "name": "Dubai", "country": "United Arab Emirates", "hotel_count": 1842}
  ],
  "hint": "Use ?city_id=2041 to list hotels in this city"
}

GET /api/city/?city_id=2041&limit=100

{
  "count": 1842,
  "next": "/api/city/?city_id=2041&limit=100&page=2",
  "results": [
    {
      "master_hotel_id": 581233,
      "name": "Hilton Dubai Jumeirah",
      "latitude": 25.2048,
      "longitude": 55.2708,
      "star_rating": 5,
      "providers": [
        {"provider": "hotelbeds",  "code": "12345"},
        {"provider": "dida",       "code": "DXB-00981"},
        {"provider": "rezlive",    "code": "RZ77120"}
      ]
    }
  ]
}

That providers array is the whole point of hotel mapping: one master record, every supplier code attached. Need more detail? /api/hotels/{master_hotel_id}/ returns the full master record including address and all mappings.

Step 3 - Batch-map the supplier codes you already have

Most teams are not starting from zero - they have thousands of supplier hotel codes stored already. Instead of iterating city by city, map them directly:

POST /api/provider-map/
X-API-KEY: your_api_key_here
Content-Type: application/json

{
  "provider": "hotelbeds",
  "codes": ["12345", "67890", "11223"]
}

{
  "results": [
    {"code": "12345", "master_hotel_id": 581233, "providers": [{"provider": "dida", "code": "DXB-00981"}, {"provider": "rezlive", "code": "RZ77120"}]},
    {"code": "67890", "master_hotel_id": 581240, "providers": []},
    {"code": "11223", "master_hotel_id": null}
  ]
}

Send up to 100 codes per call. A null master means that supplier code is not yet mapped; log it and move on - you can query it again after the next data refresh. A typical first pass over 50,000 supplier codes is 500 requests, well inside a Basic plan's 10,000-per-day quota.

Persist master_hotel_id on your hotel row and switch your search index, cache keys and content joins to it. Supplier codes become an attribute of the hotel rather than its identity.

Step 4 - Sync changes daily instead of re-importing

Master data changes: hotels open and close, duplicates are merged, names are corrected. Instead of re-pulling everything, ask for what changed since your last sync:

GET /api/changes/?since=2026-10-20

{
  "since": "2026-10-20",
  "count": 213,
  "results": [
    {"entity": "hotel", "id": 581240, "action": "merged_into", "target_id": 581233, "changed_at": "2026-10-21T09:14:00+05:30"},
    {"entity": "hotel", "id": 603311, "action": "updated", "fields": ["name", "star_rating"], "changed_at": "2026-10-22T18:02:00+05:30"},
    {"entity": "city",  "id": 2041,   "action": "updated", "fields": ["latitude", "longitude"], "changed_at": "2026-10-23T02:31:00+05:30"}
  ]
}

Run this once a day (a merged_into action tells you to re-point the old master ID to the new one). Mappin also e-mails every active partner a daily digest of changes at 18:00 IST, so your operations team sees the same information without touching the API. Add ?format=csv if you prefer a spreadsheet.

Step 5 - Respect the limits and handle errors

Design around three limits and you will never be throttled:

Error responses are consistent JSON with a code field (MISSING_API_KEY, INVALID_API_KEY, DAILY_QUOTA_EXCEEDED, BURST_RATE_LIMITED ...) and, where relevant, an upgrade_url and Retry-After header. A small retry wrapper that honours Retry-After on 429 and backs off on 5xx is all you need.

A minimal client in Python

import time
import requests

BASE = "https://mappin.rpconnect.travel"
HEADERS = {"X-API-KEY": "your_api_key_here"}

def get(path, **params):
    while True:
        r = requests.get(BASE + path, headers=HEADERS, params=params, timeout=20)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        r.raise_for_status()
        return r.json()

def map_codes(provider, codes):
    out = {}
    for i in range(0, len(codes), 100):
        batch = codes[i:i + 100]
        r = requests.post(BASE + "/api/provider-map/", headers=HEADERS,
                          json={"provider": provider, "codes": batch}, timeout=30)
        r.raise_for_status()
        for row in r.json()["results"]:
            out[row["code"]] = row["master_hotel_id"]
        time.sleep(0.3)   # stay under 5 req/s
    return out

city = get("/api/city/", city="Dubai")["results"][0]
hotels = get("/api/city/", city_id=city["city_id"], limit=500)
print(hotels["count"], "master hotels in", city["name"])

What you have at the end of the afternoon

• Every hotel in your system carries a stable master_hotel_id
• Duplicate listings collapse automatically, and price comparison across suppliers works
• New supplier feeds plug in by mapping their codes, not by re-building your catalogue
• A daily /api/changes/ call keeps you in sync without full reloads

Start with the free tier, then pick a plan by daily volume: Basic (10,000 requests/day), Pro (50,000) or Premium (200,000) - see pricing. Questions about a specific supplier or a migration plan? Write to assist@rpconnect.travel.