Run a Hotel Mapping Job

Start a hotel mapping job against the Mapping.Travel reference database, choose the right mapping mode, and poll for results including match counts.

Once your inventory upload reaches COMPLETED status, you can start a mapping job. Mapping.Travel matches your partner hotels against the reference hotel database and returns a count of matched and unmatched hotels. The job runs asynchronously — you poll for its status until it completes.

Choosing a mapping mode

The mode field in your mapping request controls the matching strategy. Choose based on what data you have available.

Mode	When to use	Requires supplier code
STANDARD	You don’t have supplier hotel IDs, or you want broad fuzzy matching coverage	No
ID_TO_ID	You have supplier hotel IDs and want precise, exact-match results	Yes
HYBRID	You want ID_TO_ID precision with fuzzy matching as a fallback for unmatched hotels	Yes

STANDARD runs a fuzzy matching pipeline against the full reference database. It’s the best default choice when you don’t have supplier IDs.

ID_TO_ID matches exclusively by supplier external IDs. Every hotel in your inventory must have a supplierCode column, and you must pass the matching supplierCode when uploading the file. Hotels without a supplier ID are left unmatched.

HYBRID runs ID_TO_ID first. Any hotels not matched by ID fall through to the fuzzy pipeline. This gives you the precision of ID matching where possible, with coverage from fuzzy matching for the rest.

ID_TO_ID and HYBRID both require a supplierCode on your inventory upload. If the inventory has no supplier code, the API returns a 400 Bad Request.

1. Start the mapping job

   Send a POST request to /api/v1/mapping with your partnerInventoryId and chosen mode.

   STANDARD

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

   A successful request returns HTTP 201:

   {
     "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
     "status": "PENDING",
     "mode": "STANDARD",
     "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "createdAt": "2026-04-25T10:05:00Z"
   }
   

   Save the mappingJobId to poll for status and to search results later.

2. Poll for job status

   Check the job status with 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 <your-token>"
   

   {
     "mappingJobId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
     "status": "COMPLETED",
     "mode": "STANDARD",
     "partnerInventoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "rowCount": 1000,
     "matchedCount": 923,
     "unmatchedCount": 77,
     "createdAt": "2026-04-25T10:05:00Z",
     "completedAt": "2026-04-25T10:07:42Z"
   }
   

   Status	Meaning
   PENDING	Queued, not yet started
   PROCESSING	Mapping pipeline is running
   COMPLETED	All phases finished successfully
   FAILED	Job failed — check the error message

   Poll every 5–10 seconds. Small inventories (under 1,000 hotels) typically complete in under a minute. Larger files may take several minutes.

3. Review the results summary

   The completed job response includes three key counts:

   • rowCount — total number of hotels in your inventory
   • matchedCount — hotels successfully matched to a reference hotel
   • unmatchedCount — hotels with no match found

   For HYBRID jobs, matchedCount includes hotels matched by both ID_TO_ID and the fuzzy fallback pipeline.

   To see individual match results and drill into specific hotels, use the search results endpoint.

Quota and credits

Each mapping job counts against your daily quota. On the free plan, you can run 10 mapping jobs per day. On subscription plans, you get a higher daily limit.

If you exceed your daily limit, you need credits to continue. Each credit covers one additional mapping job. The API returns a 403 Forbidden if you have no remaining quota and no credits.

Check your current quota before starting a job:

curl https://api.mapping.travel/api/v1/billing/quota/status \
  -H "Authorization: Bearer <your-token>"

See Billing and Quotas for details on purchasing credits and upgrading your plan.

List all mapping jobs

To view all mapping jobs for your organization:

curl "https://api.mapping.travel/api/v1/mapping?page=0&size=20" \
  -H "Authorization: Bearer <your-token>"