Flat files V1

The Flatfiles API provides a downloadable ZIP archive containing JSON data files with HX's inventory — sailings, ships, cabin grades, excursions, ports, pricing, and itineraries. This is the simplest way to get bulk product data for your integration.

Tip

Starting a new integration? The current-generation Flat files V3 serves voyages, ships, and ports as plain JSON endpoints and is simpler to consume. V1 (this page) remains fully supported.

Environments

Staging: https://partner.staging.travelhx.com/api/v1
Production: https://partner.travelhx.com/api/v1

Credentials

To start using the API, contact our support team via the support portal to get your credentials created. You will receive:

client_id and client_secret — for Auth0 authentication
user_key — your agency identifier, passed as a query parameter

Note

If you already have a user_key from the previous partner API offering, you may continue to use it. However you will still need Auth0 credentials to generate a bearer token.

Authentication

Authenticate with Auth0 to get a bearer token.

Token endpoints:

Staging: https://travelhx-backend-stage.eu.auth0.com/oauth/token
Production: https://partner-travelhx.eu.auth0.com/oauth/token

Audience values:

Staging: https://partner.dev.travelhx.dev/api
Production: https://partner.travelhx.com/api

curl --request POST \
  --url https://travelhx-backend-stage.eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"your_client_id","client_secret":"your_client_secret","audience":"https://partner.dev.travelhx.dev/api","grant_type":"client_credentials"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "scope": "application:B2B.API.Legacy",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Note

The bearer token is valid for the duration indicated by expires_in (in seconds) and should be cached and reused.

Download Flatfiles

Method: GET

Endpoint: /FlatFile/{agencyId}

Full example (staging):

curl --request GET \
  --url 'https://partner.staging.travelhx.com/api/v1/FlatFile/your_agency_id?user_key=your_user_key&includeSwota=true' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

Response: File download (application/octet-stream) — a ZIP archive containing JSON files.

Query Parameters

Parameter	Required	Description
`user_key`	Yes	Your agency user key
`includeSwota`	Yes	Set to `true` to include SwOTA (Seaware) format files in the archive

Archive Contents

The ZIP archive contains the following files:

PolarGlobal Files

{timestamp}_SourceMarket_{market}_{currency}.json - Source market pricing data
{timestamp}_Itinerary.json - Itinerary information
{timestamp}_Master.json - Master package data
{timestamp}_PackageMetaData.json - Package metadata

RefData Directory

excursion.json / excursion_{locale}.json - Excursion reference data (localized)
ships.json / ships_{locale}.json - Ship reference data (localized)
voyages.json / voyages_{locale}.json - Voyage reference data (localized)
cabingrades.json - Cabin grade reference data
portlist.json / portlist_new.json - Port list reference data
Itinerary.json - Itinerary reference data
Master.json - Master reference data
PackageMetaData.json - Package metadata reference data
{market}_{currency}.json - Market-specific currency data

SwOTA Files (when `includeSwota=true`)

When includeSwota=true, the archive additionally includes files with the _seaware suffix. These contain data formatted for the SwOTA (Seaware Web OTA) API.

Master_seaware.json - Master sailing records
ships_seaware.json - Ship specifications
cabingrades_seaware.json - Cabin grade definitions
portlist_new_seaware.json - Port reference data
voyages_seaware.json - Voyage definitions
PackageMetaData_seaware.json - Bookable package records
PackageItinerary_seaware.json - Full tour day-by-day itinerary
Itinerary_seaware.json - Voyage sailing itineraries with port visit schedules (sailing segment only; does not include land days)
excursion_seaware.json - Shore excursion data
SourceMarket_{currency}_seaware.json - Availability and pricing, all markets, priced in one currency (AUD, CAD, CHF, DKK, EUR, GBP, NOK, SEK, USD). {currency} only picks the display currency — it does not scope which sailings are included. See Building a market-specific view below.

File Relationships

SourceMarket_{currency}_seaware.json and voyages_{locale}.json are the two files you need for a market-specific catalogue with live availability and pricing; everything else below hangs off one of them via a shared key.

File relationships

Building a market-specific view

To show a market its own catalogue with live availability and pricing, join two files:

voyages_{locale}.json (RefData, PolarGlobal) — the voyage catalogue and marketing copy for that market. Which sailings even appear here already differs per locale, so pick the file for your target market.
SourceMarket_{currency}_seaware.json (RefData, SwOTA) — availability and pricing for every market, in one file. {currency} only selects which currency the rates are shown in; it does not filter which sailings are included. Its Market field is always "No Market" — a placeholder, not something to filter on.

Join them on TourCode (SourceMarket) ⇔ travelSuggestionCodes (voyages) — see the diagram above.

From there:

Ship details — SourceMarket → Master_seaware.json via MasterSailingId, then → ships_{locale}.json via ShipCode ⇔ shipId.
Cabin grade details — SourceMarket.Category ⇔ ships_{locale}.json → cabinCategories[].cabinGrades[].code (cabin grades are nested inside the ship record, not a separate file).
Port / location names — voyages_{locale}.json → itinerary[].location ⇔ portlist_new.json → code.

Which locale file for which market

Market	`voyages_{locale}.json`
EU	`voyages_de.json`, `voyages_fr.json`, `voyages_dk.json`
Nordic	`voyages_se.json`, `voyages_no.json`
UK	`voyages_uk.json`
USA	`voyages_us.json`
Australia	`voyages_au.json`

Pick the currency that matches the market when requesting SourceMarket_{currency}_seaware.json (e.g. voyages_de.json → SourceMarket_EUR_seaware.json, voyages_uk.json → SourceMarket_GBP_seaware.json).

File Schemas

voyages_{locale}.json

JSON array of voyage definitions. Fields:

url (string) - Voyage detail page URL
heading (string) - Voyage title
largeMap (object) - Map media with alternateText, captionText, creditText, URI fields
intro, sellingPoints, practicalInfo, includedInfo, notIncludedInfo, notes (string) - Marketing/info content
travelSuggestionCodes (array of strings) - Voyage identifiers in format "FROMPORT-TOPORT-NN" (e.g., "ARUSH-CLVAP-14N", "SJLYR-SJLYR-7N") — joins to SourceMarket_{currency}_seaware.json → TourCode
fromPort, toPort (string) - Embarkation/disembarkation port codes
isViaKirkenes (string) - Kirkenes routing indicator
customDepartureDates (string) - Special departure dates
durationText (string) - Human-readable duration (e.g., "15 days", "7 days", "21 days")
ItineraryIntro (string) - Itinerary introduction text
itinerary (array) - Day-by-day schedule:
- day (string) - Day label (e.g. "Day 1")
- location (string|null) - Port/place name (e.g. "Seward"), inconsistently formatted — matches portlist_new.json → description (case-insensitive), not a port code
- heading (string) - Day title
- body (string|null) - Day description
- mediaContent (array) - Day images/media

SourceMarket_{currency}_seaware.json

Availability and pricing for all markets, priced in one currency. Available currencies: AUD, CAD, CHF, DKK, EUR, GBP, NOK, SEK, USD. {currency} only picks the display currency of Rate_Sgl/Rate_Dbl — it does not scope which sailings are in the file. See Building a market-specific view. Fields:

MasterSailingId (number) - Links to Master_seaware sailing record
MasterPackageId (number) - Links to PackageMetaData package
Market (string) - Always "No Market" in practice — a placeholder field, not usable to filter by market
Currency (string) - Currency code (matches filename)
Pax (string) - Passenger configuration
Category (string) - Cabin grade code (e.g., "QJ", "MA", "XTJ", "USP")
SuperCategory (string) - Category grouping: "ARCTIC SUPERIOR", "EXPEDITIONSUITE", "POLAR OUTSIDE", "POLAR INSIDE", "EXPLORER", "DARWIN SUITE"
AvailableCabins (number) - Current inventory count
Rate_Sgl (string) - Single occupancy rate (e.g., "17416.51")
Rate_Dbl (string) - Double occupancy rate (e.g., "10244.75")
VoyageLink (string) - Reference to voyage code (e.g., "SJLYR-SJLYR-9N")
RateCode (string) - Rate type identifier
TourCode (string) - Tour package identifier (e.g. _@FRANT06-261016). Conceptually equivalent to voyages_{locale}.json → travelSuggestionCodes: both identify the bookable package(s) on a sailing. A single MasterSailingId can carry multiple TourCode variants (e.g. FRANT06 and FRANT06R) representing different bookable products on the same sailing. The travelSuggestionCodes field in voyages_{locale}.json is the same concept under a different name and is expected to be renamed TourCode in a future release.
TourStartDate, TourEndDate (string) - Tour package date range in ISO format

Table of Contents

Flat files V1

Tip

Environments

Credentials

Note

Authentication

Note

Download Flatfiles

Query Parameters

Archive Contents

PolarGlobal Files

RefData Directory

SwOTA Files (when includeSwota=true)

File Relationships

Building a market-specific view

Which locale file for which market

File Schemas

SwOTA Files (when `includeSwota=true`)