# Migration Guide: Galileo Web Services (GWS) to TripServices Stays API

This document provides general information about the Stays API. For the most current endpoints and examples, see [Authentication](/docs/getting-started/authentication), [Stays Endpoints](/docs/stays/general/stays-api-endpoints), and the API References.

## Introduction

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

Key Benefits of the TripServices 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 TripServices Stays API, which has two versions:

- TripServices Stays 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:

| Step | SOAP Action | What It Does |
|  --- | --- | --- |
| 1. Search

 | HotelAvailability | Find hotels with availability by location |
| 1. Details

 | HotelPropertyDescription | Get property details and
amenities |
| 1. Rules

 | HotelRateDescription | Get rate rules and
cancellation policies |


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 TripServices Stays API

The TripServices Stays API is a modern RESTful API with two workflow options:

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

| Step | Endpoint | What It Does |
|  --- | --- | --- |
| 1. Search

 | POST /search/properties/search | Find hotels with property info |
| 1. Availability

 | POST /availability/catalogofferingshospitality | Get available rates |
| 1. Rules

 | /rules/offershospitality/buildfromcatalogoffering | Get rate policies |


Option 2: SearchComplete (Single Call)

| Step | Endpoint | What It Does |
|  --- | --- | --- |
| Search | /search/searchcomplete | Get everything - properties, rates, AND rules |


TripServices 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 TripServices API

Summary Comparison

| Feature | GWS (SOAP) | TripServices API |
|  --- | --- | --- |
| Protocol | SOAP/XML | REST/JSON |
| Authentication | SOAP headers with credentials | OAuth 2.0 Bearer tokens |
| Request Format | XML with Galileo-specific structure | JSON with industry-standard
structure |
| Response Format | XML | JSON |
| Error Handling | SOAP Faults | HTTP status codes + JSON errors |
| Property Details | Separate HotelPropertyDescription call | Included in search response |
| API Calls for Shopping | 2-3 calls (Availability, Description, Rules) | v11: 3 calls /
SearchComplete: 1 call |
| Endpoints | Multiple SOAP operations | RESTful endpoints |
| Documentation | GWS
specifications | OpenAPI/Swagger |
| Code Format | Galileo-specific codes | Industry-standard codes |


## Authentication Migration

GWS Authentication

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


```xml
<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>
```

TripServices API Authentication

TripServices API uses OAuth 2.0. First, obtain an access token (see [Authentication](/docs/getting-started/authentication)):


```xml
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &
client_id=YOUR_CLIENT_ID &
client_secret=YOUR_CLIENT_SECRET
```

Then use the token in all API requests:


```xml
Authorization: Bearer YOUR_ACCESS_TOKEN
XAUTH_TRAVELPORT_ACCESSGROUP: YOUR_PCC
```

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: TripServices API v11 (Multi-Step Workflow)

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

### Step 1: Hotel Search

GWS: HotelAvailability


```xml
<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>
```

TripServices API v11:


```json
{
 "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.

TripServices API v11: Hotel Availability API

TripServices 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


```xml
<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>
```

TripServices API v11:


```json
{
 "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 TripServices 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

| GWS | TripServices API |
|  --- | --- |
| SOAP Faults with error codes | HTTP status codes (400, 401, 404, 500, etc.) |
| Error details in XML structure | Error details in JSON errors array |


TripServices API error response example:


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

Request/Response Size

TripServices 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

| GWS | TripServices API |
|  --- | --- |
| GWS
specifications/documentation | OpenAPI/Swagger documentation |
| SoapUI for testing | Postman, Insomnia, curl for testing |


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 TripServices Stays 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.

[Provide feedback about this documentation](mailto:john.callaway@travelport.com?subject=JSON%20API%20Hotel%20Feedback)

This link does not provide Help Desk support. If you need immediate assistance with Travelport APIs, please create a support request in  My Travelport  or use your normal support path.