Table of Contents

Flat files API

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.

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 No 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 - 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 - Land package itineraries
  • Itinerary_seaware.json - Sailing itineraries with port schedules
  • excursion_seaware.json - Shore excursion data
  • SourceMarket_{currency}_seaware.json - Currency-specific pricing (AUD, CAD, CHF, DKK, EUR, GBP, NOK, SEK, USD)
  • voyages_{region}_seaware.json - Region-filtered voyages (ANZ, ASIA, CANADA, CE, DACH, DE, FR, LATAM, MEA, NORDICS, UK, US)

File Relationships

The diagrams below show how the flatfiles reference each other via shared keys.

Note

Both SourceMarket and Itinerary independently reference Master via MasterSailingId. The chain shown (SourceMarket → Itinerary → Master) is for layout clarity.

PolarGlobal Files

PolarGlobal file relationships

Seaware Files (SwOTA)

Seaware file relationships

SwOTA File Schemas

Master_seaware.json

JSON array of master sailing records. Fields:

  • MasterSailingId (number) - Unique sailing identifier
  • CruiseLine (string) - Cruise line code (e.g., "HX")
  • DepartureDate, ArrivalDate (string) - ISO date format (YYYY-MM-DD)
  • DeparturePort, ArrivalPort (string) - Port codes (e.g., "GLGOH", "ARUSH", "SJLYR")
  • ShipCode (string) - Ship identifier: FN (Fridtjof Nansen), FR (Fram), RA (Roald Amundsen), SP (Spitsbergen), SC (Santa Cruz II)
  • ViaKirkeness (string) - Kirkenes routing flag
  • Description (string) - Sailing description
  • Region (string) - Geographic region: "NORWAY", "ALASKA", "ANTARCTICA", "SVALBARD", "GALAPAGOS", "GREENLAND", "ICELAND", "BRITISH ISLES", "EUROPE", "SOUTH AMERICA", "NW PASSAGE", "ARCTIC CANADA"

ships_seaware.json

JSON array of ship specifications. Fields:

  • shipId (string) - Ship code (FN, FR, RA, SP, SC)
  • heading (string) - Full ship name (e.g., "MS Fridtjof Nansen", "MS Fram", "MS Roald Amundsen", "MS Santa Cruz II", "MS Spitsbergen")
  • imageUrl, pageUrl (string) - Asset URLs
  • body, secondaryBody (string) - Ship descriptions
  • yearOfConstruction (string) - Build year (e.g., "2019", "2007", "2015")
  • shipyard (string) - Construction shipyard
  • passengerCapacity (string) - Max passengers (e.g., "1590", "318", "335", "150")
  • beds, carCapacity (string)
  • grossTonnage (number|null) - Ship tonnage
  • length, beam (number|null) - Ship dimensions in meters
  • speed (number|null) - Cruising speed in knots
  • facilities (array of strings) - Onboard amenities: restaurants ("Main Restaurant", "Fine dining 2", "IMAQ", "Aune", "Brygga", "Beagle Restaurant"), "LIBRARY", "CONFERENCE"
  • decks (array) - Deck info with number and media object containing alternateText, lowResolutionUri, highResolutionUri, retinaUri
  • cabinCategories (array) - Each contains:
    • title (string) - Category name: "POLAR OUTSIDE", "POLAR INSIDE", "EXPEDITIONSUITE", "ARCTIC SUPERIOR", "EXPLORER", "DARWIN SUITE"
    • description (string)
    • media (array of media objects)
    • cabinGrades (array) - Grade details with code, title, shortDescription, longDescription, sizeFrom, sizeTo, cabin amenities flags (hasBathroom, hasBalcony, hasSofa, hasTv, etc.)
  • passengerCapacityAntarctica (string) - Reduced capacity for Antarctic voyages

cabingrades_seaware.json

JSON array of cabin grade definitions. Fields:

  • code (string) - Grade code (e.g., "DS", "MA", "MB", "MC", "XTJ", "Q2", "Q4", "TT", "USP", "USPS")
  • shipDescriptions (array) - Per-ship configurations:
    • shipCode (string) - Ship this grade is available on
    • maxCapacity (number) - Maximum passengers for this grade/ship combination (1.0, 2.0, 3.0, 4.0)
    • description (string)

portlist_new_seaware.json

JSON array of port reference data. Fields:

  • code (string) - Port code (e.g., "ISHEM", "ARUSH", "SJLYR", "AQDAN", "GLGOH")
  • country (string) - ISO 2-letter country code (IS, AR, NO, AQ, GL, etc.)
  • description (string) - Port/location name (e.g., "Heimaey", "Ushuaia", "Longyearbyen", "Danco Island", "Nuuk (Godthaab)")

voyages_seaware.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")
  • 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 (number) - Day number (1, 2, 3...)
    • location (string) - Port code or "AT SEA"
    • heading (string) - Day title
    • body (string|null) - Day description
    • mediaContent (array) - Day images/media

PackageMetaData_seaware.json

Nested JSON array of bookable package records. Fields:

  • MasterPackageId (number) - Unique package identifier (e.g., 102840, 115362)
  • PackageId (string) - Package code: "FROMPORT-TOPORT-NN" format (e.g., "GLGOH-USOME-23N", "NOTOS-NOTOS-7N", "ECSYM-ECSYM-8N")
  • StartDate, EndDate (string) - Package dates in ISO format
  • EmbarkationDate (string) - Boarding date
  • StartLocation, EndLocation (string) - Port codes

PackageItinerary_seaware.json

JSON array of land package definitions with itinerary components. Fields:

  • PackageId (string) - Package code (e.g., "AEP-IGR-EC", "ANCAIR-HOT")
  • Description (array) - Localized descriptions with Culture and Description
  • Supplier (string|null) - Package supplier name (e.g., "Premier Alaska Tours")
  • Markets (array of strings) - Target markets
  • StartLocation, EndLocation (string) - Location codes
  • Destination (string) - Destination identifier
  • Availability (object):
    • DateRange (object) - FromDate, ToDate in ISO format, Days
    • Dates (array of strings) - Available departure dates
    • Ships (array) - Applicable ships
  • MandatoryArrivalPackage, MandatoryDeparturePackage (string) - Required connecting packages
  • MandatoryArrivalPackageOffset, MandatoryDeparturePackageOffset (string) - Timing offsets
  • PackageItinerary (array) - Day-by-day components:
    • Type (string) - Component type: "Flight", "Transfer", "Hotel", "Ferry", "Rail", "Voyage"
    • Supplier (string|null) - Component supplier
    • StartDay, EndDay (number) - Day numbers (1-based)
    • FlightDetails (object) - FlightType, BookingClass, Route with From, To, Segments
    • HotelDetails (object) - DefaultRoomType, DefaultBoardBasis
    • TransferDetails (object) - From, To, Method
    • VoyageDetails (object) - FromPort, ToPort
    • Description (array) - Component descriptions

Itinerary_seaware.json

JSON array of sailing itineraries with port visit schedules. Fields:

  • MasterSailingId (string) - Links to Master_seaware sailing record
  • ItineraryDetails (array) - Ordered port visits:
    • OrderNumber (number) - Sequence number (1, 2, 3...)
    • Port (string) - Port code or "AT SEA"
    • ArrivalDateTime (string) - Arrival time in ISO format (YYYY-MM-DD HH:MM:SS) or "NaT" for not applicable
    • DepartureDateTime (string) - Departure time in ISO format or "NaT"
    • Notes (string) - Additional notes

excursion_seaware.json

JSON array of shore excursion data. Fields:

  • id (string) - Unique excursion identifier (e.g., "3591", "5140", "6742")
  • link (string) - Excursion detail page URL
  • image (object) - imageUrl, altText, caption, credits
  • title (string) - Excursion name (e.g., "Golden Circle Tour with lunch", "Porto Walking Tour", "Castro Walking Tour")
  • summary (string|null) - Short description
  • details (string) - Full excursion description
  • code (string|null) - Excursion booking code (e.g., "SJLYR-01-270615", "PTOPO-IN01-2027-04-24")
  • price (string) - Display price
  • priceValue (string) - Numeric price value
  • durationText (string) - Duration description
  • years (array) - Applicable seasons with id and text (e.g., "26-27", "27-28")
  • seasons (array) - Season availability with id and text
  • physicalLevel (array) - Physical difficulty with id and text
  • activityCategory (string) - Activity type category

SourceMarket_{currency}_seaware.json

Currency-specific pricing and availability. Available currencies: AUD, CAD, CHF, DKK, EUR, GBP, NOK, SEK, USD. Fields:

  • MasterSailingId (number) - Links to Master_seaware sailing record
  • MasterPackageId (number) - Links to PackageMetaData package
  • Market (string) - Market identifier (e.g., "No 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

voyages_{region}_seaware.json

Region-filtered voyage data with identical structure to voyages_seaware.json. Available regions:

  • voyages_ANZ_seaware.json - Australia/New Zealand market
  • voyages_ASIA_seaware.json - Asian market
  • voyages_CANADA_seaware.json - Canadian market
  • voyages_CE_seaware.json - Central Europe market
  • voyages_DACH_seaware.json - Germany/Austria/Switzerland market
  • voyages_DE_seaware.json - Germany market
  • voyages_FR_seaware.json - France market
  • voyages_LATAM_seaware.json - Latin America market
  • voyages_MEA_seaware.json - Middle East/Africa market
  • voyages_NORDICS_seaware.json - Nordic countries market
  • voyages_UK_seaware.json - United Kingdom market
  • voyages_US_seaware.json - United States market