Comprehensive Venue Module

Search, filter, and analyze venue data for events, conferences, and meetings using programmatic APIs and data sources. This skill covers venue search with geographic filters, capacity matching, availability checking, comparison scoring, and integration with mapping services for location-based event planning.

When to Use This Skill

Choose Comprehensive Venue Module when you need to:

• Search for event venues by location, capacity, amenities, and availability
• Compare venues across multiple criteria with weighted scoring
• Integrate venue data with mapping and transportation APIs
• Build event planning tools with automated venue recommendations

Consider alternatives when:

• You need hotel booking integrations (use booking platform APIs)
• You need restaurant reservations (use OpenTable or Resy APIs)
• You need real estate commercial listings (use commercial real estate APIs)

Quick Start

Copy
pip install requests geopy pandas

Copy
import requests
from geopy.distance import geodesic
from geopy.geocoders import Nominatim
from dataclasses import dataclass
from typing import List, Optional

@dataclass
class Venue:
    name: str
    address: str
    latitude: float
    longitude: float
    capacity: int
    amenities: List[str]
    price_per_hour: float
    rating: float = 0.0
    venue_type: str = "conference"

    @property
    def coordinates(self):
        return (self.latitude, self.longitude)

class VenueSearchEngine:
    """Search and compare venues for events."""

    def __init__(self):
        self.venues: List[Venue] = []
        self.geocoder = Nominatim(user_agent="venue_search")

    def add_venue(self, venue: Venue):
        self.venues.append(venue)

    def search(self, location: str, radius_km: float = 10,
               min_capacity: int = 0, required_amenities: List[str] = None,
               max_price: float = float('inf')) -> List[dict]:
        """Search venues by criteria."""
        geo = self.geocoder.geocode(location)
        if not geo:
            raise ValueError(f"Could not geocode: {location}")
        center = (geo.latitude, geo.longitude)

        results = []
        for venue in self.venues:
            distance = geodesic(center, venue.coordinates).km
            if distance > radius_km:
                continue
            if venue.capacity < min_capacity:
                continue
            if venue.price_per_hour > max_price:
                continue
            if required_amenities:
                if not all(a in venue.amenities for a in required_amenities):
                    continue

            results.append({
                'venue': venue,
                'distance_km': round(distance, 2),
            })

        results.sort(key=lambda r: r['distance_km'])
        return results

    def compare(self, venues: List[Venue], weights: dict = None) -> List[dict]:
        """Score and rank venues by weighted criteria."""
        if weights is None:
            weights = {'capacity': 0.3, 'price': 0.3, 'rating': 0.4}

        max_cap = max(v.capacity for v in venues)
        max_price = max(v.price_per_hour for v in venues)
        max_rating = max(v.rating for v in venues) or 1

        scored = []
        for v in venues:
            score = (
                weights.get('capacity', 0) * (v.capacity / max_cap) +
                weights.get('price', 0) * (1 - v.price_per_hour / max_price) +
                weights.get('rating', 0) * (v.rating / max_rating)
            )
            scored.append({'venue': v.name, 'score': round(score, 3),
                           'capacity': v.capacity, 'price': v.price_per_hour})

        scored.sort(key=lambda s: s['score'], reverse=True)
        return scored

# Example
engine = VenueSearchEngine()
engine.add_venue(Venue("Grand Hall", "123 Main St, NYC", 40.7128, -74.0060,
                       500, ["wifi", "av", "catering", "parking"], 250, 4.5))
engine.add_venue(Venue("Tech Hub", "456 Broadway, NYC", 40.7210, -73.9985,
                       200, ["wifi", "av", "projector"], 150, 4.2))
engine.add_venue(Venue("Park Center", "789 Park Ave, NYC", 40.7650, -73.9720,
                       350, ["wifi", "av", "catering"], 200, 4.8))

results = engine.search("New York City", radius_km=15, min_capacity=100,
                         required_amenities=["wifi", "av"])
for r in results:
    v = r['venue']
    print(f"{v.name}: {v.capacity} cap, ${v.price_per_hour}/hr, "
          f"{r['distance_km']}km away")

Core Concepts

Venue Data Model

Field	Type	Description
name	string	Venue name
address	string	Physical address
coordinates	(lat, lon)	Geographic coordinates
capacity	integer	Maximum attendees
amenities	list	Available equipment/services
price_per_hour	float	Hourly rental rate
rating	float	User/review rating (0-5)
venue_type	string	conference, banquet, outdoor, theater
availability	dict	Available dates/times
contact	dict	Booking contact information
photos	list	Image URLs
accessibility	list	ADA compliance features

Multi-Criteria Venue Comparison

Copy
import pandas as pd
from dataclasses import dataclass
from typing import List, Dict

def venue_comparison_report(venues: List[dict], criteria_weights: Dict[str, float]) -> pd.DataFrame:
    """Generate a weighted comparison report for venue selection."""
    df = pd.DataFrame(venues)

    # Normalize each criterion to 0-1 scale
    normalized = pd.DataFrame()
    normalized['venue'] = df['name']

    for criterion, weight in criteria_weights.items():
        if criterion in df.columns:
            col = df[criterion]
            if criterion == 'price':  # Lower is better
                normalized[criterion] = 1 - (col - col.min()) / (col.max() - col.min() + 1e-9)
            else:  # Higher is better
                normalized[criterion] = (col - col.min()) / (col.max() - col.min() + 1e-9)

    # Calculate weighted score
    normalized['total_score'] = sum(
        normalized[c] * w for c, w in criteria_weights.items()
        if c in normalized.columns
    )

    # Rank
    normalized = normalized.sort_values('total_score', ascending=False)
    normalized['rank'] = range(1, len(normalized) + 1)

    return normalized

# Example comparison
venues_data = [
    {"name": "Grand Hall", "capacity": 500, "price": 250,
     "rating": 4.5, "transit_score": 8},
    {"name": "Tech Hub", "capacity": 200, "price": 150,
     "rating": 4.2, "transit_score": 9},
    {"name": "Park Center", "capacity": 350, "price": 200,
     "rating": 4.8, "transit_score": 7},
    {"name": "Riverside", "capacity": 400, "price": 300,
     "rating": 4.6, "transit_score": 6},
]

weights = {"capacity": 0.2, "price": 0.3, "rating": 0.3, "transit_score": 0.2}
report = venue_comparison_report(venues_data, weights)
print(report.to_string(index=False))

Configuration

Parameter	Description	Default
search_radius	Maximum distance from center (km)	10
min_capacity	Minimum venue capacity	0
max_price	Maximum hourly rate	Unlimited
venue_types	Filter by venue type	All types
required_amenities	Must-have amenities	[]
sort_by	Sort results by field	"distance"
geocoder	Geocoding service	"nominatim"
comparison_weights	Criteria weights for scoring	Equal weights

Best Practices

1. Use geocoding to normalize location inputs — Users specify locations in various formats (addresses, city names, zip codes, landmarks). Always geocode to coordinates before computing distances. Cache geocoding results to avoid rate limits and improve response time.

2. Weight comparison criteria based on event type — Corporate events prioritize AV equipment and transit access. Weddings prioritize ambiance and catering. Academic conferences prioritize capacity and price. Let users customize weights rather than using fixed formulas.

3. Include accessibility as a required filter, not a bonus — ADA compliance and accessibility features should be filterable requirements, not scoring bonuses. This ensures inclusive event planning and compliance with accessibility regulations.

4. Verify venue data freshness before presenting results — Venue availability, pricing, and amenities change frequently. Include last-updated timestamps and flag stale data. Ideally, integrate with venue management systems for real-time availability.

5. Calculate total event cost, not just hourly rate — Hourly rental rate is misleading without including catering minimums, AV equipment fees, setup/teardown charges, and service charges. Build a total cost estimator that accounts for all fee components.

Common Issues

Geocoding returns wrong location for ambiguous place names — "Springfield" exists in 30+ US states. Always include state or country in location queries, or prompt users to confirm the geocoded location on a map before searching. Use reverse geocoding to display the resolved location.

Distance calculations are inaccurate for large areas — The haversine formula (used by geopy) assumes a spherical earth and has ~0.3% error. For venue searches within a city (< 50 km), this error is negligible. For regional searches, the error is still acceptable for ranking purposes.

Venue search returns no results within radius — Expand the search radius gradually (10km → 25km → 50km) and inform the user. Also suggest relaxing filters: removing one amenity requirement or reducing capacity threshold often unlocks more options.