Nearby Endpoint Documentation

Overview

The /api/maps/nearby endpoint allows you to find exhibitions, spaces, and restaurants within walking distance from a given location based on time input.

Endpoint

GET /api/maps/nearby

Parameters

Required Parameters

• lat (float): Latitude of the starting point
• lng (float): Longitude of the starting point
• time (integer): Maximum walking time in minutes (1-480)

Optional Parameters

• include_restaurants (boolean): Whether to include nearby restaurants in results (default: false)

Example Request

Basic Request (Exhibitions and Spaces only)

GET /api/maps/nearby?lat=50.935173&lng=6.953101&time=30

Request with Restaurants

GET /api/maps/nearby?lat=50.935173&lng=6.953101&time=30&include_restaurants=true

Response Format

The endpoint returns a JSON object with three arrays:

{
  "exhibitions": [
    {
      "id": "exhibition-uuid",
      "name": "Exhibition Name",
      "body": "Exhibition description",
      "start_date": "2024-01-01T00:00:00+00:00",
      "end_date": "2024-12-31T23:59:59+00:00",
      "space": {
        "id": "space-uuid",
        "name": "Gallery Name",
        "address": "123 Art Street",
        "lat": 50.935173,
        "lng": 6.953101
      },
      "walking_distance": {
        "distance": "1.2 km",
        "distance_meters": 1200,
        "duration": "15 mins",
        "duration_minutes": 15
      }
    }
  ],
  "spaces": [
    {
      "id": "space-uuid",
      "name": "Gallery Name",
      "address": "123 Art Street",
      "lat": 50.935173,
      "lng": 6.953101,
      "walking_distance": {
        "distance": "1.2 km",
        "distance_meters": 1200,
        "duration": "15 mins",
        "duration_minutes": 15
      }
    }
  ],
  "restaurants": [
    {
      "id": "place_id",
      "name": "Restaurant Name",
      "address": "456 Food Street",
      "rating": 4.5,
      "price_level": 2,
      "types": ["restaurant", "food", "establishment"],
      "lat": 50.935173,
      "lng": 6.953101,
      "walking_distance": {
        "distance": "0.8 km",
        "distance_meters": 800,
        "duration": "10 mins",
        "duration_minutes": 10
      }
    }
  ]
}

Features

Exhibitions

• Returns only currently active exhibitions (between start_date and end_date)
• Includes full exhibition details with associated space information
• Sorted by walking time (closest first)

Spaces

• Returns unique spaces (no duplicates even if multiple exhibitions at same space)
• Includes space details and walking distance
• Sorted by walking time (closest first)

Restaurants (Optional)

• Uses Google Places API to find nearby restaurants
• Filters results to only include restaurants within the specified walking time
• Includes restaurant details like rating, price level, and types
• Sorted by walking time (closest first)

Walking Distance Calculation

• Uses Google Maps Distance Matrix API
• Calculates actual walking routes (not straight-line distance)
• Returns both human-readable and machine-readable distance/duration
• Duration is rounded to the nearest minute

Error Handling

Validation Errors

{
  "error": "Validation failed",
  "extended": {
    "lat": ["This field is required"],
    "time": ["Time must be between 1 and 480 minutes"]
  }
}

API Errors

If Google Maps API is unavailable or returns an error, the endpoint will still return exhibitions and spaces but may not include accurate walking distances.

Rate Limiting

• Google Maps API has rate limits
• Consider caching results for frequently requested locations
• The endpoint makes one API call per exhibition/space/restaurant

Use Cases

Art Gallery Discovery

Find all exhibitions within a 30-minute walk from your current location.

Lunch Planning

Find exhibitions and nearby restaurants within a 15-minute walk for lunch breaks.

Cultural District Exploration

Discover all cultural spaces within walking distance for a day of gallery hopping.

Example Use Cases

Mobile App Integration

// Find exhibitions within 20 minutes walk
fetch('/api/maps/nearby?lat=50.935173&lng=6.953101&time=20')
  .then(response => response.json())
  .then(data => {
    console.log('Nearby exhibitions:', data.exhibitions);
    console.log('Nearby spaces:', data.spaces);
  });

Restaurant Integration

// Find exhibitions and restaurants within 30 minutes
fetch('/api/maps/nearby?lat=50.935173&lng=6.953101&time=30&include_restaurants=true')
  .then(response => response.json())
  .then(data => {
    console.log('Cultural itinerary:', data.exhibitions);
    console.log('Dining options:', data.restaurants);
  });