Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
421 lines (373 loc) · 10.5 KB

API_DOCUMENTATION.md

File metadata and controls

421 lines (373 loc) · 10.5 KB

🌟 LAYOVER LEGEND API - Complete Documentation

🚀 What This System Does

Your Layover Legend System is a smart layover planning API that:

  • Finds places to visit during airport layovers
  • Uses AI agents to create personalized itineraries
  • Uses ArcGIS for real routing and travel times
  • Uses OpenAI embeddings for semantic search
  • Returns complete route geometry for frontend mapping
  • Always includes airport as starting and ending points
  • Extracts preferences from natural language queries

🎯 Access Your API

Base URL: http://localhost:8000
Swagger Documentation: http://localhost:8000/docs
OpenAPI JSON: http://localhost:8000/openapi.json

📋 All API Endpoints

1. Health Check - GET /

Purpose: Check if API is running and get system status
Sample Request:

curl http://localhost:8000/

Sample Response:

{
  "message": "Layover Legend API is running",
  "status": "healthy",
  "available_airports": ["LGA", "JFK", "EWR"],
  "total_pois": 22
}

2. Get Airports - GET /airports

Purpose: Get list of supported airports with coordinates
Sample Request:

curl http://localhost:8000/airports

Sample Response:

{
  "airports": {
    "LGA": {
      "name": "LaGuardia Airport",
      "latitude": 40.7769,
      "longitude": -73.8740
    },
    "JFK": {
      "name": "JFK Airport", 
      "latitude": 40.6413,
      "longitude": -73.7781
    },
    "EWR": {
      "name": "Newark Airport",
      "latitude": 40.6895,
      "longitude": -74.1745
    }
  }
}

3. Get All POIs - GET /pois

Purpose: Get all available Points of Interest with ArcGIS geocoded coordinates
Sample Request:

curl http://localhost:8000/pois

Sample Response:

{
  "pois": [
    {
      "name": "Empire State Building",
      "address": "20 W 34th St., New York, NY 10001",
      "category": "Monument", 
      "description": "Iconic Art Deco skyscraper...",
      "latitude": 40.748673,
      "longitude": -73.985495
    }
  ]
}

4. Search Places - POST /search-places

Purpose: Semantic search for places using AI embeddings
Sample Request:

curl -X POST "http://localhost:8000/search-places" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentic NYC coffee shops"}'

Sample Response:

{
  "success": true,
  "query": "authentic NYC coffee shops",
  "locations": [
    {
      "name": "Banc Cafe",
      "address": "431 3rd Ave, New York, NY 10016",
      "category": "Cafe",
      "description": "Neighborhood staple in Murray Hill...",
      "latitude": 40.743243,
      "longitude": -73.979706
    }
  ],
  "raw_result": "Found 1 places"
}

5. Calculate Route - POST /calculate-route

Purpose: Calculate route between two points using ArcGIS
Sample Request:

curl -X POST "http://localhost:8000/calculate-route" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_lat": 40.7769,
    "origin_lon": -73.8740,
    "dest_lat": 40.748673,
    "dest_lon": -73.985495,
    "mode": "driving"
  }'

Sample Response:

{
  "success": true,
  "route": {
    "from_location": "40.7769,-73.8740",
    "to_location": "40.7487,-73.9855", 
    "travel_time_minutes": 48,
    "distance_miles": 17.2,
    "mode": "driving",
    "coordinates": [[-73.8740, 40.7769], [-73.9855, 40.7487]]
  },
  "raw_result": "✅ Driving: 48 minutes, 17.2 miles"
}

6. Plan Multi-Stop Route - POST /plan-multi-stop-route ⭐

Purpose: MAIN ROUTING API - Complete ArcGIS routing with TIMECAT
Sample Request:

curl -X POST "http://localhost:8000/plan-multi-stop-route" \
  -H "Content-Type: application/json" \
  -d '{
    "airport_code": "LGA",
    "poi_locations": [
      {
        "name": "Empire State Building",
        "lat": 40.748673,
        "lon": -73.985495,
        "timecat": 1
      },
      {
        "name": "Banc Cafe", 
        "lat": 40.743243,
        "lon": -73.979706,
        "timecat": 1
      }
    ],
    "mode": "driving"
  }'

Sample Response:

{
  "success": true,
  "arcgis_response": {
    "routes": {
      "features": [{
        "attributes": {
          "Total_TravelTime": 51.7,
          "Total_Miles": 16.3
        },
        "geometry": {
          "paths": [
            [[-73.87383, 40.77378], [-73.87396, 40.77376]]
          ]
        }
      }]
    },
    "stops": [...],
    "directions": [...],
    "messages": []
  },
  "time_analysis": {
    "total_travel_time_minutes": 51.7,
    "total_distance_miles": 16.3,
    "total_visit_time_minutes": 120,
    "safety_buffer_minutes": 120,
    "total_time_needed_minutes": 291.7,
    "poi_details": [...]
  },
  "time_breakdown": {
    "travel": "51.7 minutes",
    "visits": "120 minutes",
    "buffer": "120 minutes", 
    "total": "291.7 minutes (4.9 hours)"
  },
  "frontend_ready": {
    "routes": {...},
    "directions": [...],
    "stops": [...],
    "messages": []
  }
}

7. Plan Layover - POST /plan-layover 🤖

Purpose: AI AGENT PLANNING - Complete layover planning with CrewAI
Sample Request:

curl -X POST "http://localhost:8000/plan-layover" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I love to walk and I love bars",
    "user_preferences": {},
    "airport": "LGA",
    "layover_hours": 6,
    "arrival_time": "9:00 AM",
    "departure_time": "3:00 PM"
  }'

Sample Response:

{
  "success": true,
  "text_response": "**Layover Itinerary for Walking Enthusiast**\n\n**Timeline:**\n- **9:00 AM - Leave LGA Airport:** Allocate 30-45 minutes for airport departure logistics...",
  "locations": [
    {
      "name": "LGA Airport",
      "address": "LaGuardia Airport",
      "category": "Airport",
      "description": "Starting and ending point for layover",
      "latitude": 40.7769,
      "longitude": -73.8740
    },
    {
      "name": "230 Fifth Rooftop Bar",
      "address": "1150 Broadway, New York, NY 10001",
      "category": "POI",
      "description": "Expansive rooftop in the Flatiron District with panoramic views",
      "latitude": 40.7442,
      "longitude": -73.9888
    },
    {
      "name": "LGA Airport (Return)",
      "address": "LaGuardia Airport",
      "category": "Airport",
      "description": "Return point for layover",
      "latitude": 40.7769,
      "longitude": -73.8740
    }
  ],
  "routes": [
    {
      "from_location": "LGA Airport",
      "to_location": "230 Fifth Rooftop Bar",
      "travel_time_minutes": 144,
      "distance_miles": 7.5,
      "mode": "walking",
      "coordinates": [[-73.8740, 40.7769], [-73.9888, 40.7442]]
    }
  ],
  "total_cost_estimate": {
    "taxi": 0.0,
    "subway": 0.0,
    "walking": 0.0
  },
  "arcgis_route_data": {
    "routes": {...},
    "directions": [...],
    "stops": [...]
  },
  "frontend_ready": {
    "routes": {...},
    "directions": [...],
    "stops": [...],
    "messages": []
  },
  "route_analysis": {
    "total_travel_time_minutes": 144,
    "total_distance_miles": 7.5,
    "geometry_paths": [...]
  }
}

8. Test ArcGIS Data - GET /test-arcgis-data

Purpose: Test if ArcGIS data is being stored and accessible
Sample Request:

curl http://localhost:8000/test-arcgis-data

Sample Response:

{
  "has_arcgis_data": true,
  "data_keys": ["routes", "directions", "stops"],
  "routes_available": true,
  "directions_available": true
}

🎯 TIMECAT System

Your system uses TIMECAT values to determine visit durations:

TIMECAT Duration Type Description
1 30 minutes Short visit Quick stops, coffee, snacks
2 60 minutes Medium visit Meals, museum exhibits, shopping
3 180 minutes Long visit Full museum tours, extended dining

🗺️ For Frontend Engineers

Key Response Fields:

  • arcgis_response: Complete ArcGIS data for mapping
  • routes.features[0].geometry.paths: Route coordinates for drawing
  • directions: Turn-by-turn navigation
  • stops: Optimized stop sequence
  • spatialReference.wkid: 4326: WGS84 coordinate system
  • locations: Always includes airport as first and last points

Route Geometry:

  • Detailed coordinate points for accurate mapping
  • Format: [longitude, latitude] pairs
  • Compatible with ArcGIS JavaScript SDK, Google Maps, Mapbox

Airport Integration:

  • First location: Always the departure airport
  • Last location: Always the return airport
  • Coordinates: Real airport coordinates from ArcGIS geocoding
  • Categories: Marked as "Airport" for easy identification

🔧 How to Test in Swagger

  1. Open: http://localhost:8000/docs
  2. Click on any endpoint
  3. Click "Try it out"
  4. Enter sample data from above
  5. Click "Execute"
  6. See the response

🚀 System Architecture

User Query → FastAPI → CrewAI Agent → Tools:
                                    ├── Search Places (OpenAI Embeddings + LanceDB)
                                    ├── Calculate Route (ArcGIS Routing API)
                                    ├── Plan Multi-Stop Route (ArcGIS + TIMECAT)
                                    └── Get Transportation Options
                      ↓
Frontend ← Complete Response (Text + Routes + Geometry + Airport Locations)

📊 Database

  • LanceDB: Vector database with OpenAI embeddings
  • 22 NYC POIs: Coffee shops, museums, landmarks, etc.
  • Embedding Model: text-embedding-ada-002
  • Search Method: L2 (Euclidean) distance similarity
  • ArcGIS Geocoding: All POIs have precise coordinates

🔑 API Keys Used

  • OpenAI: For LLM and embeddings (text-embedding-ada-002)
  • ArcGIS: For geocoding and routing (World Geocoding Service, Routing Service)

🎉 Ready for Production!

Your system is complete and ready for frontend integration. The /plan-layover endpoint provides everything needed for mapping applications, including:

✅ Complete itinerary text
✅ All locations with airport
✅ Route geometry for mapping
✅ Turn-by-turn directions
✅ Time analysis with buffers
✅ Cost estimates
✅ Frontend-ready JSON structure

The system automatically extracts preferences from natural language queries and always includes the airport as starting and ending points for complete layover planning!