Nowah Java SDK

Official Java SDK for the Nowah Travel API.

Requirements

• Java 11+
• No runtime dependencies (stdlib only)

Installation

Maven

<dependency>
    <groupId>xyz.nowah</groupId>
    <artifactId>sdk</artifactId>
    <version>0.2.0</version>
</dependency>

Gradle

implementation 'xyz.nowah:sdk:0.2.0'

Quick Start

import com.nowah.sdk.*;
import com.nowah.sdk.model.*;

NowahClient client = NowahClient.builder("your-api-key").build();

// Search flights
ApiResponse<SearchFlightsResult> flights = client.searchFlights(
    SearchFlightsParams.builder("JFK", "LAX", "2025-06-15", new Passengers(1))
        .cabinClass(CabinClass.ECONOMY)
        .build()
);

for (FlightOffer offer : flights.getData().getOffers()) {
    System.out.println(offer.getAirline() + ": " + offer.getPriceAmount());
}

Configuration

NowahClient client = NowahClient.builder("your-api-key")
    .baseUrl("https://custom-api.example.com")     // Custom base URL
    .httpClient(HttpClient.newHttpClient())          // Custom HttpClient
    .maxRetries(2)                                   // Retry count (default: 1)
    .build();

API Methods

Stable Nowah-owned responses and normalized flight results use typed ApiResponse<T> models. Provider passthrough methods continue to return raw JSON strings.

Flights

client.searchFlights(params)        // Typed normalized flight offers
client.searchFlightsRaw(params)     // Unparsed flight response
client.searchLocations(params)      // Search airports/cities
client.getOffer(params)             // Get offer details (with optional seat map)
client.getOfferServices(offerId)    // Get available services for an offer

Hotels

client.searchHotels(params)         // Search hotels
client.getHotelQuote(rateId)        // Get a hotel rate quote

Trips

client.listTrips()                  // List all trips
client.listTrips(params)            // List trips with pagination
client.getTrip(tripId)              // Get a single trip
client.createTrip(params)           // Create a trip from an offer
client.updateTrip(params)           // Update trip details
client.cancelTrip(params)           // Cancel a trip
client.getTripDocuments(tripId)     // Get trip documents

Booking

client.bookFlight(params)           // Book a flight (idempotent)
client.getBookingFees()             // Get booking fee schedule
client.bookHotel(params)            // Book a hotel (idempotent)

Payments

client.createCheckoutSession(params)     // Create Stripe checkout session
client.listPaymentMethods()              // List saved payment methods
client.payWithSavedCard(params)          // Pay with a saved card
client.getPaymentStatus(paymentIntentId) // Check payment status
client.managePaymentMethod(params)       // Delete or set default

Orders

client.getCancellationQuote(orderId)     // Get cancellation quote
client.confirmCancellation(cancelId)     // Confirm cancellation (idempotent)
client.getOrderServices(orderId)         // List available services
client.addOrderServices(params)          // Add services (idempotent)
client.createChangeRequest(params)       // Request flight change
client.confirmFlightChange(params)       // Confirm change (idempotent)

Seat Map

client.getSeatInfo(params)               // Get seat layout/best/avoid
client.getSeatRecommendations(params)    // Get AI seat recommendations

Flight Tracking

client.getFlightInfo(params)             // Get flight status/position
client.getBookingTracking(bookingId)     // Track a booking's flights
client.getAirportDelays(airportCode)     // Get airport delay info

Travel Info

client.getVisaRequirements(passport, dest)  // Visa requirements
client.getWeather(params)                    // Current or forecast weather
client.convertCurrency(params)               // Convert or get rates
client.getSafetyInfo(country)                // Country safety info

POIs & Itinerary

client.findPois(params)                  // Search or nearby POIs
client.generateItinerary(params)         // AI-generated itinerary

Claims

client.checkClaimEligibility(params)     // Check if claim is eligible
client.fileClaim(params)                 // File a claim
client.listClaims()                      // List all claims
client.listClaims(params)               // List claims with filters

Usage

client.getUsageStats()                   // Get API usage stats
client.getUsageStats(params)             // With period/endpoint filter

AI Agent

client.chatWithAgent(params)             // Non-streaming chat
client.chatWithAgentStream(params)       // Streaming chat

Error Handling

All errors throw NowahException (unchecked):

try {
    client.getTrip("nonexistent");
} catch (NowahException e) {
    if (e.isNotFound()) {
        System.out.println("Trip not found");
    } else if (e.isUnauthorized()) {
        System.out.println("Invalid API key");
    } else if (e.isRateLimited()) {
        System.out.println("Rate limited, retry later");
    } else if (e.isTimeout()) {
        System.out.println("Request timed out");
    }

    System.out.println("Status: " + e.getStatusCode());
    System.out.println("Code: " + e.getCode());
    System.out.println("Retryable: " + e.isRetryable());
}

Retry & Idempotency

• Retries: 5xx and network errors are retried (default: 1 retry with exponential backoff). 4xx errors are never retried.
• Idempotency: bookFlight, bookHotel, confirmCancellation, addOrderServices, and confirmFlightChange automatically generate X-Idempotency-Key headers.
• Timeouts: 30s for standard requests, 120s for streaming.

Thread Safety

NowahClient is thread-safe. The underlying HttpClient and all parameter classes are immutable.

License

Apache 2.0