tl-live-music-data（tl 现场音乐数据）

Live Music Data APIs

Reference documentation for live music data APIs and how they connect via external IDs. Covers artist metadata, concert events, setlists, and images across multiple providers.

When to Use

• "How do I get concert data for an artist?"
• "Which API should I use for setlists?"
• "Where can I get music livestream data?"
• "How do I resolve artist IDs across platforms?"
• Building applications that need artist metadata, concert events, livestreams, or setlists
• Resolving artist identities across multiple platforms
• Integrating live music data APIs

Outcomes

• Analysis: API selection based on data requirements
• Reference: Endpoint documentation, auth patterns, rate limits
• Decision: ID resolution strategy (MBID hub vs name search)

API Quick Reference

Tier 1: Core APIs (High Value, Easy Access)

Tier 2: Events and Concerts

Tier 3: Supplementary Data

Tier 4: Avoid / Difficult Access

Web Scraping Fallback

When APIs are unavailable (Tier 4) or rate-limited, use web scraping as a fallback. Workflow escalation: search → scrape → crawl.

# Scrape a single artist page to markdown
firecrawl scrape "https://www.allmusic.com/artist/mn0000004789" --only-main-content -o .firecrawl/artist.md

# Wait for JS rendering (SPA sites)
firecrawl scrape "<url>" --wait-for 3000 -o .firecrawl/page.md

# Extract structured data with a query
firecrawl scrape "https://example.com/artist" --query "What are the upcoming tour dates?"

Best practices for music data scraping:

• Respect robots.txt and rate limit aggressively (1-2 req/sec)
• Cache scraped content for 7+ days
• Prefer APIs when available - scraping breaks when sites change
• Use --only-main-content to skip navigation/ads

See firecrawl/cli skills for comprehensive scraping patterns.

ID Mapping Architecture

MusicBrainz serves as the central ID hub. Most services either accept MBID directly or can be resolved via MusicBrainz url-rels.

flowchart LR
    subgraph hub [ID Hub]
        MB[MusicBrainz<br/>MBID]
    end

    subgraph direct [Accept MBID]
        Setlist[Setlist.fm]
        Fanart[Fanart.tv]
        Lastfm[Last.fm]
    end

    subgraph multi [Multi-ID Lookup]
        JamBase[JamBase<br/>15 ID sources for events]
    end

    subgraph linked [Via url-rels]
        Discogs[Discogs]
        Wikidata[Wikidata]
        Spotify[Spotify]
    end

    subgraph name [Name Search Only]
        Bandsintown[Bandsintown]
        TM[Ticketmaster]
        Genius[Genius]
    end

    MB -->|MBID| direct
    MB -->|MBID or external ID| multi
    MB -->|url-rels lookup| linked
    MB -.->|artist name| name

Services That Accept MBID Directly

Services Requiring url-rels Lookup

Get external IDs from MusicBrainz first:

GET /ws/2/artist/{mbid}?inc=url-rels&fmt=json

Returns IDs for: spotify, discogs, wikidata, allmusic, lastfm, imdb, bandcamp, soundcloud, youtube

JamBase Multi-ID Support

JamBase v3 accepts different source slugs per resource. Use {source}:{id} everywhere an ID is accepted.

Events (15 sources): axs, dice, etix, eventbrite, eventim-de, jambase, seated, seatgeek, see-tickets, see-tickets-uk, sofar-sounds, suitehop, ticketmaster, tixr, viagogo

Artists (12 sources): axs, dice, etix, eventbrite, eventim-de, jambase, musicbrainz, seated, seatgeek, spotify, ticketmaster, viagogo

Venues (11 sources): axs, dice, etix, eventbrite, eventim-de, jambase, seated, seatgeek, suitehop, ticketmaster, viagogo

Streams: jambase only (as of v3.0.0).

/v3/events/id/{source}:{id}
/v3/artists/id/{source}:{id}
/v3/venues/id/{source}:{id}

Environment Variables

# Tier 1
MUSICBRAINZ_USER_AGENT="AppName/1.0 (contact@example.com)"
SETLISTFM_API_KEY=""
DISCOGS_TOKEN=""

# Tier 2
JAMBASE_API_KEY=""
SONGKICK_API_KEY=""
BANDSINTOWN_APP_ID=""
TICKETMASTER_API_KEY=""

# Tier 3
LASTFM_API_KEY=""
FANARTTV_API_KEY=""
THEAUDIODB_API_KEY=""
GENIUS_ACCESS_TOKEN=""

API Selection Guide

ID Resolution Strategy

Starting with Artist Name

1. Search MusicBrainz for MBID
2. Use MBID to get external IDs via url-rels
3. Use external IDs with other services

Starting with Existing ID (Spotify, etc.)

1. Use JamBase /v3/artists/id/{source}:{id} for direct lookup
2. Or lookup in Wikidata via property (P1902 for Spotify)
3. Resolve to MBID for other services

Rate Limit Summary

OAuth 2.0 Patterns

See OAuth 2.0 Patterns for the full Spotify Authorization Code + PKCE flow, the token refresh pattern, and recommended scopes per provider.

Pagination Patterns

See Pagination Patterns for cursor-based vs offset-based async iterators and the per-API pagination parameter table.

Error Handling Matrix

See Error Handling for the full retry strategy table by HTTP code, the fetchWithRetry implementation, and API-specific error code interpretations.

Caching Recommendations

Local Data Architecture

See Local Data Architecture for replica decision criteria, the external-ID-mapping schema (entities, entity_source_ids, sync_state), incremental sync patterns with overlap windows, ID resolution flow, the enrichment pipeline, and deletion/merge handling.

Detailed Reference Files

Each API has comprehensive documentation in the references/ folder:

• musicbrainz.md - ID hub, url-rels, search, rate limiting
• setlistfm.md - Setlist search, MBID integration, response schemas
• jambase.md - v3 events, streams, venues, artists, geographies, lookups, multi-source ID
• discogs.md - Discography, releases, rate headers
• wikidata.md - SPARQL queries, property codes
• nugs.md - Undocumented API, catalog methods
• bandsintown.md - Artist events, date filters
• ticketmaster.md - Events, attractions, venues
• songkick.md - Gigography, calendar (keys suspended)
• lastfm.md - Similar artists, tags, scrobbles
• fanarttv.md - High-res images via MBID
• theaudiodb.md - Metadata, images, free vs premium
• genius.md - Annotations, OAuth, no lyrics via API

Skill Maintenance

Keeping References Current

Each reference file includes a "Keeping Current" section with:

• Authoritative docs - Official documentation links
• Version detection - How to check for API changes
• Test endpoint - Quick verification command
• Last verified - When this reference was last validated

Monitoring for Changes

Update Triggers

Re-verify a reference when:

• API returns unexpected errors
• New features announced in changelog
• Response structure differs from documented
• Rate limits or auth requirements change

Contribution

To update this skill:

1. Verify changes against official docs
2. Test endpoints with real API calls
3. Update "Last Verified" date
4. Note breaking changes prominently

References

Quilted Skills

• firecrawl/cli/firecrawl-scrape — Web scraping patterns

First-Party API Documentation

• MusicBrainz API — ID hub, url-rels, JSON responses
• MusicBrainz JSON Web Service — JSON format details
• Setlist.fm API — Setlist search and retrieval
• JamBase Data API Reference — v3 events, streams, venues, artists, geographies, lookups
• JamBase Data llms-full.txt — full LLM-tuned reference
• JamBase Data OpenAPI 3.1 — versioned spec
• JamBase Data ai-plugin.json — discoverable plugin manifest
• Ticketmaster Discovery API — Events, attractions
• Spotify Web API — OAuth 2.0, artist data
• Spotify Authorization Guide — PKCE flow
• Discogs API — Discography, releases
• Last.fm API — Similar artists, tags
• Wikidata Query Service — SPARQL cross-references

Community Resources

• MusicBrainz Picard Documentation — Tagging patterns
• Wikidata SPARQL Examples — Cross-reference queries