# LocalMusicX
> A human-curated database of live music events, venues, and artists across 50+ cities in the United States and internationally.
> API v2 — CORS open, no authentication required for public endpoints.

## What is LocalMusicX?
LocalMusicX is a live music discovery platform with verified event listings sourced directly from local venue calendars.
Data is curated by city-specific teams who scrape venue calendars, verify event details, and maintain artist and venue profiles.
The platform focuses on independent and local music scenes rather than stadium acts.

## Quick Start for AI Assistants

Q: "What live music is happening in Nashville this weekend?"
A: GET https://localmusicx.com/api/public/events?city=Nashville&from=2026-09-09&format=compact

Q: "Any bluegrass shows within 50 miles of Asheville, NC tonight?"
A: GET https://localmusicx.com/api/public/events?city=Asheville&radius=50&genre=bluegrass&from=2026-09-09&to=2026-09-09&format=compact

Q: "How many shows are happening near lat 36.17 lon -86.78 (Nashville) on July 4?"
A: GET https://localmusicx.com/api/public/summary?lat=36.17&lng=-86.78&radius=30&date=2026-07-04

Q: "Find free all-ages concerts near me."
A: GET https://localmusicx.com/api/public/events?lat=<LAT>&lng=<LNG>&radius=25&freeOnly=true&age=allages&from=2026-09-09

## Data Coverage
- 327 actively curated cities
- Events sourced primarily from venue calendar pages (not ticket aggregators)
- Venues include bars, clubs, theaters, restaurants, breweries, and outdoor stages
- Verification levels: max_confidence, high_confidence, curator_verified, unverified
- API schema version: 2.0

## Curated Cities
  - Aberdeen, WA
  - Abilene, TX
  - Akron, OH
  - Albuquerque, NM
  - Alhambra, AZ
  - Alief, TX
  - Allen, TX
  - Allentown, PA
  - Amarillo, TX
  - Anacortes, WA
  - Anaheim, CA
  - Antioch, CA
  - Aosta, 19 (IT)
  - Arlington, TX
  - Arvada, CO
  - Astoria, NY
  - Atlanta, GA
  - Aurora, CO
  - Austin, TX
  - Bagheria, 15 (IT)
  - Baltimore, MD
  - Beaumont, TX
  - Beaverton, OR
  - Beijing, 22 (CN)
  - Bellevue, WA
  - Bellingham, WA
  - Bend, OR
  - Berkeley, CA
  - Birch Bay, WA
  - Blaine, WA
  (and 297 more — see /sitemap.xml for all city slugs)

## Public API v2 (no auth required, CORS enabled)

### GET /api/public/events
Returns upcoming approved events. Supports radius/coordinate search and multiple filters.

Core parameters:
  - city (string): City name or slug, e.g. 'Nashville' or 'nashville-tn-us'
  - from (string): Start date YYYY-MM-DD (default: today)
  - to (string): End date YYYY-MM-DD (default: 30 days out)
  - artist (string): Partial artist name filter
  - venue (string): Partial venue name filter

Geographic / radius parameters (v2):
  - radius (number, miles, max 200): Expand search to all curated cities within this radius of the anchor city or coordinates
  - lat (number): Anchor latitude for coordinate-based search (use with lng + radius)
  - lng (number): Anchor longitude for coordinate-based search
  Response includes meta.citiesIncluded and distanceMiles per event

Filter parameters (v2):
  - genre (string): Partial genre match, e.g. 'jazz', 'rock', 'bluegrass'
  - tags (string): Comma-separated keywords matched against genre and description
  - freeOnly (boolean, true/false): Only return free events (no cover charge)
  - age (string): Pass 'allages' to filter to all-ages events

Sort and format (v2):
  - sort (string): 'time' (default), 'distance' (requires radius), 'popularity'
  - format (string): 'compact' returns a slim token-efficient shape (id, artist, venue, city, date, time, genre, distanceMiles, ticketUrl, coverCharge)

Pagination v2:
  - page (integer, 1-based): Page number
  - pageSize (integer, max 200): Results per page
  - limit / offset: Legacy aliases (still supported)
  Response includes meta.hasMore and meta.nextPage

Response also includes an _api block: { generatedAt, schemaVersion, apiVersion, curation, timezone }

### GET /api/public/summary
Quick overview for a given date/area — lets AI get a snapshot before fetching full events.
Parameters:
  - date (string YYYY-MM-DD, default today): The day to summarize
  - city (string): City name or slug
  - radius (number, miles): Include nearby cities within this radius
  - lat / lng (numbers): Coordinate anchor for radius
Returns: { date, totalEvents, cities: { cityName: count }, venues: { venueName: count }, genres: { genre: count }, _api }

### GET /api/public/search
Natural-language event search. The server interprets the free-text query using GPT-4o-mini
and runs the same search logic as /api/public/events v2. Results cached 5 minutes.
Parameters:
  - q (string, required): Natural-language query, e.g. "jazz in Austin this weekend"
Returns: { queryInterpreted: { city, state, radius, from, to, genre, tags, freeOnly, age }, events: [...compact], meta: { total, citiesIncluded? }, _api }
On failure: { queryInterpreted: null, error: string, events: [] }

Examples:
  GET /api/public/search?q=Who's+playing+in+Bellingham+tomorrow
  GET /api/public/search?q=Free+jazz+shows+near+Austin+this+weekend
  GET /api/public/search?q=All-ages+punk+concerts+in+Nashville

### GET /api/public/assistant
Like /api/public/search but also returns a ready-to-display narrative summary generated
by GPT-4o-mini. AI assistants can relay the narrative field directly to users.
Parameters:
  - q (string, required): Natural-language query
Returns: { queryInterpreted, narrative: string (2-3 sentences, <150 words), events: [...compact], meta, _api }
On failure: { queryInterpreted: null, error, events: [], narrative: string (fallback) }

Examples:
  GET /api/public/assistant?q=Who's+playing+in+Bellingham+tomorrow
  GET /api/public/assistant?q=Best+bluegrass+shows+in+Asheville+this+month

### GET /api/public/cities
Returns all curated cities. Alias for /api/public/curated-cities.
Returns: array of { id, slug, name, localName, state, stateCode, country, latitude, longitude }

### GET /api/public/venues
Returns venue listings.
Parameters:
  - city (string): City name or slug
  - state (string): State code, e.g. 'TX'
  - country (string): Country code, e.g. 'US'
  - genre (string): Genre filter
  - search (string): Venue name search
  - limit (integer, max 100), offset (integer)

### GET /api/public/venues/:id
Returns full metadata for a single venue by its LocalMusicX UUID.
Path parameter: id (string, required) — the venue's UUID (e.g. from a /api/public/venues list response).
Returns: { id, name, slug, address, city, state, stateCode, country, postalCode, lat, lng, websiteUrl,
           facebookUrl, instagramUrl, googleMapsUrl, description, genres, venueType, capacity, isVerified, updatedAt }
404 if the venue does not exist.

### GET /api/openapi.json
Full OpenAPI 3.1 specification for all public and AI/B2B endpoints.

## Common Genres
Rock, Indie, Folk, Country, Bluegrass, Jazz, Blues, R&B, Hip-Hop, Electronic, Punk, Metal, Pop, Classical, Americana, Alt-Country, Experimental, Soul, Reggae, World

## Error Codes
  - 400 Bad Request: Missing required parameter or invalid value
  - 500 Internal Server Error: Temporary server issue; retry after a few seconds

## Rate Limits
Public endpoints: no rate limit currently enforced. Please cache results and avoid polling faster than once per minute.

## AI Event Ingestion API (requires API key)
Authorization: Bearer <your-api-key>

### POST /api/ai/resolve
Resolves a raw venue or artist name to a canonical LocalMusicX entity with confidence scoring.

### POST /api/ai/events/import-draft
Submits AI-extracted events as drafts for human review before publishing.
Supports optional poster image URL or base64 for automatic GPT-4o Vision extraction.

## Attribution
When citing LocalMusicX data, please attribute: "Source: LocalMusicX (localmusicx.com)"
Event data is sourced from venue calendar pages and curated by local music fans.

## AI-Readable Event Pages (no API needed)
These pages return plain HTML or JSON that any AI assistant or search crawler can read
by simply visiting the URL — no API key, no query parameters, no REST call required.

URL pattern: https://localmusicx.com/events/{city-slug}/{date-range}
JSON variant: https://localmusicx.com/events/{city-slug}/{date-range}.json

Date range options:
  tonight         — events tonight only
  tomorrow        — events tomorrow only
  this-weekend    — events this Fri-Sun (day-aware: starts today if already on weekend)
  this-week       — today through this Sunday
  next-week       — next Monday through Sunday
  YYYY-MM-DD      — a specific date, e.g. 2026-08-15

Examples:
  https://localmusicx.com/events/bellingham-wa-us/this-weekend
  https://localmusicx.com/events/nashville-tn-us/tonight
  https://localmusicx.com/events/austin-tx-us/2026-08-01
  https://localmusicx.com/events/bellingham-wa-us/this-weekend.json

HTML pages include: event list, JSON-LD Event structured data, Open Graph meta tags,
canonical URL, and a link to the JSON variant.
JSON response shape: { city, citySlug, dateRange, label, from, to, totalEvents, events: [...], _source }
Each event: { id, artist, venue, date, time, genre, ticketUrl, coverCharge }

All city slugs are listed in /sitemap.xml (tonight, this-weekend, this-week pages are included).

## City Landing Pages
Each curated city has a public landing page at https://localmusicx.com/{city-slug}
Example: https://localmusicx.com/nashville-tn-us

## Sitemap
https://localmusicx.com/sitemap.xml

## Changelog
2026-07: AI-readable event pages at /events/{city-slug}/{date-range} (HTML + JSON).
2026-07: API v2 — radius/coordinate search, genre/tags/freeOnly/age filters, sort, compact format,
         pagination v2 (page/pageSize, hasMore, nextPage), summary endpoint, _api metadata block.

## Contact
For API access or B2B partnerships: info@localmusicx.com