Gov_Travel_App/documents/AMADEUS_SETUP.md

Amadeus Flight API Setup Guide

This application now automatically searches for real flight prices using the Amadeus Flight API.

🎯 Features

• ✈️ Automatic flight price search - No manual entry needed
• ⏱️ Automatic duration calculation - Determines business class eligibility
• 💰 Real-time pricing in CAD
• 🎫 Multiple flight options - Shows cheapest flights
• 🚨 Business class detection - Flags flights ≥9 hours automatically

---

📋 Prerequisites

You need a free Amadeus Self-Service API account:

• 2,000 free API calls per month
• No credit card required for development tier
• Official airline pricing data

---

🚀 Quick Setup (5 minutes)

Step 1: Register for Amadeus API

1. Go to: https://developers.amadeus.com/register
2. Create a free account
3. Verify your email

Step 2: Create an Application

1. Log in to: https://developers.amadeus.com/my-apps
2. Click "Create New App"
3. Enter app details:
   • App Name: Government Travel Estimator
   • Description: Travel cost calculator for government employees
4. Click "Create"

Step 3: Get Your API Credentials

After creating the app, you'll see:

• API Key (Client ID)
• API Secret (Client Secret)

⚠️ Keep these confidential!

Step 4: Configure the Application

1. Open the .env file in the project root
2. Add your credentials:

AMADEUS_API_KEY=your_api_key_here
AMADEUS_API_SECRET=your_api_secret_here

Step 5: Restart the Server

# Stop the current server (Ctrl+C)
# Then restart:
npm start

You should see:

✅ Amadeus API configured

---

🎮 How to Use

1. Enter Travel Details:

   • Departure City: Ottawa
   • Destination City: Vancouver
   • Departure Date
   • Return Date

2. Select Transportation:

   • Choose "Flight"

3. Click "Search Flights Automatically"

   • App will search for real flights
   • Shows 5 cheapest options
   • Duration and business class eligibility shown

4. Select a Flight:

   • Click on any flight option
   • Price and duration auto-populate
   • Continue with accommodation estimate

5. Calculate Total Cost:

   • Scroll down
   • Enter accommodation estimate
   • Click "Calculate Estimate"

---

🌍 Supported Cities

The app includes airport codes for 60+ cities:

🇨🇦 Canadian Cities

Ottawa, Toronto, Montreal, Vancouver, Calgary, Edmonton, Winnipeg, Halifax, Quebec City, Whitehorse, Yellowknife, Iqaluit, and more

🇺🇸 US Cities

New York, Los Angeles, Chicago, San Francisco, Seattle, Boston, Washington DC, Miami, Dallas, Denver, Las Vegas, and more

🌏 International

London, Paris, Frankfurt, Amsterdam, Tokyo, Hong Kong, Singapore, Dubai, Sydney, Auckland, Mexico City, and more

---

🔧 Troubleshooting

Error: "Amadeus API credentials not configured"

Solution: Add your API key and secret to the .env file

Error: "Could not find airport codes"

Solution: The city name needs to match one in the database. Try:

• "Ottawa" instead of "Ottawa, ON"
• "New York" instead of "NYC"
• "Vancouver" instead of "Vancouver, BC"

Error: "No flights found for this route"

Possible causes:

• Date is too far in the future (try within 11 months)
• Route not available (small airports may not have data)
• Try searching on Google Flights manually

API Rate Limits

Free tier: 2,000 calls/month

• Each search = 1 API call
• ~66 searches per day
• Perfect for small teams

If you exceed limits, you'll get an error. Wait until next month or upgrade to paid tier.

---

💡 API Limits & Best Practices

Free Tier Limits

• ✅ 2,000 API calls/month
• ✅ Test & development use
• ✅ No credit card required

Tips to Save API Calls

1. Only search when dates are finalized
2. Use manual Google Flights link for rough estimates
3. Share results with colleagues instead of re-searching
4. Consider caching common routes

---

🔐 Security Notes

• ✅ .env file is in .gitignore (won't be committed)
• ✅ Never share your API credentials
• ✅ API keys are server-side only
• ✅ Not exposed to browser/frontend

---

📊 What Gets Calculated

For each flight search, you get:

• Price in CAD
• Duration in hours (for business class rules)
• Number of stops (direct vs. connections)
• Business class eligibility (≥9 hours)
• Carrier information
• Departure/arrival times

---

🎓 Amadeus Documentation

For more details:

• API Docs: https://developers.amadeus.com/self-service/category/flights
• Support: https://developers.amadeus.com/support
• Dashboard: https://developers.amadeus.com/my-apps

---

⚙️ Alternative: Manual Entry

Don't want to set up the API? No problem!

The app still has the Google Flights integration:

1. Click the Google Flights link
2. Copy the price
3. Paste into the form
4. Enter duration manually

Takes about 30 seconds per search.

---

🧪 Sample Flights (No API)

When the Amadeus credentials are not configured (for example in a fresh Docker build or when you want to keep the app self-hosted without API keys), the backend returns curated sample flights from data/sampleFlights.json. You can still click Search Flights Automatically, review the mock options, and select one to populate the form. The status banner will mention that these are placeholder flights, so you know when to add real credentials and get live pricing.

---

🆘 Getting Help

API Issues

Contact Amadeus Support: https://developers.amadeus.com/support

App Issues

Check the server console for error messages

Still Stuck?

The app works fine without the API - use manual Google Flights links instead.

---

✨ Benefits of API Integration

Feature	Manual Entry	With Amadeus API
Speed	30 seconds	5 seconds
Accuracy	User dependent	Official data
Business class detection	Manual	Automatic
Multiple options	One at a time	5 instantly
Up-to-date prices	User checks	Real-time
Effort	Medium	Low

---

You're all set! 🎉

The app will now automatically search flights and calculate costs with real airline data.