Functional Requirements Specification¶

Document Version: 1.0 Date: 2024-11-23 Module: tqamds (Amadeus Integration Module) Platform: TQPro Travel Platform

Table of Contents¶

Introduction
Scope
Functional Requirements
Use Cases
API Specifications
Data Requirements
Non-Functional Requirements
Constraints and Assumptions

1. Introduction¶

1.1 Purpose¶

This document specifies the functional requirements for the TQAMDS module, which provides travel content aggregation capabilities through integration with Amadeus travel APIs. The module enables travel search, booking, and reference data access for flights and hotels.

1.2 Intended Audience¶

Product Managers
Business Analysts
Quality Assurance Teams
Integration Partners
API Consumers
System Architects

1.3 Product Overview¶

The TQAMDS module provides: - Flight Search - Search and price flight offers - Flight Booking - Create and manage flight reservations - Hotel Discovery - Find hotels by location or name - Hotel Shopping - Search hotel availability and pricing - Reference Data - Access airline and airport information

2. Scope¶

2.1 In Scope¶

Flight Services: - Flight availability search (one-way, round-trip, multi-city) - Flight offer pricing confirmation - Flight booking creation (PNR generation) - Flight booking retrieval - Flight booking cancellation

Hotel Services: - Hotel reference data search - Hotel availability and pricing search - Hotel name autocomplete

Reference Data Services: - Airline information lookup - Airport information lookup - Location search

Supporting Capabilities: - Session management - Data caching for performance - Multi-currency support - Multi-language support

2.2 Out of Scope¶

The following are explicitly NOT included in this module: - Payment processing - Ticket issuance - Customer profile management - Loyalty program integration - Car rental services - Travel insurance - Seat selection - Ancillary services (meals, baggage) - Hotel booking creation - Multi-provider aggregation (single provider: Amadeus)

3. Functional Requirements¶

3.1 Flight Search Requirements¶

FR-FS-001: Basic Flight Search¶

Requirement: The system shall allow users to search for flight offers between two locations.

Inputs: - Origin airport code (required, IATA 3-letter code) - Destination airport code (required, IATA 3-letter code) - Departure date (required, ISO 8601 date format YYYY-MM-DD) - Number of adult passengers (required, range: 1-9) - Return date (optional, for round-trip searches) - Number of children (optional, range: 0-9) - Number of infants (optional, range: 0-9)

Outputs: - List of available flight offers - Each offer contains: - Unique offer identifier - Total price with currency - Itinerary details (outbound and return if applicable) - Available booking classes - Airline information - Aircraft type - Flight duration

Business Rules: - At least one adult passenger must be specified - Total passengers (adults + children + infants) must not exceed 9 - Departure date must be in the future - Return date (if provided) must be after departure date - System shall return up to 250 offers by default

Requirement: The system shall support filtering of flight search results.

Filter Options: - Travel class (Economy, Premium Economy, Business, First) - Non-stop flights only (true/false) - Maximum price threshold - Maximum number of results

Business Rules: - Filters are applied server-side during search - Multiple filters can be combined - Invalid filter values shall be rejected with error message

FR-FS-003: Flight Itinerary Details¶

Requirement: Each flight offer shall provide detailed itinerary information.

Itinerary Information: - Per Itinerary (outbound/return): - Total journey duration - Number of flight segments - List of segments with: - Departure airport, terminal, and time - Arrival airport, terminal, and time - Carrier code and name - Flight number - Aircraft type - Number of stops - Segment duration - Operating carrier (if codeshare)

FR-FS-004: Flight Pricing Details¶

Requirement: Each flight offer shall provide detailed pricing breakdown.

Pricing Information: - Per Offer: - Total price - Base fare - Currency code - Tax and fee breakdown

Per Passenger Type:
Passenger type (ADULT, CHILD, INFANT)
Fare option
Base price
Total price
Per Segment:
Cabin class
Booking class
Fare basis code
Branded fare name (if available)
Available seats in class

Business Rules: - All prices shall be provided in the requested currency or default currency - Prices include all mandatory taxes and fees - Infant pricing may be percentage of adult fare or fixed fee

FR-FS-005: Flight Price Confirmation¶

Requirement: The system shall allow confirmation of flight offer pricing before booking.

Inputs: - Flight offer identifier from search results

Outputs: - Updated pricing (may differ from search results) - Booking requirements (required passenger fields) - Last ticketing date - Instant ticketing requirement flag - Validity period

Business Rules: - Price confirmation must be performed before booking - Confirmed price is guaranteed for limited time (typically 10 minutes) - Booking requirements vary by route and airline - System shall indicate which passenger fields are mandatory

3.2 Flight Booking Requirements¶

FR-FB-001: Create Flight Booking¶

Requirement: The system shall allow creation of flight bookings with passenger details.

Inputs: - Priced flight offer (from price confirmation) - Passenger details for each traveler: - Passenger type (ADULT, CHILD, INFANT) - First name (required) - Last name (required) - Date of birth (required or optional based on booking requirements) - Gender (required or optional based on booking requirements) - Contact information: - Email address (required or optional) - Phone number (required or optional) - Country calling code - Travel documents (required or optional based on route): - Document type (PASSPORT, IDENTITY_CARD) - Document number - Expiry date - Issuing country - Nationality

Outputs: - Booking confirmation with: - Booking order ID (PNR) - Booking status - Passenger details as booked - Flight itinerary details - Pricing details - Associated booking records (airline PNRs) - Ticketing office ID

Business Rules: - All required passenger fields (per booking requirements) must be provided - Passenger names must match travel documents exactly - Email address must be valid format - Phone number must be valid format with country code - Passport must be valid for at least 6 months beyond travel date (validation by airline) - Booking creates a confirmed reservation (PNR) immediately - System shall reject booking if price has changed significantly

FR-FB-002: Retrieve Flight Booking¶

Requirement: The system shall allow retrieval of booking details by booking order ID.

Inputs: - Booking order ID (PNR)

Outputs: - Complete booking details (same structure as booking creation output) - Current booking status

Business Rules: - Only valid booking order IDs shall return results - Invalid or non-existent booking IDs shall return appropriate error - System shall return most current booking information

FR-FB-003: Cancel Flight Booking¶

Requirement: The system shall allow cancellation of flight bookings.

Inputs: - Booking order ID (PNR)

Outputs: - Cancellation confirmation - Cancellation timestamp

Business Rules: - Only confirmed bookings can be cancelled - Already cancelled bookings shall return appropriate error - Cancellation is immediate and irreversible - Refund processing is outside system scope - System shall not allow cancellation of ticketed bookings (depends on airline policy)

3.3 Hotel Search Requirements¶

FR-HS-001: Hotel Search by City¶

Requirement: The system shall allow searching for hotels within a city.

Inputs: - City code (required, IATA 3-letter code) - Search radius (optional, numeric value) - Radius unit (optional, KM or MILE, default: KM) - Hotel ratings filter (optional, comma-separated: 1,2,3,4,5) - Hotel source (optional, GDS or ALL, default: ALL)

Outputs: - List of hotels with: - Hotel identifier (Amadeus hotel ID) - Hotel name - Chain code - IATA code - GPS coordinates (latitude, longitude) - Full address (street, city, state, country, postal code) - Distance from city center - Distance unit

Business Rules: - City code must be valid IATA code - Search radius defaults to city boundaries if not specified - Results sorted by distance from city center - Maximum 250 hotels returned per search - Invalid city codes shall return error

FR-HS-002: Hotel Search by Geographic Coordinates¶

Requirement: The system shall allow searching for hotels near GPS coordinates.

Inputs: - Latitude (required, decimal degrees) - Longitude (required, decimal degrees) - Search radius (optional, default: 5 KM) - Radius unit (optional, KM or MILE, default: KM) - Hotel ratings filter (optional, comma-separated values) - Hotel source (optional, GDS or ALL)

Outputs: - List of hotels (same structure as city search) - Distance calculated from provided coordinates

Business Rules: - Valid latitude range: -90 to +90 - Valid longitude range: -180 to +180 - Results sorted by distance from coordinates (nearest first) - Search radius maximum: 300 KM or 200 MILE

FR-HS-003: Hotel Search by Name¶

Requirement: The system shall provide hotel name autocomplete/search functionality.

Inputs: - Keyword (required, minimum 3 characters) - Country code (optional, ISO 2-letter code) - Hotel sub-type (optional, HOTEL_GDS or HOTEL_LEISURE) - Language code (optional, ISO 2-letter code) - Maximum results (optional, default: 20)

Outputs: - List of matching hotels with: - Hotel identifier - Hotel name - Chain code - Location information (city, country) - GPS coordinates

Business Rules: - Minimum keyword length: 3 characters - Search is case-insensitive - Partial matching supported - Results sorted by relevance - Maximum 100 results per search

FR-HS-004: Hotel Lookup by IDs¶

Requirement: The system shall allow retrieval of hotel details by hotel IDs.

Inputs: - Hotel IDs (required, comma-separated, maximum 250 IDs)

Outputs: - List of hotels with complete reference data - Hotels not found are omitted from results

Business Rules: - All hotel IDs must be valid Amadeus hotel IDs - Maximum 250 hotel IDs per request - Invalid hotel IDs are silently ignored

3.4 Hotel Availability and Pricing Requirements¶

FR-HA-001: Hotel Offer Search¶

Requirement: The system shall allow searching for hotel availability and pricing.

Inputs: - Hotel IDs (required, comma-separated, maximum 250 hotels) - Check-in date (required, ISO 8601 format YYYY-MM-DD) - Number of adults (required, range: 1-9) - Check-out date (optional, defaults to check-in + 1 day) - Number of rooms (optional, range: 1-9, default: 1) - Price range filter (optional, format: "min-max") - Currency code (optional, ISO 3-letter code) - Payment policy filter (optional, NONE, DEPOSIT, GUARANTEE) - Board type filter (optional, ROOM_ONLY, BREAKFAST, HALF_BOARD, FULL_BOARD, ALL_INCLUSIVE) - Include closed hotels (optional, default: false) - Best rate only (optional, default: true) - View detail level (optional, FULL, LIGHT, NONE) - Language code (optional, ISO 2-letter code)

Outputs: - List of hotel offers with: - Offer identifier - Hotel information: - Hotel ID and name - Chain code - City code - GPS coordinates - Availability status - Stay dates (check-in, check-out) - Room configuration: - Room quantity - Guest count - Room details: - Room type and category - Bed configuration (number and type) - Room description - Rate information: - Rate code - Rate family - Category - Board type (meal plan) - Pricing: - Currency - Total price - Base price - Average daily rate - Tax breakdown - Policies: - Cancellation policy (type, deadline, description) - Payment policy (type, methods accepted) - Guarantee requirements (methods, credit cards) - Deposit requirements (amount, deadline, methods) - Prepayment requirements (amount, deadline, methods) - Hold time deadline - Check-in/check-out times - Commission information (if available) - Offer description

Business Rules: - Check-in date must be in the future - Check-out date must be after check-in date - Maximum stay duration: typically 30 days (varies by hotel) - Minimum stay: 1 night - Number of adults must be at least 1 per room - Price range filter: both min and max must be positive numbers - Currency must be supported by hotel - Best rate only returns single lowest offer per hotel - Full view includes detailed room descriptions and policy text - Results may include multiple offers per hotel (different room types, rates)

FR-HA-002: Retrieve Specific Hotel Offer¶

Requirement: The system shall allow retrieval of specific hotel offer details by offer ID.

Inputs: - Offer ID (required, from previous search) - Language code (optional, ISO 2-letter code)

Outputs: - Complete hotel offer details (same structure as search output) - Most current pricing and availability

Business Rules: - Offer ID must be valid and not expired - Expired offers return appropriate error - Pricing may differ from original search - Offer validity typically 10-30 minutes

3.5 Reference Data Requirements¶

FR-RD-001: Airline Information Lookup¶

Requirement: The system shall provide airline information by airline codes.

Inputs: - Airline codes (required, comma-separated IATA 2-letter codes)

Outputs: - List of airlines with: - IATA code (2-letter) - ICAO code (4-letter) - Business name (official legal name) - Common name (brand name) - Airline type

Business Rules: - IATA codes are case-insensitive - Invalid codes are silently ignored - Maximum 100 codes per request

FR-RD-002: Airport and Location Search¶

Requirement: The system shall provide airport and city search functionality.

Inputs: - Keyword (optional, search term) - Location sub-type (optional, AIRPORT or CITY)

Outputs: - List of locations with: - Location name - Detailed name - IATA code - Location type and sub-type - City name and code - Country name and code - Region code

Business Rules: - Minimum keyword length: 3 characters - Search supports partial matching - Results include airports and cities - Results sorted by relevance

FR-RD-003: Airport Lookup by Code¶

Requirement: The system shall allow direct airport lookup by IATA code.

Inputs: - Airport code (required, IATA 3-letter code)

Outputs: - Airport details: - IATA code - Airport name - Detailed name - City code and name - Country code and name - Region code

Business Rules: - Code is case-insensitive - Invalid codes return null/not found - Results cached locally for performance

4. Use Cases¶

4.1 Use Case: Book a Round-Trip Flight¶

Actor: Travel Agent / End User

Preconditions: - User has valid session - Travel dates are known - Passenger information is available

Main Flow: 1. User initiates flight search with: - Origin: JFK (New York) - Destination: LHR (London) - Departure: 2024-12-15 - Return: 2024-12-22 - Passengers: 2 adults - Class: Economy

System searches for available flights
System returns list of flight offers with pricing
User reviews offers and selects preferred option
User requests price confirmation for selected offer
System confirms pricing and returns booking requirements
User provides passenger details:
Passenger 1: John Smith, DOB: 1985-03-15, Passport: AB123456
Passenger 2: Jane Smith, DOB: 1987-06-20, Passport: CD789012
Contact: john.smith@email.com, +1-555-123-4567
User submits booking request
System creates booking and returns PNR: ABC123
User receives booking confirmation

Postconditions: - Flight booking is confirmed with PNR - Booking can be retrieved by PNR - Booking appears in booking management system

Alternative Flows: - 3a. No flights available: - System returns empty result set - User adjusts search criteria

6a. Price has increased:
System returns new higher price
User decides to accept or cancel
8a. Passenger information incomplete:
System returns validation error
User corrects information and resubmits

Exception Flows: - Invalid origin/destination code → System returns error - Past travel date → System returns error - Invalid passenger count → System returns error - API timeout → System returns timeout error

4.2 Use Case: Find Hotel in City¶

Actor: Travel Agent / End User

Preconditions: - User has valid session - Destination city is known

Main Flow: 1. User searches for hotels: - City: PAR (Paris) - Ratings: 4,5 (4 and 5 star only) - Radius: 10 KM

System searches hotel reference data
System returns list of hotels with:
Hotel names
Addresses
GPS coordinates
Distance from city center
User reviews hotel list
User selects multiple hotels for availability check
User searches hotel offers:
Selected hotel IDs
Check-in: 2024-12-20
Check-out: 2024-12-23
Guests: 2 adults
Rooms: 1
Board type: BREAKFAST
System returns available offers with pricing
User reviews offers and prices
User selects desired offer

Postconditions: - User has identified available hotel room - User has current pricing information - Offer ID available for future booking (out of scope)

Alternative Flows: - 3a. No hotels found in city: - System returns empty result set - User expands search radius or changes criteria

7a. No availability for selected dates:
System returns empty or partial results
User adjusts dates or hotel selection

Exception Flows: - Invalid city code → System returns error - Invalid date range → System returns error - Check-in date in past → System returns error

4.3 Use Case: Hotel Name Autocomplete¶

Actor: Travel Agent / End User

Preconditions: - User is entering hotel search - User knows partial hotel name

Main Flow: 1. User types "Hilt" in hotel search field 2. System searches hotels by keyword "Hilt" 3. System returns matching hotels: - Hilton Paris Opera - Hilton London Metropole - Hilton New York Midtown - (etc.)

User sees suggestions and continues typing or selects from list
User types "Hilton Paris"
System refines search with "Hilton Paris"
System returns:
Hilton Paris Opera
Hilton Paris Charles de Gaulle Airport
Hilton Paris La Defense
User selects "Hilton Paris Opera"
System populates hotel ID for further operations

Postconditions: - User has selected specific hotel - Hotel ID available for availability search

Alternative Flows: - 3a. No matches found: - System returns empty result - User adjusts spelling or search term

4.4 Use Case: Retrieve and Cancel Booking¶

Actor: Travel Agent

Preconditions: - Booking exists with PNR ABC123 - User has authorization to manage booking

Main Flow: 1. User enters PNR: ABC123 2. System retrieves booking details 3. System displays: - Passenger names - Flight itinerary - Booking status: CONFIRMED - Pricing information

User reviews booking
User requests cancellation
System confirms cancellation request
User confirms cancellation
System cancels booking with airline
System returns cancellation confirmation

Postconditions: - Booking status changed to CANCELLED - Cancellation timestamp recorded - Booking no longer valid for travel

Alternative Flows: - 2a. PNR not found: - System returns not found error - User verifies PNR and retries

Exception Flows: - Booking already cancelled → System returns error - Booking already ticketed → System returns error (cannot cancel) - Airline API error → System returns cancellation failed error

4.5 Use Case: Multi-City Flight Search¶

Actor: Travel Agent

Preconditions: - User needs complex multi-city itinerary - All cities and dates known

Main Flow: 1. User initiates multi-city search: - Segment 1: NYC → PAR, 2024-12-15 - Segment 2: PAR → ROM, 2024-12-18 - Segment 3: ROM → NYC, 2024-12-22 - Passengers: 1 adult

System searches for available itineraries
System returns combined offers with:
All three segments together
Total journey pricing
Connection times
Layover information
User reviews complete itinerary
User confirms pricing
User proceeds to booking (as per Use Case 4.1)

Postconditions: - User has found multi-city itinerary - Single PNR covers all segments - Pricing is combined for all segments

4.6 Use Case: Search Flights with Filters¶

Actor: End User

Preconditions: - User has specific preferences - Basic search parameters known

Main Flow: 1. User searches flights: - Origin: LAX - Destination: SFO - Date: 2024-12-10 - Passengers: 1 adult - Filters: - Non-stop only: true - Travel class: BUSINESS - Max price: 500 USD

System applies filters during search
System returns only:
Non-stop flights
Business class only
Price ≤ $500
User reviews filtered results
User finds suitable flight quickly

Postconditions: - User sees only relevant results - Search time reduced - User satisfaction improved

Alternative Flows: - 3a. No results match filters: - System returns empty result set - User relaxes filter criteria

5. API Specifications¶

5.1 Flight Search API¶

5.1.1 Search Flight Offers¶

Operation: getFlightOffers

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | originLocationCode | String | Yes | Origin airport IATA code | 3-letter code (e.g., JFK) | | destinationLocationCode | String | Yes | Destination airport IATA code | 3-letter code (e.g., LHR) | | departureDate | String | Yes | Departure date | YYYY-MM-DD format | | returnDate | String | No | Return date for round-trip | YYYY-MM-DD format | | adults | Integer | Yes | Number of adults | 1-9 | | children | Integer | No | Number of children | 0-9 | | infants | Integer | No | Number of infants | 0-9 | | travelClass | String | No | Cabin class | ECONOMY, PREMIUM_ECONOMY, BUSINESS, FIRST | | nonStop | Boolean | No | Direct flights only | true, false | | maxPrice | Number | No | Maximum price filter | Positive number | | max | Integer | No | Maximum results | 1-250 (default: 250) |

Response Structure:

name="__codelineno-0-1" href="#__codelineno-0-1">FlightOfferList: Array of FlightOffer FlightOffer: - id: String (Offer identifier) - source: String (GDS, etc.) - instantTicketingRequired: Boolean - lastTicketingDate: String (ISO 8601 date) - currency: String (ISO currency code) - totalAmount: Number - baseAmount: Number - grandTotal: Number - itineraries: Array of Itinerary Itinerary: - duration: String (ISO 8601 duration) - segments: Array of Segment Segment: - id: String - duration: String - carrierCode: String (IATA airline code) - carrierName: String - flightNumber: String - numberOfStops: Integer - departureAirport: String (IATA code) - departureAirportName: String - departureTerminal: String - departureTime: String (ISO 8601 datetime) - arrivalAirport: String (IATA code) - arrivalAirportName: String - arrivalTerminal: String - arrivalTime: String (ISO 8601 datetime) - paxPricing: Array of TravelerPricing TravelerPricing: - travelerId: String - travelerType: String (ADULT, CHILD, INFANT) - fareOption: String - currency: String - totalPrice: Number - basePrice: Number - segmentFares: Array of SegmentFare SegmentFare: - segmentId: String - cabin: String (ECONOMY, BUSINESS, etc.) - fareBasis: String - brandedFare: String - bookingClass: String - availableSeats: Integer

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | Required parameter not provided | | INVALID_PARAMETER | Parameter value invalid | | INVALID_FORMAT | Date format incorrect | | REMOTE_ERROR | Amadeus API error | | NO_RESULTS | No flights found |

5.1.2 Get Flight Offer Pricing¶

Operation: getFlightOfferPricing

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | flightOffer | FlightOffer | Yes | Offer from search results |

Response Structure:

FlightOfferPricing:
  - flightOffer: FlightOffer (updated pricing)
  - bookingRequirement: BookingRequirement
      BookingRequirement:
        - paxConditions: Array of PaxCondition
            PaxCondition:
              - travelerId: String
              - documentRequired: Boolean
              - documentNumberRequired: Boolean
              - dateOfBirthRequired: Boolean
              - genderRequired: Boolean
        - emailAddressRequired: Boolean
        - phoneNumberRequired: Boolean
        - mobilePhoneNumberRequired: Boolean
        - phoneCountryCodeRequired: Boolean
        - invoiceAddressRequired: Boolean
        - mailingAddressRequired: Boolean
        - postalCodeRequired: Boolean

Error Responses: | Error Code | Description | |------------|-------------| | OFFER_EXPIRED | Offer no longer valid | | PRICE_CHANGED | Price significantly changed | | REMOTE_ERROR | Amadeus API error |

5.2 Flight Booking API¶

5.2.1 Create Flight Booking¶

Operation: createFlightOrder

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pricedOffer | FlightOfferPricing | Yes | Priced offer from pricing API | | passengers | Array of Passenger | Yes | Passenger details |

Passenger Structure:

Passenger:
  - id: String (Reference ID)
  - firstName: String (Given name)
  - lastName: String (Family name)
  - dateOfBirth: String (YYYY-MM-DD, conditional)
  - gender: String (M/F, conditional)
  - contact: Contact
      Contact:
        - emailAddress: String (conditional)
        - phoneNo: String (conditional)
        - countryCode: String (conditional)
  - document: Document (conditional)
      Document:
        - docType: String (PASSPORT, ID_CARD)
        - docNumber: String
        - docExpiryDate: String (YYYY-MM-DD)
        - docNationality: String (ISO country code)
        - docCountry: String (ISO country code)

Response Structure:

FlightBooking:
  - bookingOrderId: String (PNR)
  - queuingOfficeId: String
  - passengers: Array of Passenger
  - offers: Array of FlightOffer
  - records: Array of BookingRecord
      BookingRecord:
        - reference: String (Airline PNR)
        - originSystem: String
        - genTimestamp: String (ISO 8601 datetime)

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PASSENGER_DATA | Required passenger field missing | | INVALID_PASSENGER_DATA | Passenger data validation failed | | OFFER_EXPIRED | Offer no longer available | | BOOKING_FAILED | Booking creation failed | | REMOTE_ERROR | Amadeus API error |

5.2.2 Retrieve Flight Booking¶

Operation: getBooking

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bookingOrderId | String | Yes | Booking order ID (PNR) |

Response Structure:

FlightBooking (same as create response)

Error Responses: | Error Code | Description | |------------|-------------| | NOT_FOUND | Booking not found | | REMOTE_ERROR | Amadeus API error |

5.2.3 Cancel Flight Booking¶

Operation: deleteBooking

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bookingOrderId | String | Yes | Booking order ID (PNR) |

Response: Void (success) or Exception (failure)

Error Responses: | Error Code | Description | |------------|-------------| | NOT_FOUND | Booking not found | | ALREADY_CANCELLED | Booking already cancelled | | CANNOT_CANCEL | Booking cannot be cancelled (ticketed) | | REMOTE_ERROR | Amadeus API error |

5.3 Hotel Reference Data API¶

5.3.1 Get Hotels by City¶

Operation: getHotelsByCity

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | cityCode | String | Yes | IATA city code | 3-letter code (e.g., PAR) | | radius | Integer | No | Search radius | Positive number | | radiusUnit | String | No | Distance unit | KM, MILE (default: KM) | | ratings | String | No | Hotel star ratings | Comma-separated: 1,2,3,4,5 | | hotelSource | String | No | Hotel source type | GDS, ALL (default: ALL) |

Response Structure:

HotelList: Array of Hotel
  Hotel:
    - hotelId: String (Amadeus hotel ID)
    - chainCode: String
    - name: String
    - iataCode: String
    - latitude: Number
    - longitude: Number
    - cityCode: String
    - cityName: String
    - countryCode: String (ISO country code)
    - stateCode: String
    - postalCode: String
    - addressLines: Array of String
    - distance: Number
    - distanceUnit: String (KM, MILE)

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | cityCode not provided | | INVALID_PARAMETER | Invalid city code or parameter | | REMOTE_ERROR | Amadeus API error |

5.3.2 Get Hotels by Geographic Coordinates¶

Operation: getHotelsByGeocode

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | latitude | Number | Yes | Latitude | -90 to +90 | | longitude | Number | Yes | Longitude | -180 to +180 | | radius | Integer | No | Search radius | Default: 5 KM | | radiusUnit | String | No | Distance unit | KM, MILE (default: KM) | | ratings | String | No | Hotel star ratings | Comma-separated: 1,2,3,4,5 | | hotelSource | String | No | Hotel source type | GDS, ALL (default: ALL) |

Response Structure: Same as Get Hotels by City

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | latitude or longitude not provided | | INVALID_PARAMETER | Invalid coordinates or parameter | | REMOTE_ERROR | Amadeus API error |

5.3.3 Search Hotels by Name¶

Operation: searchHotelsByName

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | keyword | String | Yes | Search keyword | Min 3 characters | | countryCode | String | No | Country filter | ISO 2-letter code | | subType | String | No | Hotel type | HOTEL_GDS, HOTEL_LEISURE | | lang | String | No | Language | ISO 2-letter code | | max | Integer | No | Maximum results | Default: 20, Max: 100 |

Response Structure: Same as Get Hotels by City

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | keyword not provided | | INVALID_PARAMETER | keyword too short or invalid | | REMOTE_ERROR | Amadeus API error |

5.3.4 Get Hotels by IDs¶

Operation: getHotelsByIds

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | hotelIds | String | Yes | Hotel identifiers | Comma-separated, max 250 IDs |

Response Structure: Same as Get Hotels by City

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | hotelIds not provided | | INVALID_PARAMETER | Too many IDs or invalid format | | REMOTE_ERROR | Amadeus API error |

5.4 Hotel Availability and Pricing API¶

5.4.1 Search Hotel Offers¶

Operation: searchHotelOffers

Request Parameters: | Parameter | Type | Required | Description | Valid Values | |-----------|------|----------|-------------|--------------| | hotelIds | String | Yes | Hotel identifiers | Comma-separated, max 250 | | checkInDate | String | Yes | Check-in date | YYYY-MM-DD | | adults | Integer | Yes | Number of adults | 1-9 | | checkOutDate | String | No | Check-out date | YYYY-MM-DD (default: checkIn + 1) | | roomQuantity | Integer | No | Number of rooms | 1-9 (default: 1) | | priceRange | String | No | Price filter | "min-max" format | | currency | String | No | Currency code | ISO 3-letter code | | paymentPolicy | String | No | Payment policy | NONE, DEPOSIT, GUARANTEE | | boardType | String | No | Meal plan | ROOM_ONLY, BREAKFAST, HALF_BOARD, FULL_BOARD, ALL_INCLUSIVE | | includeClosed | Boolean | No | Include closed hotels | true, false (default: false) | | bestRateOnly | Boolean | No | Best rate only | true, false (default: true) | | view | String | No | Detail level | FULL, LIGHT, NONE | | lang | String | No | Language | ISO 2-letter code |

Response Structure:

HotelOfferList: Array of HotelOffer
  HotelOffer:
    - offerId: String (Offer identifier)
    - hotelId: String
    - hotelName: String
    - chainCode: String
    - cityCode: String
    - hotelLatitude: Number
    - hotelLongitude: Number
    - available: Boolean
    - checkInDate: String (YYYY-MM-DD)
    - checkOutDate: String (YYYY-MM-DD)
    - roomQuantity: Integer
    - guests: Integer
    - rateCode: String
    - rateFamilyEstimated: String
    - category: String
    - description: String
    - descriptionLang: String
    - boardType: String
    - commission: String
    - currency: String (ISO code)
    - totalAmount: Number
    - baseAmount: Number
    - room: HotelRoom
        HotelRoom:
          - type: String
          - category: String
          - beds: Integer
          - bedType: String
          - description: String
          - descriptionText: String
          - descriptionLang: String
    - price: HotelPrice
        HotelPrice:
          - currency: String
          - total: Number
          - base: Number
          - averageTotal: Number
          - averageBase: Number
    - policies: HotelPolicy
        HotelPolicy:
          - cancellationType: String
          - cancellationDeadline: String (ISO 8601 datetime)
          - cancellationDescription: String
          - paymentType: String
          - guaranteePaymentMethods: Array of String
          - guaranteeCreditCards: Array of String
          - depositPaymentMethods: Array of String
          - depositAmount: Number
          - depositDeadline: String
          - prepayPaymentMethods: Array of String
          - prepayAmount: Number
          - prepayDeadline: String
          - holdTimeDeadline: String
          - checkInTime: String
          - checkOutTime: String

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | Required parameter not provided | | INVALID_PARAMETER | Invalid parameter value | | INVALID_FORMAT | Date format incorrect | | REMOTE_ERROR | Amadeus API error |

5.4.2 Get Hotel Offer by ID¶

Operation: getHotelOfferById

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | offerId | String | Yes | Offer ID from search | | lang | String | No | Language code |

Response Structure: Same as single HotelOffer from search

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | offerId not provided | | NOT_FOUND | Offer not found or expired | | REMOTE_ERROR | Amadeus API error |

5.5 Reference Data API¶

5.5.1 Get Airlines¶

Operation: getAirlines

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | airlineCodes | String | Yes | Comma-separated IATA codes |

Response Structure:

AirlineList: Array of Airline
  Airline:
    - iataCode: String (2-letter code)
    - icaoCode: String (4-letter code)
    - businessName: String (Official name)
    - commonName: String (Brand name)
    - type: String

Error Responses: | Error Code | Description | |------------|-------------| | MISSING_PARAMETER | airlineCodes not provided | | REMOTE_ERROR | Amadeus API error |

5.5.2 Search Locations¶

Operation: getLocations

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | keyword | String | No | Search keyword | | subType | String | No | AIRPORT, CITY |

Response Structure:

LocationList: Array of Location
  Location:
    - name: String
    - detailedName: String
    - iataCode: String
    - type: String
    - subType: String
    - cityName: String
    - cityCode: String
    - countryName: String
    - countryCode: String
    - regionCode: String

Error Responses: | Error Code | Description | |------------|-------------| | INVALID_PARAMETER | Invalid parameter | | REMOTE_ERROR | Amadeus API error |

5.5.3 Get Airport by Code¶

Operation: getAirportByCode

Request Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | code | String | Yes | Airport IATA code |

Response Structure: Single Location object

Error Responses: | Error Code | Description | |------------|-------------| | NOT_FOUND | Airport not found | | REMOTE_ERROR | Amadeus API error |

6. Data Requirements¶

6.1 Data Formats¶

6.1.1 Date and Time Formats¶

Dates: - Format: ISO 8601 date format (YYYY-MM-DD) - Example: 2024-12-25 - Timezone: Dates are local to the relevant airport/hotel

Date-Times: - Format: ISO 8601 datetime format (YYYY-MM-DDTHH:MM:SS) - Example: 2024-12-25T14:30:00 - Timezone: Local time at the relevant location

Durations: - Format: ISO 8601 duration format (PnDTnHnMnS) - Example: PT2H30M (2 hours 30 minutes) - Example: P1DT6H (1 day 6 hours)

6.1.2 Currency Formats¶

Currency Codes: - Format: ISO 4217 3-letter currency code - Examples: USD, EUR, GBP, JPY

Amounts: - Format: Decimal number with up to 2 decimal places - Example: 1234.56 - No currency symbols in numeric values

6.1.3 Location Codes¶

Airport Codes: - Format: IATA 3-letter code - Case: Uppercase - Examples: JFK, LHR, CDG

City Codes: - Format: IATA 3-letter code - Case: Uppercase - Examples: NYC, LON, PAR

Country Codes: - Format: ISO 3166-1 alpha-2 (2-letter code) - Case: Uppercase - Examples: US, GB, FR

Airline Codes: - Format: IATA 2-letter code - Case: Uppercase - Examples: AA, BA, AF

Language Codes: - Format: ISO 639-1 (2-letter code) - Case: Lowercase - Examples: en, fr, de

6.1.4 Passenger Types¶

Valid Values: - ADULT - Age 12 or above - CHILD - Age 2-11 - INFANT - Age under 2

6.1.5 Cabin Classes¶

Valid Values: - ECONOMY - Economy class - PREMIUM_ECONOMY - Premium economy class - BUSINESS - Business class - FIRST - First class

6.1.6 Document Types¶

Valid Values: - PASSPORT - Passport - IDENTITY_CARD - National identity card - TRAVEL_CARD - Travel card - DRIVER_LICENSE - Driver's license (rarely accepted)

6.2 Data Validation Rules¶

6.2.1 Flight Search Validation¶

Origin/Destination Codes: - Must be valid 3-letter IATA codes - Cannot be the same (origin ≠ destination) - Case-insensitive but normalized to uppercase

Dates: - Departure date must be today or future date - Return date (if provided) must be after departure date - Maximum advance booking: typically 331 days

Passengers: - Adults: 1-9 (at least one adult required) - Children: 0-9 - Infants: 0-9 (cannot exceed number of adults) - Total passengers: 1-9

Price: - Maximum price must be positive number - Expressed in requested currency

6.2.2 Booking Validation¶

Passenger Names: - First name: 1-56 characters, letters and spaces only - Last name: 1-56 characters, letters and spaces only - Must match passport exactly - No special characters except hyphens and apostrophes

Date of Birth: - Format: YYYY-MM-DD - Must be in the past - Must match passenger type age range

Contact Information: - Email: Valid email format (RFC 5322) - Phone: Valid international format with country code - Country code: Valid calling code (e.g., +1, +44)

Travel Documents: - Document number: Alphanumeric, 6-20 characters - Expiry date: Must be at least 6 months after return date - Nationality: Valid ISO country code - Issuing country: Valid ISO country code

6.2.3 Hotel Search Validation¶

City Code: - Must be valid 3-letter IATA city code - Case-insensitive

Geographic Coordinates: - Latitude: -90 to +90 decimal degrees - Longitude: -180 to +180 decimal degrees - Precision: Up to 6 decimal places

Search Radius: - Minimum: 0 (hotel location) - Maximum: 300 KM or 200 MILE - Default: 5 KM

Hotel Ratings: - Valid values: 1, 2, 3, 4, 5 - Can be comma-separated for multiple ratings - Duplicates ignored

Keyword Search: - Minimum length: 3 characters - Maximum length: 100 characters - Special characters: Alphanumeric, spaces, hyphens

6.2.4 Hotel Offer Search Validation¶

Check-in/Check-out Dates: - Check-in: Today or future date - Check-out: After check-in date - Minimum stay: 1 night - Maximum stay: Typically 30 nights (varies by hotel)

Guests and Rooms: - Adults: 1-9 per search - Room quantity: 1-9 - At least 1 adult required

Price Range: - Format: "min-max" (e.g., "100-500") - Min must be less than max - Both must be positive numbers

6.3 Data Retention and Caching¶

6.3.1 Search Results Caching¶

Flight Offers: - Cache duration: Not cached (real-time pricing) - Offer validity: Typically 10 minutes - Must confirm price before booking

Hotel Offers: - Cache duration: Not cached (real-time pricing) - Offer validity: Typically 10-30 minutes - Pricing may change between search and booking

6.3.2 Reference Data Caching¶

Airport Data: - Storage: Local database (amadeus.airport table) - Cache strategy: Populate on-demand - Expiry: No expiry (relatively static data) - Update: Manual or via scheduled refresh

Hotel Data: - Storage: Local database (amd_hotels table) - Cache strategy: Populate on-demand - Expiry: No expiry (relatively static data) - Update: Manual or via scheduled refresh

Airline Data: - Storage: Not cached locally - Fetched: On-demand via batch lookup - Used for: Enriching flight search results

6.3.3 Booking Data¶

Storage: Not managed by this module Retrieval: On-demand via Amadeus API Retention: Per Amadeus data retention policies

7. Non-Functional Requirements¶

7.1 Performance Requirements¶

NFR-P-001: Response Time¶

Requirement: API response times shall meet the following targets:

Operation	Target Response Time	Maximum Response Time
Flight search	< 5 seconds	15 seconds
Flight pricing	< 3 seconds	10 seconds
Flight booking	< 5 seconds	15 seconds
Hotel reference search	< 2 seconds	8 seconds
Hotel offer search	< 5 seconds	15 seconds
Reference data lookup	< 1 second	5 seconds

Measurement: 95th percentile under normal load conditions

NFR-P-002: Throughput¶

Requirement: The system shall support minimum throughput:

Flight searches: 50 requests per second
Flight bookings: 20 requests per second
Hotel searches: 30 requests per second
Reference data lookups: 100 requests per second

NFR-P-003: Database Query Performance¶

Requirement: Database queries for cached data shall complete within 100ms for 95th percentile.

7.2 Scalability Requirements¶

NFR-S-001: Concurrent Users¶

Requirement: The system shall support at least 1,000 concurrent users performing search operations.

NFR-S-002: Data Volume¶

Requirement: The system shall handle: - Airport cache: Up to 10,000 airports - Hotel cache: Up to 1,000,000 hotels - Search results: Up to 250 offers per search

NFR-S-003: Horizontal Scaling¶

Requirement: The system architecture shall support horizontal scaling by adding more service instances.

7.3 Reliability Requirements¶

NFR-R-001: Availability¶

Requirement: The system shall maintain 99.5% uptime during business hours (6 AM - 11 PM local time).

NFR-R-002: Error Handling¶

Requirement: The system shall: - Gracefully handle API failures - Return meaningful error messages - Log all errors for troubleshooting - Not expose sensitive information in error messages

NFR-R-003: Data Integrity¶

Requirement: The system shall ensure: - Cached data accuracy through validation - Booking data consistency with Amadeus - No data corruption in storage

7.4 Security Requirements¶

NFR-SEC-001: Authentication¶

Requirement: All API calls to Amadeus shall use OAuth2 authentication with automatic token refresh.

NFR-SEC-002: Data Protection¶

Requirement: Sensitive data shall be protected: - API credentials stored encrypted - Passenger data transmitted over HTTPS - PII logged only when necessary and masked in logs

NFR-SEC-003: Input Validation¶

Requirement: All user inputs shall be validated to prevent: - SQL injection - XML/JSON injection - Parameter tampering - Buffer overflow

7.5 Maintainability Requirements¶

NFR-M-001: Logging¶

Requirement: The system shall log: - All API requests and responses (with PII masked) - All errors and exceptions with stack traces - Performance metrics (response times) - Cache hit/miss ratios

Log Levels: - ERROR: All failures and exceptions - WARN: Recoverable errors, deprecated usage - INFO: Significant events (booking created, search executed) - DEBUG: Detailed flow information

NFR-M-002: Monitoring¶

Requirement: The system shall expose metrics for: - API response times - Error rates - Cache hit ratios - Amadeus API call counts - Database query performance

NFR-M-003: Configuration Management¶

Requirement: All configuration shall be externalized: - API credentials in configuration files - Service endpoints configurable - Timeout values configurable - Cache settings configurable

7.6 Compatibility Requirements¶

NFR-C-001: Amadeus API Versions¶

Requirement: The system shall support: - Flight Offers Search API v2 - Flight Orders API v1 - Hotel Search API v1 - Hotel Offers API v3 - Reference Data APIs v1

NFR-C-002: Java Version¶

Requirement: The system shall run on Java 17 or higher.

NFR-C-003: Database Compatibility¶

Requirement: The system shall support PostgreSQL 12 or higher.

7.7 Usability Requirements¶

NFR-U-001: Error Messages¶

Requirement: Error messages shall be: - Clear and descriptive - Actionable (indicate what to fix) - Consistent in format - Appropriate for technical users

NFR-U-002: API Documentation¶

Requirement: All APIs shall be documented with: - Input parameter descriptions - Output structure - Example requests and responses - Error codes and descriptions

8. Constraints and Assumptions¶

8.1 Technical Constraints¶

C-001: Amadeus API Limitations¶

Constraint: The system is constrained by Amadeus API limits: - Rate limits: Per API key, varies by endpoint - Data freshness: Real-time but may have slight delays - Availability: Dependent on Amadeus service availability - Geographic coverage: Limited to Amadeus provider network

C-002: Booking Capabilities¶

Constraint: - Hotel booking creation is NOT supported (Amadeus limitation) - Only flight booking creation is available - Seat selection not available through this API - Ancillary services must be added through airline channels

C-003: Search Limitations¶

Constraint: - Maximum 250 flight offers per search - Maximum 250 hotels per offer search - Multi-city limited to reasonable number of segments - Date range limited to airline booking windows (typically 331 days)

C-004: Data Caching¶

Constraint: - Flight offers cannot be reliably cached (pricing changes) - Hotel offers cannot be reliably cached (availability changes) - Reference data updates require manual cache refresh

8.2 Business Constraints¶

C-005: Amadeus Subscription Required¶

Constraint: Valid Amadeus For Developers subscription required with appropriate API access levels.

C-006: Commercial Terms¶

Constraint: Usage subject to Amadeus commercial terms and pricing.

C-007: Data Ownership¶

Constraint: All data retrieved from Amadeus is owned by Amadeus and subject to their terms of use.

8.3 Assumptions¶

A-001: Network Connectivity¶

Assumption: Reliable internet connectivity available for API calls to Amadeus servers.

A-002: Database Availability¶

Assumption: PostgreSQL database available and accessible for caching operations.

A-003: Session Management¶

Assumption: Session management handled by calling application (not in module scope).

A-004: Payment Processing¶

Assumption: Payment processing handled by separate system (not in module scope).

A-005: User Authentication¶

Assumption: User authentication and authorization handled by calling application.

A-006: Amadeus API Stability¶

Assumption: Amadeus APIs remain backward compatible or provide migration path for version updates.

A-007: Reference Data Accuracy¶

Assumption: Amadeus reference data (airports, airlines) is accurate and current.

A-008: Time Zone Handling¶

Assumption: All datetime values are in local time of the relevant airport/hotel unless otherwise specified.

9. Glossary¶

Term	Definition
Amadeus	Global distribution system (GDS) and travel technology provider
API	Application Programming Interface
Cabin Class	Class of service on flight (Economy, Business, First)
Fare Basis	Airline code representing fare rules and restrictions
GDS	Global Distribution System
IATA	International Air Transport Association
ICAO	International Civil Aviation Organization
ISO 8601	International standard for date and time representation
Itinerary	Complete journey including all segments
Offer	Available flight or hotel option with pricing
PII	Personally Identifiable Information
PNR	Passenger Name Record (booking reference)
Segment	Single flight leg (one takeoff and landing)
Session	User session for API interactions

10. Document Revision History¶

Version	Date	Author	Changes
1.0	2024-11-23	System Analysis	Initial requirements specification based on code analysis

11. Approval¶

This requirements specification document represents the functional capabilities of the TQAMDS module as implemented.

Document Status: Draft for Review

Next Steps: 1. Review by product management 2. Review by technical architecture 3. Validation against business requirements 4. Approval and baseline

End of Document

Functional Requirements Specification¶

Table of Contents¶

1. Introduction¶

1.1 Purpose¶

1.2 Intended Audience¶

1.3 Product Overview¶

2. Scope¶

2.1 In Scope¶

2.2 Out of Scope¶

3. Functional Requirements¶

3.1 Flight Search Requirements¶

FR-FS-001: Basic Flight Search¶

FR-FS-002: Advanced Flight Search Filters¶

FR-FS-003: Flight Itinerary Details¶

FR-FS-004: Flight Pricing Details¶

FR-FS-005: Flight Price Confirmation¶

3.2 Flight Booking Requirements¶

FR-FB-001: Create Flight Booking¶

FR-FB-002: Retrieve Flight Booking¶

FR-FB-003: Cancel Flight Booking¶

3.3 Hotel Search Requirements¶

FR-HS-001: Hotel Search by City¶

FR-HS-002: Hotel Search by Geographic Coordinates¶

FR-HS-003: Hotel Search by Name¶

FR-HS-004: Hotel Lookup by IDs¶

3.4 Hotel Availability and Pricing Requirements¶

FR-HA-001: Hotel Offer Search¶

FR-HA-002: Retrieve Specific Hotel Offer¶

3.5 Reference Data Requirements¶

FR-RD-001: Airline Information Lookup¶

FR-RD-002: Airport and Location Search¶

FR-RD-003: Airport Lookup by Code¶

4. Use Cases¶

4.1 Use Case: Book a Round-Trip Flight¶

4.2 Use Case: Find Hotel in City¶

4.3 Use Case: Hotel Name Autocomplete¶

4.4 Use Case: Retrieve and Cancel Booking¶

4.5 Use Case: Multi-City Flight Search¶

4.6 Use Case: Search Flights with Filters¶

5. API Specifications¶

5.1 Flight Search API¶

5.1.1 Search Flight Offers¶

5.1.2 Get Flight Offer Pricing¶

5.2 Flight Booking API¶

5.2.1 Create Flight Booking¶

5.2.2 Retrieve Flight Booking¶

5.2.3 Cancel Flight Booking¶

5.3 Hotel Reference Data API¶

5.3.1 Get Hotels by City¶

5.3.2 Get Hotels by Geographic Coordinates¶

5.3.3 Search Hotels by Name¶

5.3.4 Get Hotels by IDs¶

5.4 Hotel Availability and Pricing API¶

5.4.1 Search Hotel Offers¶

5.4.2 Get Hotel Offer by ID¶

5.5 Reference Data API¶

5.5.1 Get Airlines¶

5.5.2 Search Locations¶

5.5.3 Get Airport by Code¶

6. Data Requirements¶

6.1 Data Formats¶

6.1.1 Date and Time Formats¶

6.1.2 Currency Formats¶

6.1.3 Location Codes¶

6.1.4 Passenger Types¶

6.1.5 Cabin Classes¶

6.1.6 Document Types¶

6.2 Data Validation Rules¶

6.2.1 Flight Search Validation¶

6.2.2 Booking Validation¶

6.2.3 Hotel Search Validation¶

6.2.4 Hotel Offer Search Validation¶

6.3 Data Retention and Caching¶

6.3.1 Search Results Caching¶

6.3.2 Reference Data Caching¶

6.3.3 Booking Data¶

7. Non-Functional Requirements¶

7.1 Performance Requirements¶

NFR-P-001: Response Time¶

NFR-P-002: Throughput¶