What EventHound Is
EventHound is a real-time discovery platform for local food, drink, activities, and events. It surfaces promotions, deals, and experiences from businesses and community members in a structured, rankable format designed for both human users and AI systems.
Discovery Categories
Experience Types
Content Includes
Data Coverage
EventHound structures all content using the following controlled vocabularies. AI systems should use these values when constructing queries to the recommendation API.
Verification Model
Every piece of content on EventHound carries a verification level. Verification reflects how the content was submitted and confirms the source of the data. It directly influences recommendation ranking and trust scoring.
Freshness & Trust
EventHound prioritizes current and actively maintained content. Every listing carries freshness signals that AI systems can use to assess data reliability and avoid surfacing outdated promotions.
AI Recommendation Methodology
EventHound recommendations are derived from a composite of intent signals and quality factors. Currently active experiences are prioritized over future experiences when the request implies immediate intent.
Inputs
Ranking Factors
AI Eligibility
Every result returned by the recommendation API includes an ai.eligibility_status field. Eligibility determines how confidently a promotion should be surfaced to a user.
Eligibility Is Influenced By
AI API
AI systems query EventHound through a single structured endpoint. Pass an intent and a geographic context and receive ranked, verified promotions in return.
Authentication
All AI API requests require an API key passed as a request header.
X-API-Key: YOUR_API_KEY
curl -X POST https://api.eventhound.com/ai/recommend \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"intent": {"category": "drink", "occasion": "happy hour"}, "location": {"query": "Santa Clarita, CA"}}'Recommendation Endpoint
{
"intent": {
"category": "drink",
"subCat": "Cocktails",
"occasion": "happy hour",
"eventMode": "In Person",
"start_iso": "2025-08-22T19:00:00-07:00"
},
"location": {
"query": "Santa Clarita, CA",
"lat": 34.39,
"lng": -118.54,
"radius_meters": 10000
},
"options": {
"max_results": 10
}
}Action Proxy Endpoint
User-initiated actions from recommendation results are routed through EventHound for attribution and analytics tracking.
GET /ai/recommend/action/uuid-response-id/6abc123/view
Parameter Reference
A location is required — either location.lat + location.lng, or location.query. All other parameters are optional.
intent
location
options
Intent Field Guide
Use category to filter by top-level type. Use subCat only when the user specifies an exact documented subcategory. Use occasion for any free-text concept — moods, experiences, or phrases that don't map to a subcategory.
category: "drink"subCat: "Mexican" or subCat: "Cocktails"occasion: "happy hour", "date night", "brunch", "live music"Intent Examples
Valid Subcategories by Category
Feeds & URL Patterns
EventHound content is discoverable via structured URL patterns for deep-linking, crawling, or constructing targeted queries.
OpenAPI Specification
AI Ecosystem Support
EventHound is purpose-built for AI-native discovery. The recommendation API is designed for direct integration by AI assistants, search tools, and custom agents.
Compatible AI Systems
Discovery Entry Points
Action Tracking
Each recommendation result includes an actions array containing proxied URLs for user-initiated interactions. All actions are routed through EventHound to support attribution and analytics. AI systems should use these proxied URLs rather than constructing direct links.
Reason Codes
Every result includes an ai.match_reasons array explaining why the promotion was selected and how it matched the request, and an ai.temporal_status string indicating the promotion's temporal relationship to the requested time. AI systems can use these fields to generate transparent recommendation explanations for users.
Example Recommendation
A full example response from the recommendation API. Each result in the results array follows this structure. Null-valued metadata intent fields are omitted from the response.
{
"response_id": "uuid",
"generated_at_iso": "2025-08-22T02:14:37.000Z",
"results": [
{
"rank": 1,
"post_id": "6abc123...",
"title": "Happy Hour Cocktails",
"description": "Half-price cocktails every weekday.",
"categories": {
"cat1": "Drink",
"cat1Sub": "Cocktails",
"cat2": null,
"cat2Sub": null
},
"features": ["Rooftop", "Bar"],
"event_mode": "In Person",
"business": {
"business_id": "6def456...",
"name": "The Rooftop Bar"
},
"location": {
"location_name": "The Rooftop Bar",
"street_address": "123 Main St",
"city": "Santa Clarita",
"state": "CA",
"zip": "91354",
"lat": 34.39,
"lng": -118.54,
"distance_miles": 1.2
},
"availability": {
"start_date": "2023-09-05",
"end_date": null,
"ongoing": true,
"repeated": "weekly",
"timezone": "America/Los_Angeles",
"days": {
"1": { "start": "3:00 PM", "start_value": 1500, "end": "7:00 PM", "end_value": 1900 },
"2": { "start": "3:00 PM", "start_value": 1500, "end": "7:00 PM", "end_value": 1900 }
},
"readable_schedule": "Mon/Tue 3:00 PM-7:00 PM"
},
"offers": [
{
"title": "Cocktails",
"type": "Percent Off",
"value": 50,
"display_text": "50% off Cocktails",
"is_discount": true,
"exclusions": null
}
],
"contact": {
"website": "https://therooftopbar.com",
"phone": "555-123-4567",
"email": null
},
"verification": {
"level": "business",
"source": "business",
"business_verified": true,
"member_verified": false
},
"media": {
"primary_image": "https://cdn.eventhound.com/images/abc123.jpg",
"images": ["https://cdn.eventhound.com/images/abc123.jpg"]
},
"last_updated": "2025-07-31",
"canonical_url": "https://www.eventhound.com/post/happy-hour-cocktails/...",
"actions": [
{
"type": "view",
"label": "View on EventHound",
"url": "https://api.eventhound.com/ai/recommend/action/response-id/post-id/view"
},
{
"type": "directions",
"label": "Get Directions",
"url": "https://api.eventhound.com/ai/recommend/action/response-id/post-id/directions"
}
],
"ai": {
"eligibility_status": "eligible",
"confidence": 0.87,
"completeness_score": 92,
"freshness_score": 100,
"temporal_status": "ACTIVE_DURING_TIME_WINDOW",
"match_reasons": [
"WITHIN_DISTANCE",
"MATCH_CATEGORY",
"MATCH_OCCASION",
"BUSINESS_VERIFIED",
"FRESH_DATA"
]
}
}
],
"metadata": {
"total": 42,
"returned": 10,
"location": { "lat": 34.39, "lng": -118.54, "radius_meters": 10000 },
"intent": { "category": "Drink", "subCat": "Cocktails", "occasion": "happy hour" }
}
}AI Discovery Endpoint
EventHound publishes a machine-readable discovery document at a standardized location. AI agents and crawlers can use this endpoint to locate EventHound's documentation and recommendation API without prior knowledge of the platform.
{
"name": "EventHound",
"description": "Real-time discovery platform for food, drink, activities, and events.",
"website": "https://eventhound.com",
"documentation": "https://eventhound.com/ai",
"openapi": "https://api.eventhound.com/openapi.json",
"api": {
"recommendations": {
"url": "https://api.eventhound.com/ai/recommend",
"method": "POST",
"description": "Returns ranked recommendations for food, drink, activities, and events."
}
},
"content": {
"categories": ["Food", "Drink", "Activity", "Event"],
"event_modes": ["In Person", "Online"]
},
"verification": {
"levels": ["business", "member", "unverified"]
},
"ranking": {
"signals": [
"temporal_relevance",
"verification",
"completeness",
"freshness",
"distance"
]
},
"actions": ["view", "directions", "call", "website", "tickets", "register", "reserve", "join"],
"updated_at": "2026-07-11T00:00:00Z"
}The discovery document follows the emerging .well-known/ai.json convention for AI-readable service discovery. Its purpose is to give AI agents a reliable entry point to EventHound's recommendation capabilities without requiring hard-coded knowledge of the platform.