Technical Integration

Overview

This guide provides technical details for integrating with the Flight Availability Search API v2.

Authentication Setup

OAuth 2.0

The API uses OAuth 2.0 for authentication. Include your access token in the Authorization header:

Authorization: Bearer <your_access_token>

Each API key is linked to an agent profile that determines visible flights and fares based on NewSkies role permissions.

AgentName Mapping

Important: After creating your app in the developer portal, you must request AgentName mapping:

1. Note your app name from the developer portal
2. Email yoda@tui.de with:
   • Your app name (as shown in the developer portal)
   • The AgentName you need (provided by the API team)

Without proper mapping, your API requests will fail with a 401 Unauthorized error.

Integration Steps

1. Obtain Credentials

Contact your API administrator to obtain OAuth 2.0 credentials for the appropriate environment.

2. Test Connectivity

Test basic connectivity using a simple search request:

curl -X GET "https://test.api.tui/flight/newskies/availability/v2/search?outboundStartDate=2024-06-01&outboundEndDate=2024-06-30&departureStationCodes=BRU&arrivalStationCodes=ALC&tripType=0" \
  -H "Authorization: Bearer <your_access_token>"

3. Implement Search Logic

Implement search functionality in your application using the query parameters documented in the API Details tab.

4. Handle Responses

Parse the grouped response structure:

{
  "groups": [
    {
      "name": "BRU-ALC",
      "flights": [...]
    }
  ]
}

5. Error Handling

Implement proper error handling for:

• 400: Invalid parameters
• 401: Authentication failure
• 500: Server errors

Best Practices

Date Range Selection

Use reasonable date ranges (1-3 months) for optimal performance.

Result Limiting

Use LimitGroups and LimitFlights to control response size and improve performance.

Grouping Strategy

• Use GroupBy=0 (OriginDestination) for route-based displays
• Use GroupBy=1 (Date) for calendar-based displays

Error Handling

• Always check response status codes
• Handle 401 errors by refreshing access token
• Implement retry logic for 500 errors with exponential backoff

Caching

Cache results appropriately based on your use case. Consider that availability changes frequently.

Request Validation

The API validates all requests. Common validation errors:

• Missing required parameters (outboundStartDate, outboundEndDate, tripType)
• Invalid date format (must be yyyy-MM-dd)
• Missing inbound dates when tripType=1
• Invalid trip type value (must be 0 or 1)
• Invalid GroupBy value (must be 0 or 1)

Response Structure

Grouped Results

Results are organized into groups based on the GroupBy parameter:

• GroupBy=0: Groups by origin-destination pair (e.g., "BRU-ALC")
• GroupBy=1: Groups by date (e.g., "2024-06-15")

Flight Data

Each flight contains:

• Schedule information (departure/arrival times, duration)
• Route information (airports, countries)
• Carrier information (marketing and operating carriers)
• Availability (number of seats)
• Journey keys (plain and encrypted)
• Stopover information (if applicable)
• Fare options

Fare Data

Each fare contains:

• Fare basis code and class information
• Pricing for adults, children, and infants
• Gross and net prices
• Taxes, fees, and surcharges
• Currency code
• Fare keys (plain and encrypted)

Environment-Specific Configuration

Configure your application for different environments:

Environment	Base URL	Purpose
Development	https://dev.api.tui/flight/newskies/availability/v2	Development testing
Test	https://test.api.tui/flight/newskies/availability/v2	Integration testing
Pre-Production	https://pre-prod.api.tui/flight/newskies/availability/v2	Pre-production validation
Production	https://prod.api.tui/flight/newskies/availability/v2	Live environment

Code Examples

See the Examples tab for complete code samples in multiple programming languages.

Troubleshooting

401 Unauthorized

• Verify your access token is valid
• Check token expiration
• Ensure Authorization header is properly formatted
• Verify your app name has been mapped to an AgentName (contact yoda@tui.de if unsure)

400 Bad Request

• Check all required parameters are provided
• Verify date format is yyyy-MM-dd
• Ensure inbound dates are provided for round-trip searches
• Validate parameter values are within acceptable ranges

Empty Results

• Verify departure/arrival codes or countries are provided
• Check date ranges are valid
• Confirm flights exist for the specified criteria

Slow Response Times

• Reduce date range
• Use LimitGroups and LimitFlights parameters