Art Tour Planning API Endpoint

Overview

The /maps/tour endpoint provides intelligent art tour planning based on available time, similar to Komoot for art galleries. It creates optimized routes that include gallery visits, travel time, and optional restaurant stops.

Endpoint

GET /maps/tour

Parameters

Parameter	Type	Required	Default	Description
`lat`	float	Yes	-	Starting latitude
`lng`	float	Yes	-	Starting longitude
`total_time`	integer	Yes	-	Total available time in minutes (30-480)
`gallery_time`	integer	No	20	Time to spend at each gallery in minutes (10-120)
`include_restaurant`	boolean	No	false	Whether to include a restaurant stop
`restaurant_time`	integer	No	45	Time to spend at restaurant in minutes (15-120)
`loop`	boolean	No	true	Whether to return to starting point
`max_galleries`	integer	No	5	Maximum number of galleries to visit (1-10)

Example Requests

Basic 2-hour tour

GET /maps/tour?lat=50.935173&lng=6.953101&total_time=120

Tour with lunch break

GET /maps/tour?lat=50.935173&lng=6.953101&total_time=180&include_restaurant=true&restaurant_time=60

Customized gallery time

GET /maps/tour?lat=50.935173&lng=6.953101&total_time=120&gallery_time=30&max_galleries=3

One-way tour (no return)

GET /maps/tour?lat=50.935173&lng=6.953101&total_time=120&loop=false

Response Format

Success Response

{
  "success": true,
  "tour": {
    "stops": [
      {
        "type": "restaurant",
        "name": "Café Central",
        "address": "Hohe Straße 123, Cologne",
        "lat": 50.935173,
        "lng": 6.953101,
        "time_minutes": 45,
        "walking_time_minutes": 5,
        "distance_km": 0.3,
        "description": "Lunch break"
      },
      {
        "type": "gallery",
        "id": 123,
        "name": "Contemporary Art Exhibition",
        "space_name": "Galerie Modern",
        "address": "Kunststraße 45, Cologne",
        "lat": 50.936000,
        "lng": 6.954000,
        "visit_time_minutes": 20,
        "travel_time_minutes": 8,
        "total_time_minutes": 28,
        "distance_km": 0.5,
        "exhibition": {
          "id": 123,
          "name": "Contemporary Art Exhibition",
          "opening_datetime": "2024-01-15T10:00:00",
          "closing_datetime": "2024-03-15T18:00:00"
        }
      },
      {
        "type": "return",
        "name": "Return to start",
        "lat": 50.935173,
        "lng": 6.953101,
        "travel_time_minutes": 12,
        "total_time_minutes": 12,
        "distance_km": 0.8,
        "description": "Return to starting point"
      }
    ],
    "total_time_minutes": 130,
    "total_distance_km": 1.6,
    "gallery_count": 1,
    "includes_restaurant": true
  },
  "summary": {
    "total_stops": 3,
    "gallery_count": 1,
    "restaurant_count": 1,
    "total_time_minutes": 130,
    "requested_time_minutes": 120,
    "time_utilization_percent": 108.3,
    "total_distance_km": 1.6,
    "average_time_per_gallery": 130.0
  }
}

Error Response

{
  "success": false,
  "message": "No galleries found within the specified time range",
  "tour": null
}

Tour Planning Algorithm

The tour planning uses a greedy algorithm that:

Calculates available time for travel after accounting for gallery visits and restaurant time
Finds potential galleries within reasonable walking distance using database-level filtering
Optimizes the route by selecting the nearest gallery at each step
Accounts for travel time between locations using realistic walking speed estimates
Optionally includes restaurant at the beginning of the tour
Optionally returns to start if loop is enabled

Time Calculations

Walking Speed: 5 km/h (realistic urban walking speed)
Distance Factor: 1.4x straight-line distance (accounts for actual walking paths)
Gallery Time: Configurable per gallery (default: 20 minutes)
Restaurant Time: Configurable (default: 45 minutes)

Optimization Features

Database-level filtering for performance
Greedy nearest-neighbor algorithm for route optimization
Time-aware selection ensures tours fit within time constraints
Flexible restaurant placement at tour start
Loop/one-way options for different use cases

Use Cases

Mobile App Integration

Perfect for iOS/Android apps that need to provide “one-click” art tour planning:

// Example mobile app usage
const planTour = async (lat, lng, totalTime) => {
  const response = await fetch(`/maps/tour?lat=${lat}&lng=${lng}&total_time=${totalTime}&include_restaurant=true`);
  const tour = await response.json();
  
  if (tour.success) {
    // Display tour on map
    displayTourOnMap(tour.tour.stops);
    // Show tour summary
    showTourSummary(tour.summary);
  }
};

Web Application

Ideal for web-based art discovery platforms:

// Example web app usage
const createArtTour = async (userLocation, preferences) => {
  const params = new URLSearchParams({
    lat: userLocation.lat,
    lng: userLocation.lng,
    total_time: preferences.duration,
    gallery_time: preferences.galleryTime || 20,
    include_restaurant: preferences.includeLunch,
    loop: preferences.returnToStart !== false
  });
  
  const response = await fetch(`/maps/tour?${params}`);
  return await response.json();
};

Performance Considerations

Efficient database queries using existing findDistance finder
Minimal API calls to Google Maps (only for restaurant search)
Caching-friendly responses for repeated requests
Scalable algorithm that works with large numbers of galleries

Error Handling

The endpoint handles various error conditions:

No galleries found: Returns appropriate message when no galleries are within range
Invalid parameters: Validates all input parameters with clear error messages
API failures: Gracefully handles Google Maps API failures
Time constraints: Ensures tours fit within specified time limits

Future Enhancements

Potential improvements for the tour planning system:

Advanced routing algorithms (TSP solvers for optimal routes)
Real-time traffic integration for more accurate travel times
Gallery preferences based on user interests
Multi-day tour planning for longer art experiences
Public transport integration for longer distances
Gallery opening hours consideration in route planning