Upload and Prepare Your Hotel Inventory File

Prepare and upload a hotel inventory file in CSV, JSON, Excel, or Parquet format, then poll for processing status before starting a mapping job.

Before you can run a mapping job, you need to upload your hotel inventory to Mapping.Travel. The API accepts CSV, JSON, Excel (.xlsx), and Parquet files up to 500 MB. Uploading is idempotent — if you upload the same file twice, the API returns the same upload ID rather than creating a duplicate.

File format

Your inventory file must include the following columns. Column names are case-sensitive.

Column	Required	Description
id	Yes	Your internal hotel identifier
name	Yes	Hotel name
address	No	Street address
city	Yes	City
country	Yes	Country (full name or ISO code)
latitude	No	Decimal latitude
longitude	No	Decimal longitude
supplierCode	No	Supplier code for ID_TO_ID or HYBRID mapping (e.g. expedia, booking)

Example CSV:

id,name,address,city,country,latitude,longitude
hotel-001,The Grand Budapest,1 Mendl's Square,Zubrowka,PL,51.1079,17.0385
hotel-002,Hotel Chevalier,15 Rue Monseigneur,Paris,FR,48.8566,2.3522
hotel-003,Royal Tenenbaum,111 Archer Avenue,New York,US,40.7128,-74.0060

If you plan to use ID_TO_ID or HYBRID mapping, include the supplierCode query parameter when uploading and add your supplier’s hotel IDs in a supplierCode column:

id,name,address,city,country,latitude,longitude,expedia
hotel-001,The Grand Budapest,1 Mendl's Square,Zubrowka,PL,51.1079,17.0385,12345678
hotel-002,Hotel Chevalier,15 Rue Monseigneur,Paris,FR,48.8566,2.3522,98765432

1. Prepare your file

   Export your hotel data in one of the supported formats. Make sure every row has at minimum an id, name, city, and country. Remove any rows with blank IDs — they will cause the upload to fail with a 400 error.

   If your file is larger than 500 MB, split it into multiple uploads and run a separate mapping job for each.

2. Upload the file

   Send a multipart/form-data POST request to /api/v1/inventory. Include your supplier code as a query parameter if you have one.

   Standard upload

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

   A successful upload returns HTTP 201 with an upload object:

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

   Save the uploadId — you need it to check status and to start a mapping job.

3. Poll for processing status

   The API processes your file asynchronously. Poll GET /api/v1/inventory/{uploadId} until status is COMPLETED.

   curl https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
     -H "Authorization: Bearer <your-token>"
   

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

   Status	Meaning
   PENDING	Queued, not yet started
   PROCESSING	File is being parsed and validated
   COMPLETED	Ready to use in a mapping job
   FAILED	Processing failed — check the error message
   CANCELLED	You cancelled the upload

   Poll every 2–5 seconds. Most files complete within 30 seconds, but large Parquet files may take a few minutes.

4. Handle errors

   If the upload fails, the response will include an error message explaining what went wrong.

   HTTP status	Cause	Fix
   400 Bad Request	Empty file, missing required columns, or malformed data	Check your file format and required columns
   413 Payload Too Large	File exceeds 500 MB	Split the file into smaller chunks
   415 Unsupported Media Type	File format not supported	Convert to CSV, JSON, Excel, or Parquet
   429 Too Many Requests	Upload rate limit exceeded	Wait and retry with exponential backoff

   If status is FAILED, do not use that uploadId to start a mapping job. Fix the issue and re-upload.

List your inventories

To see all previously uploaded inventories for your organization, use the list endpoint:

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

Cancel an in-progress upload

If you need to stop an upload that is still PENDING or PROCESSING, send a cancel request:

curl -X POST https://api.mapping.travel/api/v1/inventory/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer <your-token>"