Migration Guide: Galileo Web Services (GWS) to Hotel JSON API

Introduction

This migration guide assists developers in transitioning from Galileo Web Services (GWS) SOAP-based hotel booking to the modern Hotel JSON API. The JSON API provides a RESTful interface with simplified request/response structures and improved performance.

Key Benefits of the JSON API:

• REST/JSON instead of SOAP/XML - simpler integration

• OAuth 2.0 authentication instead of WS-Security

• Cleaner, more intuitive data structures

• Better error handling with standard HTTP status codes

• Consolidated endpoints reduce complexity

• Two workflow options: v11 (multi-step) or SearchComplete (single call)

Important: This guide covers migration to the Hotel JSON API, which has two versions:

• Hotel JSON API v11 - Multi-step workflow (Search > Availability > Rules)

• SearchComplete API - Single consolidated endpoint (recommended)

This guide shows both paths so you can choose the best approach for your needs.

Overview of GWS Hotel Booking Flow

As a quick refresher, GWS is a SOAP-based API using XML payloads:

Key Characteristics:

• Protocol: SOAP over HTTP

• Data Format: XML

• Authentication: SOAP headers with credentials

• Multiple SOAP operations for different functions

• Complex nested XML structures

• Property details require separate call

• Galileo-specific codes and formats

Overview of Hotel JSON API

The Hotel JSON API is a modern RESTful API with two workflow options:

Option 1: JSON API v11 (Multi-Step Workflow)

Option 2: SearchComplete (Single Call)

JSON API Characteristics:

• Protocol: RESTful HTTP

• Data Format: JSON

• Authentication: OAuth 2.0 Bearer tokens

• Consolidated RESTful endpoints

• Simplified request/response structures

• Property details included in search response

• Standard HTTP status codes for errors

• Industry-standard codes and formats

Recommendation: Use SearchComplete for new implementations. It reduces API calls from 3 to 1, simplifies state management, and provides better performance.

Key Differences Between GWS and JSON API

Summary Comparison

Authentication Migration

GWS Authentication

GWS uses WS-Security with username/password in SOAP headers:

<soap:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>USERNAME</wsse:Username>
      <wsse:Password>PASSWORD</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
  <Header_v52_0:BranchCode>P1234567</Header_v52_0:BranchCode>
</soap:Header>

JSON API Authentication

JSON API uses OAuth 2.0. First, obtain an access token (see Authentication):

Then use the token in all API requests:

Key Differences:

• OAuth tokens expire in 24 hours and must be refreshed

• Access group (PCC) is now in XAUTH_TRAVELPORT_ACCESSGROUP header

• No username/password in each authorization request - use token instead

• Token management required (cache tokens, refresh before expiry)

• More secure - tokens can be revoked without changing credentials

Migration Path 1: JSON API v11 (Multi-Step Workflow)

This section shows how to migrate several GWS calls to the JSON API v11 endpoints. This maintains the familiar multi-step workflow while modernizing the technology.

Step 1: Hotel Search

GWS: HotelAvailability

<soapenv:Envelope>
    <soapenv:Body>
        <HotelAvailability>
            <CityCode>SFO</CityCode>
            <CheckInDate>2025-03-15</CheckInDate>
            <CheckOutDate>2025-03-17</CheckOutDate>
            <NumAdults>2</NumAdults>
            <NumRooms>1</NumRooms>
            <RateCategory>STANDARD</RateCategory>
        </HotelAvailability>
    </soapenv:Body>
</soapenv:Envelope>

JSON API v11:

{
 "PropertiesQuerySearch": {
  "@type": "PropertiesQuerySearch",
  "CheckInDate": "2025-03-15",
  "CheckOutDate": "2025-03-17",
  "SearchBy": {
   "@type": "SearchByIATACode",
   "IATACode": "SFO"
  },
  "RoomStayCandidate": [
   {
    "GuestCount": {
     "AdultCount": 2
    }
   }
  ]
 }
}

Key Changes:

• JSON instead of XML - simpler structure

• SearchBy object for location (supports coordinates, city, airport)

• RoomStayCandidate structure replaces NumAdults/NumRooms Property details (images, amenities) included in response

• Property details (images, amenities) included in response

• No separate HotelPropertyDescription needed

Step 2: Hotel Availability

GWS: Availability in Search Response

In GWS, availability is returned in the HotelAvailability response.

JSON API v11: Hotel Availability API

JSON API v11 requires a separate availability call:

{
 "CatalogOfferingsQueryHospitality": {
  "@type": "CatalogOfferingsQueryHospitality",
  "PropertyIdentifier": [
   "TVPT-12345",
   "TVPT-67890"
  ],
  "HotelStay": {
   "CheckInDate": "2025-03-15",
   "CheckOutDate": "2025-03-17"
  },
  "GuestCount": {
   "AdultCount": 2
  }
 }
}

Key Changes:

• Separate call required (different from GWS)

• Use PropertyIdentifier from search response

• Returns CatalogOfferingIdentifier needed for rules call

• Rate and room details in response

• More detailed rate breakdown (base, taxes, fees)

Step 3: Rate Rules

GWS: HotelRateDescription

<soapenv:Envelope>
    <soapenv:Body>
        <HotelRateDescription>
            <HotelCode>12345</HotelCode>
            <RatePlanCode>BAR</RatePlanCode>
            <CheckInDate>2025-03-15</CheckInDate>
            <CheckOutDate>2025-03-17</CheckOutDate>
        </HotelRateDescription>
    </soapenv:Body>
</soapenv:Envelope>

JSON API v11:

{
 "BuildFromCatalogOfferingsRequestHospitality": {
  "CatalogOfferingIdentifier": "abc123-def456-ghi789"
 }
}

Key Changes:

• Use CatalogOfferingIdentifier from availability response

• Returns cancellation policies, deposit requirements, guarantees

• Simpler JSON structure vs XML

• More detailed policy information than GWS

• Standard date/time formats (ISO 8601)

Migration Path 2: SearchComplete (Single Call)

Recommended Approach

SearchComplete consolidates search, availability, and rules into a single endpoint. This is the recommended approach for new implementations as it reduces complexity and improves performance.

GWS: Three Separate SOAP Calls

In GWS, you make:

• HotelAvailability - Search and get availability

• HotelPropertyDescription - Get property details

• HotelRateDescription - Get rate rules and policies

SearchComplete: Single REST Call

One call replaces all three

{
 "stayDetails": {
  "checkInDateLocal": "2025-03-15",
  "checkOutDateLocal": "2025-03-17",
  "guests": {
   "numberOfAdults": 2,
   "numberOfChildren": 0
  }
 },
 "propertyFilter": {
  "location": {
   "iataCode": "SFO"
  },
  "returnOnlyAvailableProperties": true,
  "returnRateSummaryInfo": true
 },
 "requestedCurrency": "USD"
}

What You Get Back:

• Properties with all details (name, address, amenities, images)

• Available rates with complete pricing

• Room type information

• Rate rules including cancellation and deposit policies

• All in one unified JSON response

Benefits vs GWS:

• One API call instead of three - reduced latency

• No need to manage state between calls

• Simpler error handling (one point of failure)

• Cleaner JSON structure vs XML

• Built-in caching for better performance

• Industry-standard codes instead of GWS-specific formats

Booking Workflow Changes

The booking, retrieval, modification, and cancellation flows are similar between GWS and JSON API, with the main differences being REST/JSON vs SOAP/XML format and modern data structures.

Create Booking

Key Changes:

• Use propertyKey and rateKey from search response

• Payment object structure simplified

• Guest details in cleaner JSON format

• Response includes reservation confirmation immediately

• Standard confirmation codes instead of GWS-specific formats

Retrieve Booking

Key Changes:

• RESTful GET instead of SOAP request

• Confirmation ID in URL path

• Complete reservation details in JSON response

• Standardized status codes

Modify Booking

Key Changes:

• RESTful PUT for updates

• Send only changed fields

• Response includes updated reservation

• Clearer modification rules and restrictions

Cancel Booking

Key Changes:

• RESTful DELETE for cancellation

• Cancellation penalties in response

• Standard HTTP status codes for success/failure

• Detailed cancellation confirmation

General Changes and Considerations

Error Handling

JSON API error response example:

{
 "errors": [
  {
   "code": "INVALID_REQUEST",
   "message": "Check-in date must be in the future",
   "field": "stayDetails.checkInDateLocal"
  }
 ]
}

Request/Response Size

JSON API payloads are typically 40-60% smaller than equivalent SOAP/XML:

• Faster transmission over network

• Reduced bandwidth costs

• Easier to parse and process

• More human-readable for debugging

• Less verbose than GWS XML structure

Development Tools

Performance Improvements

• OAuth token caching reduces authentication overhead

• JSON parsing is faster than XML

• SearchComplete API includes intelligent caching

• RESTful architecture enables better CDN usage

• Smaller payload sizes improve network performance

• Reduced round trips with SearchComplete

Migration Strategy Recommendations

• Phase 1: Set up OAuth 2.0 authentication and test token management

• Phase 2: Create code/format mapping (GWS codes to industry standards)

• Phase 3: Migrate search functionality (choose v11 or SearchComplete)

• Phase 4: Test search thoroughly with various criteria

• Phase 5: Migrate booking workflow (create, retrieve, modify, cancel)

• Phase 6: Update error handling for HTTP status codes

• Phase 7: Performance testing and optimization

• Phase 8: Production cutover with monitoring

Conclusion

Migrating from GWS to the Hotel JSON API modernizes your integration with significant benefits:

Technical Benefits:

• Modern REST/JSON architecture vs legacy SOAP/XML

• Industry-standard codes and formats

• OAuth 2.0 authentication with better security

• Significantly smaller payloads and faster performance

• Better development tools and documentation

• Standard HTTP status codes for errors

• Choice of workflow: v11 multi-step or SearchComplete single call

Business Benefits:

• Faster development and time-to-market

• Reduced bandwidth and infrastructure costs

• Easier maintenance and debugging

• Better performance for end users

• Modern architecture supporting future enhancements

• Alignment with industry standards

Recommendation: For new implementations, we strongly recommend using SearchComplete API. It provides the simplest integration path with best performance and represents the biggest leap forward from GWS. For existing v11 implementations, SearchComplete offers a clear upgrade path with significant benefits.

The Travelport team is available to assist with your migration. Contact your account manager or visit the developer portal for additional resources and support.