Quickstart: Map Your First Hotel Inventory

Go from zero to mapped hotel inventory in five steps. Upload a file, start a mapping job, and retrieve matched results against the global reference dataset.

This guide walks you through the core Mapping.Travel API workflow: authenticate, upload an inventory file, start a mapping job, poll for completion, and retrieve your matched results. By the end you will have a working end-to-end integration you can adapt to your own data pipeline.

Prerequisites

• A Mapping.Travel account with an API token (see Authentication)
• curl or any HTTP client
• A hotel inventory file in CSV, JSON, Excel (.xlsx), or Parquet format

1. Get your Bearer token

   Retrieve your API token from Settings → API tokens in the Mapping.Travel dashboard. You will use it in every request below.

   Set it as an environment variable so you do not have to repeat it:

   export MT_TOKEN="<your-token>"
   
2. Prepare your inventory file

   Your inventory file must include hotel records with enough information for matching. For CSV, use the following columns:

   Column	Required	Description
   id	Yes	Your internal hotel identifier
   name	Yes	Hotel name
   address	No	Street address
   city	Yes	City name
   country	Yes	ISO country code (e.g. US, FR)
   latitude	No	Decimal latitude
   longitude	No	Decimal longitude

   Example CSV:

   id,name,address,city,country,latitude,longitude
   hotel-001,The Grand Plaza,45 Main Street,New York,US,40.7128,-74.0060
   hotel-002,Hotel Metropole,12 Rue de Rivoli,Paris,FR,48.8566,2.3522
   hotel-003,Seaside Resort,8 Ocean Drive,Miami,US,25.7617,-80.1918
   

   JSON, Excel (.xlsx), and Parquet files are also accepted. The column names must match the schema above regardless of format.

3. Upload your inventory

   POST your file to /api/v1/inventory. The API accepts multipart/form-data.

   curl -X POST https://api.mapping.travel/api/v1/inventory \
     -H "Authorization: Bearer $MT_TOKEN" \
     -F "file=@hotels.csv"
   

   If you are mapping against a specific supplier’s ID space (for ID_TO_ID or HYBRID mode), include the supplierCode parameter:

   curl -X POST https://api.mapping.travel/api/v1/inventory \
     -H "Authorization: Bearer $MT_TOKEN" \
     -F "file=@hotels.csv" \
     -F "supplierCode=expedia"
   

   A successful upload returns 201 Created with an uploadId:

   {
     "uploadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "filename": "hotels.csv",
     "status": "PROCESSING",
     "recordCount": null,
     "createdAt": "2026-04-25T10:00:00Z"
   }
   

   Save the uploadId—you need it in the next steps.

   Uploads are idempotent. If you upload the same file twice, the API returns the same uploadId.

4. Start a mapping job

   POST to /api/v1/mapping with the partnerInventoryId from your upload. Choose a mode that matches your use case:

   • STANDARD — fuzzy matching by name and location (recommended for most cases)
   • ID_TO_ID — match by supplier hotel ID (requires a supplierCode on the upload)
   • HYBRID — try ID-based match first, fall back to fuzzy

   curl -X POST https://api.mapping.travel/api/v1/mapping \
     -H "Authorization: Bearer $MT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "mode": "STANDARD"
     }'
   

   A successful response returns 201 Created with a mappingJobId:

   {
     "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
     "status": "PENDING",
     "mode": "STANDARD",
     "createdAt": "2026-04-25T10:01:00Z"
   }
   

   If your free plan quota is exhausted, you receive a 403 response. Upgrade your plan or wait for the quota to reset.

5. Check mapping status

   Mapping jobs run asynchronously. Poll GET /api/v1/mapping/{mappingJobId} until status is COMPLETED or FAILED.

   curl https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210 \
     -H "Authorization: Bearer $MT_TOKEN"
   

   While running:

   {
     "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
     "status": "RUNNING",
     "mode": "STANDARD",
     "totalRecords": 3,
     "processedRecords": 1,
     "createdAt": "2026-04-25T10:01:00Z",
     "updatedAt": "2026-04-25T10:01:15Z"
   }
   

   When complete:

   {
     "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
     "status": "COMPLETED",
     "mode": "STANDARD",
     "totalRecords": 3,
     "processedRecords": 3,
     "matchedRecords": 2,
     "createdAt": "2026-04-25T10:01:00Z",
     "completedAt": "2026-04-25T10:01:45Z"
   }
   

   Poll every 5–10 seconds for small files. For large inventories, start with a 30-second interval and adjust based on your typical job duration.

6. Retrieve your mapping results

   Once the job is COMPLETED, search the results by POSTing to /api/v1/mapping/{mappingJobId}/results/search. You can filter by hotel name, city, country, partner ID, or matched reference ID.

   curl -X POST https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/results/search \
     -H "Authorization: Bearer $MT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "page": 0,
       "size": 20
     }'
   

   The response includes each partner hotel alongside its matched reference hotel:

   {
     "totalResults": 2,
     "page": 0,
     "size": 20,
     "totalPages": 1,
     "results": [
       {
         "id": "99887766-5544-3322-1100-aabbccddeeff",
         "partnerHotelId": "hotel-001",
         "partnerHotelName": "The Grand Plaza",
         "partnerHotelCity": "New York",
         "partnerHotelCountry": "US",
         "matchedReferenceHotelId": "ref-00042",
         "matchedReferenceHotelName": "Grand Plaza Hotel New York",
         "matchConfidence": 94.0,
         "matchMethod": "standard",
         "supplierExternalIds": {}
       },
       {
         "id": "aabbccdd-1122-3344-5566-778899001122",
         "partnerHotelId": "hotel-002",
         "partnerHotelName": "Hotel Metropole",
         "partnerHotelCity": "Paris",
         "partnerHotelCountry": "FR",
         "matchedReferenceHotelId": "ref-01187",
         "matchedReferenceHotelName": "Metropole Hotel Paris",
         "matchConfidence": 91.0,
         "matchMethod": "standard",
         "supplierExternalIds": {}
       }
     ]
   }
   

   Hotels with no match are included with matchedReferenceHotelId: null and matchMethod: null.

Next steps

Inventory uploads

Manage uploads, list past inventories, and download files.

Mapping modes

Learn when to use STANDARD, ID_TO_ID, and HYBRID modes.

Billing and usage

Monitor quota usage and manage your subscription.

API reference

Full reference for all endpoints, parameters, and response shapes.