Quickstart

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 matched results.

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

Get your API key

Retrieve your API token from Settings → API tokens in the mapping.travel dashboard. You use it in every request below.Set it as an environment variable to avoid repeating it:

export MT_TOKEN="<your-token>"

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.

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 "X-API-Key: $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 "X-API-Key: $MT_TOKEN" \
  -F "file=@hotels.csv" \
  -F "supplierCode=expedia"

A successful upload returns 202 Accepted 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.

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 "X-API-Key: $MT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "mode": "STANDARD"
  }'

A successful response returns 202 Accepted 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.

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 "X-API-Key: $MT_TOKEN"

While running:

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

When complete:

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

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

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 "X-API-Key: $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.

Get Started

Core Concepts

Guides

Delivery destinations

MCP

Agents

Prerequisites

Next steps

Inventory uploads

Mapping modes

Billing and usage

API reference

​Prerequisites

​Next steps

Inventory uploads

Mapping modes

Billing and usage

API reference

Prerequisites

Next steps