Status: beta. In prod oct. 2025
\nMapping endpoint:
\nManagement endpoint:
\nheader: UTF8 - JSON STRING - POST - GZIP - TEXT PLAIN
\nThe API provides two families of mapping tools:
\nLIVE Mapping
\nDesigned for real-time mapping of IDs or fields.
\nAPI calls return a JSON-formatted detailed response.
\nJOB Mapping
\nUsed for mapping entire inventories.
\nAPI calls return a confirmation, with results available for download.
\nBoth share the same endpoint:
\nTo interact with the mapper, create a database, upload data, the endpoint is:
\none ID at a time
\nmultiple IDs at the same time
\nwith optimal fields
\nwith standard fields
\npartial on name & address
\npartial on name & gps
\npartial on address & gps
\npartial on name only
\nreverse geocoding
\nusing a iso2 list
\nat global level
\n1 versus 1
\nThe mapper is source-agnostic: inventory, lists, and suppliers are all treated the same as data sources.
\nIt functions as a logger, recording every action you take. Each operation generates a row of mapped IDs, stored in a table, with every row tied to a unique session ID (sid)
The resulting table organizes the mapped IDs into columns, with one column per supplier.
\nWhen running multiple mapping jobs, you can retrieve the results by referencing the session ID you assigned.
\nFor best performance and cleanliness, regularly purge the inventory log once your mapping batches are complete.
\nDuplicates are virtually unavoidable. At one point the discrepancies between sources are such, you prefer to keep a duplicate rather than having a mapping error.
\nThe mapper detects 99% of them.
\nUpload each inventory, list, or supplier listing using (upload a supplier | using csv) or (upload a supplier | using json) into a nominal database.
The mapper is source-agnostic. It does not distinguish between inventory and suppliers. Use the genuine supplier name or an alias.
\nYou are free to map any source against any other.
\nEach mapping call can include a session ID (sid, up to 50 characters).
Session IDs are particularly useful for long-running mapping jobs, such as discovery or when using 1 vs 1 or X methods.
\nUsing the session ID (sid), you interact with the mapper.
To check on a mapping job progress, call the (manage | check on status) using your session ID (sid).
When mapping hotels with geocode fields, you can include a supplier’s name (suppl) and its related hotel ID (hid).
The mapped table automatically updates its columns when a new supplier name is detected.
\nSimilarly, if you provide a hotel entry with a previously unseen supplier name, a new supplier database is created & the entry is stored in it.
\nIf the supplier already exists, the entry is simply added to the existing database.
\n(hid) is not provided, the system generates a dummy ID by combining the supplier’s name with a sequential number.Real-Time Mapping Response
\nWhen using the API for real-time (LIVE) mapping, the response includes a detailed JSON object.
\nThe response provides structured mapping information such as IDs, geocodes, and related attributes, allowing immediate use without further processing.
\nSee an exemple at the end of the documentation.
\nmappedAtAddress
\n Contains the mapped ID(s) & details for a given input.
Use this if your main goal is simply retrieving the mapped ID.
otherAtAddress
\nLists additional IDs associated with the address. Depending on context, this may include:
\nother premises at same address.
\nInsufficiently qualified entries.
\nDuplicates found.
\nroomAtAddress
\n Provides mapped hotel rooms from suppliers such as Expedia and Hotelbeds.
You may also add your own room data or integrate from other sources.
IDtable
\nProvides the list of mapped IDs per supplier. (shortcut for IDs)
\nRunning a Discovery Job
\nUse the hotel endpoint.
Set the list of database names to be used.
\nSet the country (iso2) code (only one allowed).
It can be suppliers, aggregators, GDS, direct, OTA...
\nSet a unique session ID (sid) for the job (mandatory).
Session & Job Control
\nIf no session ID (sid) is provided, the system generates a unique default one.
Only one (iso2) country code can be processed per job.
A confirmation response is returned when the job is finished. There is no timeout.
\n< 3000 hotels, the response includes the detailed JSON per map like in LIVE methods.
\nIf you close the connection, check the progress or if ended using (manage | check status)
Use (result | DL mapped table) when ended to retrieve your mapping result.
Check the progress of running jobs with the (manage | check status) method.
You can stop a mapping job at any time using the (manage | kill a running job) call with the corresponding session ID (sid) .
How It Works
\nThis method cross-maps all suppliers to produce a unique inventory, consolidating every matched option and ID across sources.
\nEnables building an inventory from scratch, without requiring any pre-existing inventory.
\nCompared to currently available ID aggregators, the mapper identifies twice as many mapped hotels.
\nAutomatically detects and lists duplicates found (comma-separated) per source used for the discovery job.
\nDesigned for high reliability; currently in beta, with an error ratio of 1 per 80,000 maps (~99.99998% precision).
\nProcessing time may vary depending on the number of sources involved and sources' size.
\nMatrix result
\nThe output is an Excel-like table with one column per supplier.
\nIDs are distributed across the table depending on whether the supplier has a mapped entry for the corresponding hotel.
\nThe output includes the unique. When a hotel is only available from one source.
\nThe mapper selects your preferred geocodes for the final row (e.g., name, address) based on the suppliers' order you set for the call:
\nThe first supplier in your list has priority.
\nIf mapped, its values are used; otherwise, the next supplier in the list is picked.
\nUnique ID
\nResult table exemple
\n3 methods available (see examples)
\n1 versus 1.
\n1 versus X (multiple suppliers at the same time)
\nusing an iso2 country code
\nRunning a Mapping Job
\nUse the hotel endpoint.
You can map an inventory, source, or supplier against others.
\nUse database's name in (versus) list & base inventory name.
It can be one versus one or versus multiple others.
\nDefine a supplier’s database name to serve as the base inventory.
\nIf you already have an inventory, upload it as a source database and use its name.
\nUse country codes (iso2) to filter the selection (multiple values allowed).
Omit the codes (iso2)to map the entire listing.
Set a unique session ID (sid) for the job.
Session & Job Control
\nIf no session ID (sid) is provided, the system generates a unique default one.
A confirmation response is returned when the job is finished. There is no timeout.
\n< 3000 hotels, the response includes the detailed JSON per map like in LIVE methods.
\nIf you close the connection, check the progress or if ended using (manage | check status)
Use (result | DL mapped table) when ended to retrieve your mapping result.
Check the progress of running jobs with the (manage | check status) method.
You can stop a mapping job at any time using the (manage | kill a running job) call with the corresponding session ID (sid) .
Optimization Tips
\nIn case you do 1 versus 1, reduce mapping counts by always choose the smallest dataset as the inventory, and list larger ones as (versus) .
You can submit multiple (iso2) codes in one request. For example:
Map a large country (e.g., US) in a single call.
\nMap a dozen smaller countries together in another call.
\nResult
\nThe output is an Excel-like table with one column per supplier.
\nMapped IDs are listed depending on whether the supplier has been mapped with the corresponding base inventory entry.
\nThe base inventory geocodes are retained for the entry.
\nRunning a duplicates finder Job
\nUse the hotel endpoint.
upload the same listing twice into 2 different databases. (ex: apitude1, apitude2)
\nDefine a supplier’s database name (apitude1) to serve as the base inventory.
\nSet the second one (apitude2) in (versus) .
Use country codes (iso2) to filter the selection (multiple values allowed).
Omit the codes (iso2)to map the entire listing.
Set a unique session ID (sid) for the job.
Session & Job Control
\nIf no session ID (sid) is provided, the system generates a unique default one.
A confirmation response is returned when the job is finished. There is no timeout.
\n< 3000 hotels, the response includes the detailed JSON per map like in LIVE methods.
\nIf you close the connection, check the progress or if ended using (manage | check status)
Use (result | DL mapped table) when ended to retrieve your mapping result.
Check the progress of running jobs with the (manage | check status) method.
You can stop a mapping job at any time using the (manage | kill a running job) call with the corresponding session ID (sid) .
result
\nIn development
\n2 methods available (see examples)
\n1 ID from a supplier against X databases.
\na IDs list versus X.
\nInput Parameters
\nUse the hotel endpoint.
Use database's name for versus list & supplier.
input
\nlist: The list of IDs to map against the The supplier’s hotel ID you want to map
supplier: The name of the supplier database containing this ID
versus
\nversus: A list of supplier database names to map the list against{ \"credential\": \"mycredential\", \"input\": { \"hid\": \"3864091\", \"supplier\": \"jolidey\" }, \"versus\": [ \"apitude\",\"juniper\",\"restel\" ] }
Inputs (List Mode)
\nUse the hotel endpoint.
Use database's name for versus list & supplier.
inputs
\nlist: A collection of IDs to be mapped
supplier: The name of the supplier database containing these IDs
versus
\n{ \"credential\": \"mycredential\", \"input\": { \"suppl\":\"mikitravel\", \"hid\":\"3334522\", \"name\": \"Al Fassia Aguedal\", \"adr\": \"Zone Touristique De L 39 Aguedal\", \"lati\": \"31.599410\", \"longi\": \"-7.987370\", \"city\":\"Marrakech\", \"zip\":\"40000\", \"iso2\":\"MA\", \"stars\":\"3\" }, \"versus\": [ \"apitude\",\"restel\",\"juniper\",\"jolidey\" ] }
Sending Data ( all fields )
\nUse the hotel endpoint.
Use database's name for versus list.
Always include iso2 (mandatory).
You may also provide additional fields such as city, postal code, and star rating.
\nThe more data you supply, the more accurate and precise the mapping results will be.
\niso2 is mandatory.
suppl (supplier) and hid (hotel code) are optional. If omitted, \"uset\" is used for the supplier & a dummy incremental ID is set for the hotel.
{ \"credential\": \"mycredential\", \"input\": { \"suppl\":\"mikitravel\", \"hid\":\"3334522\", \"name\": \"Al Fassia Aguedal\", \"adr\": \"Zone Touristique De L 39 Aguedal\", \"lati\": \"31.599410\", \"longi\": \"-7.987370\", \"iso2\":\"MA\" }, \"versus\": [ \"apitude\",\"restel\",\"juniper\",\"jolidey\" ] }
Sending Data ( Standard fields )
\nAlways include iso2 (mandatory).
Use database's name for versus list.
input: Provide a name, an address, and GPS coordinates.
\nversus list: Add the list of supplier codes (databases) to map against.
\niso2 is mandatory.
suppl (supplier) and hid (hotel code) are optional. If omitted, \"uset\" is used for the supplier & a dummy incremental ID is set for the hotel.
{ \"credential\": \"mycredential\", \"input\": { \"name\": \"Al Fassia Aguedal\", \"adr\": \"Zone Touristique De L 39 Aguedal\", \"iso2\":\"MA\" }, \"versus\": [ \"apitude\",\"restel\",\"juniper\",\"jolidey\" ] }
iso2 is mandatory.{ \"credential\": \"mycredential\", \"input\": { \"name\": \"Al Fassia Aguedal\", \"lati\": \"31.599410\", \"longi\": \"-7.987370\", \"iso2\": \"MA\" }, \"versus\": [ \"apitude\", \"restel\", \"juniper\", \"jolidey\" ] }
iso2 is mandatory.{ \"credential\": \"mycredential\", \"input\": { \"adr\": \"Zone Touristique De L 39 Aguedal\", \"lati\": \"31.599410\", \"longi\": \"-7.987370\", \"iso2\": \"MA\" }, \"versus\": [ \"apitude\", \"restel\", \"juniper\", \"jolidey\" ] }
iso2 is mandatory.{ \"credential\": \"mycredential\", \"input\": { \"name\": \"Al Fassia Aguedal hotel\", \"iso2\": \"MA\" }, \"versus\": [ \"apitude\", \"restel\", \"juniper\", \"jolidey\" ] }
iso2 is mandatory.Inputs (List of Hotels)
\nUse the hotel endpoint.
Use database's name for versus list.
inputs list
\n Add multiple hotel elements with their respective fields. (Note the “s” at the end of inputs.)
versus list
\nSpecify the list of supplier names (databases) to map the inputs list against.
\nResponse
\nresponse->list) contains each hotel’s mapping result, with its own mapping arguments.Limitations
\nImportant
\nIf you send a hotel with a new supplier name (supplier attribute), that supplier is automatically added to your inventory ID table. It s database created and the entry recorded within.
If the supplier’s name is omitted, the system assigns \"unset\" as the default.
\nCall object fields:
\n","urlObject":{"protocol":"https","path":["hotel"],"host":["meta","hotel-matching","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"d842780a-d74b-4275-8e4d-d927a8d42c6c"},{"name":"LIVE | 1 vs list - no db","id":"2abc1f75-0ce4-4401-946c-30a6aa7aaf49","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Transfer-Encoding","value":"application/gzip","type":"text"},{"key":"Content-Type","value":"text/plain","type":"text"},{"key":"Accept","value":"*/*","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"credential\": \"myCredential\",\r\n \"inputs\": [\r\n {\r\n \"hid\": \"B277559\",\r\n \"supplier\":\"expedia\",\r\n \"name\": \"The Edison George Town\",\r\n \"adr\": \"15 Lebuh Leith\",\r\n \"city\": \"George Town\",\r\n \"zip\": \"10200\",\r\n \"iso2\": \"MY\",\r\n \"lati\": \"5.42096\",\r\n \"longi\": \"100.33467\"\r\n }\r\n ],\r\n \"list\": [\r\n {\r\n \"hid\": \"ChoQ9Z6Pg-rHlMKzARoNL2cvMTF5Y3k1dGd0ehAC\",\r\n \"supplier\":\"google\",\r\n \"name\": \"The Edison George Town\",\r\n \"iso2\": \"MY\",\r\n \"lati\": \"5.42096\",\r\n \"longi\": \"100.33485\"\r\n },\r\n {\r\n \"hid\": \"ChcIo8Gk3JTE5eFmGgsvZy8xdGRiazAzahAB\",\r\n \"supplier\":\"google\",\r\n \"name\": \"Edison George Town appartments\",\r\n \"iso2\": \"MY\",\r\n \"lati\": \"5.42096\",\r\n \"longi\": \"100.33467\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://meta.hotel-matching.com/hotel","description":"VOID - UNDER DEVELOPMENT
\ninputs list
\nSet the list of hotels you want to map against the list of hotels in versus .
1 to 5000 rows max.
\nversus list
\nSet the list of hotels you want to map against the inputs.
\n50.000 rows max.
\nVOID - UNDER DEVELOPMENT
\ninputs list
\nSet the list of hotels you want to map against the list of hotels in versus .
1 to 5000 rows max.
\nversus list
\nSet the list of hotels you want to map against the inputs.
\n50.000 rows max.
\nTerminate a Running Job
\nUse the manager endpoint.
Use database's name.
\nTo stop a running job, set the job’s session ID and call the kill method.
Retrieve the running job’s session ID using manage | check status method.
If you already set a sid in your initial call, you can use it directly.
Behavior
\nWhen a job is terminated, all entries already added to the inventory are removed.
\nIt may take up to 10 seconds for the job to fully stop.
\nUse the status method to check the current state until the job is confirmed killed.
Purge Job Logs
\nUse the manager endpoint.
Remove finished mapping jobs from the log list.
\nPerform this regularly after each mapping session.
\nImportant: Download your results before purging.
\nThe API provides no warning.
\nCheck Jobs & Databases Status
\nUse the manager endpoint:
Returns the current progress (%) for running jobs.
\nReturns the list of finished job session IDs.
\nProvides statistics on current databases and inventories.
\nCheck Jobs & Databases Status
\nUse the manager endpoint:
Returns the current progress (%) for running jobs.
\nReturns the list of finished job session IDs.
\nProvides statistics on current databases and inventories.
\nCheck Jobs & Databases Status
\nUse the manager endpoint:
Returns the current progress (%) for running jobs.
\nReturns the list of finished job session IDs.
\nProvides statistics on current databases and inventories.
\nCheck Jobs & Databases Status
\nUse the manager endpoint:
Returns the current progress (%) for running jobs.
\nReturns the list of finished job session IDs.
\nProvides statistics on current databases and inventories.
\nReset Inventory ID Table log
\nUse the manager endpoint.
Resets the mapped IDs log to its default state.
\nRetains only the ID column if a supplier database exists.
\nThe table is truncated, removing all other entries and data.
\nIMPORTANT
\nTo be done regularly after each mapping session.
\nDO NOT execute while some mapping jobs are running.
\nCheck if any are running by using the manage | check statuts before executing.
Always download your inventory results before resetting.
\nThere is no warning on API call reset execution.
\nDownload Inventory ID Table & results as a CSV file
\nUse the manager endpoint:
download: true
If a session ID (sid) is provided, only that session’s data is downloaded.
saveZIP: true is mandatory.
Returns the current inventory ID table, including all entries sent to the mapper since the last reset.
\nAdding saveDebug: true adds another file containing the complete mappings list for further post-check & control.
Download Inventory ID Table & results as a JSON file
\nUse the manager endpoint:
download: true
If a session ID (sid) is provided, only the data for that session is downloaded.
saveZIP: true is mandatory.
Returns the current inventory ID table, containing all entries sent to the mapper since the last reset.
\nAdding saveDebug adds another file contains the complete mappings list for post-check.
\nCreate Database as Source
\nUse the manager endpoint:
create: \"dbname\"This creates a new database named \"dbname\" to be used as a source.
Delete Database
\nUse the manager endpoint.
drop: \"dbname\"This deletes the database named \"dbname\".
Truncate Database
\nUse the manager endpoint.
truncate: \"dbname\"This empties the database named \"dbname\" without deleting it.
Remove IDs from Supplier Database
\nSpecify the supplier’s database code name.
\nProvide a list of IDs to remove.
\nRemoves the IDs from the supplier’s database and, if present, from the inventory log.
\nBenefits
\nSpeeds up ID removal without requiring a full re-upload of the listing.
\nUseful when a supplier publishes an update with certain IDs removed.
\nAdding New IDs
\nUpload List into Supplier Database using a CSV format
\nThere are 9 mandatory fields.
\nIn the inventoryCsv list, each element must contain these 9 fields as a string array.
The CSV header is informative only and can be omitted; the uploader only processes the inventoryCsv list.
The uploader validates each entry and reports any errors found.
\nMandatory Rules
\nFollow the column order exactly.
\nIf a field is missing, set it as an empty space; otherwise, the entry will be rejected.
\nColumn Order
\nhid
type
name
address
city
postal code
iso2
latitude
longitude
Performance Notes
\nUpload speed: ~12,000 entries per second.
\nUploading Expedia data takes 1 minute.
\nUpload List into Supplier Database using a JSON format
\nThere are 9 fields required for each hotel entry.
\nThe uploader validates each entry and reports any errors found.
\nIf a field is missing, the uploader will assign a default value.
\nField Mapping
\nhid
type
name
adr (address)
city
zip (postal code)
iso2
lati (latitude)
longi (longitude)
Performance Notes
\nUpload speed: ~12,000 entries per second.
\nUploading Expedia data takes 1 minute.
\nDestination Search
\nPerforms a search across your inventory or a supplier.
\nAutocomplete is supported for name, address, and city.
\nReturns the 20 most relevant results, sorted by relevance.
\nRequires a minimum of 5 characters in the search query.
\nMandatory, keep & leave autocomplete to true in your call.
\nUse Case
\nQuickly select an ID for a destination within your inventory or a supplier.
\nCan be chained with other mapping methods to map the selected ID against other sources.
\nProvides instant, real-time responses.
\nDump Database
\nUse the manager attribute:
dump: \"dbname\"Optional parameters:
\nasCSV: true – Return the database as a CSV file.
saveZIP: true – Save a ZIP file containing the database and return a download link.
If both options are omitted, the database CSV is returned directly in the response.
\nDump Database (JSON)
\nUse the manager attribute:
dump: \"dbname\"Optional parameters:
\nasJSON: true – Export the database as JSON.
saveZIP: true – Save a ZIP file containing the database and return a download link.
If both options are omitted, the JSON is returned directly in the response.
\nDump Database (JSON)
\nUse the manager attribute:
dump: \"dbname\"Optional parameters:
\nasJSON: true – Export the database as JSON.
saveZIP: true – Save a ZIP file containing the database and return a download link.
If both options are omitted, the JSON is returned directly in the response.
\nContact me for activation. olivier@room-matching.com
\nMap Rooms
\nUse the parameter:
\nmapRoom: trueBehavior:
\nWorks with live API call only.
\nIf the selected suppliers have a room database uploaded, their rooms are mapped simultaneously.
\nIn case multiple suppliers have a rooms database and the hotel IDs are mapped, their respective rooms database for this hotel are mapped, matched & grouped together.
\nThe response returns a compact mapping with essential information.
\nSuppliers like EPS and HBG provide static listings; if a mapping exists, their hotel rooms are mapped and grouped in the response.
\nYou can also upload your own room inventory to include it in the mapping, or use the room-matching API directly.
\nResponse:
\nRooms appear under the mappedRoom section, consistent with the current room-matching API response.
Produces a complete ID card for a hotel, including IDs, geoCodes, and mapped rooms.
\n