ClawEvents 🎉

Multi-city event discovery — Tel Aviv, Barcelona, New York.

Triggers

• "What's on in Tel Aviv this weekend?"
• "Find jazz concerts in Barcelona next week"
• "Cinema in Tel Aviv tonight"
• "Free family events in NYC this Saturday"
• "Events in Tel Aviv and Barcelona for the group trip"
• "Lev Cinema schedule this week"
• "Live music in New York, adults only, evening"

CLI Usage

# Basic search
python3 -m clawevents search --city tel-aviv --days 7

# Jazz in Tel Aviv this week
python3 -m clawevents search --city tel-aviv --type jazz --days 7

# Cinema tonight (Lev + others)
python3 -m clawevents search --city tel-aviv --type cinema --days 1

# Multi-city: what's on in Barcelona and NYC this weekend
python3 -m clawevents search --city barcelona new-york --days 3

# Family events, free, afternoon
python3 -m clawevents search --city tel-aviv --type family --age family --time afternoon --free

# Concert, adults, evening, specific dates
python3 -m clawevents search --city tel-aviv barcelona --type concert --age adults --time evening --from 2026-06-21 --to 2026-06-27

# JSON output (for programmatic use)
python3 -m clawevents search --city new-york --type jazz --format json --limit 10

Supported Cities

| City | Alias | Sources | |------|-------|---------| | Tel Aviv | tel-aviv, tlv | TLV Municipality API, Eventbrite, Lev Cinema | | Barcelona | barcelona, bcn | Ticketmaster, Eventbrite | | New York | new-york, nyc | Ticketmaster, Eventbrite, NYC Open Data |

Event Types

jazz · concert / music · cinema / movie · theatre · nightlife · family / kids · comedy · art · sport · festival · community

Filters

| Flag | Values | Default | |------|--------|---------| | --type | jazz, concert, cinema, theatre, ... | all | | --age | kids, family, adults | all | | --time | morning, afternoon, evening, late-night | all | | --from / --to | YYYY-MM-DD | today / +7d | | --days | integer | 7 | | --free | flag | false | | --limit | integer | 20 | | --format | text, json | text |

Setup

Install dependencies

cd skills/clawevents
pip3 install -r requirements.txt

API Keys (optional but recommended)

| Key | Source | Cities unlocked | |-----|--------|-----------------| | TICKETMASTER_API_KEY | developer.ticketmaster.com — free | Barcelona, NYC | | EVENTBRITE_TOKEN | eventbrite.com/platform/api — free | All 3 | | TLV_API_KEY | apiportal.tel-aviv.gov.il — free | Tel Aviv (official events) |

Without API keys: Tel Aviv scrapes TLV website; Barcelona/NYC use Eventbrite free tier only + NYC Open Data.

Add to ~/.zshrc or ~/.bashrc:

export TICKETMASTER_API_KEY="your_key"
export EVENTBRITE_TOKEN="your_token"
export TLV_API_KEY="your_key"         # optional

Data Sources

Tel Aviv

• TLV Municipality API — Official city events (DigiTel source). Free with API key.
• Eventbrite — Tech, community, cultural events
• Lev Cinema — Boutique cinema (Dizengoff). Web scrape.
• (planned) Time Out Israel scraper — jazz, clubs, theatre picks

Barcelona

• Ticketmaster Discovery API — Concerts, theatre, sports, 230K+ events
• Eventbrite — Community + cultural events
• (planned) Fever/Xceed scraper — nightlife, club events, immersive experiences

New York

• Ticketmaster Discovery API — Concerts, Broadway, sports
• Eventbrite — Community events
• NYC Open Data — Free parks events, city programmes

Architecture

ClawEventsEngine
├── Fetchers (parallel, per-city)
│   ├── TLVMunicipalityFetcher  → Tel Aviv
│   ├── TicketmasterFetcher     → Barcelona, NYC
│   ├── EventbriteFetcher       → All cities
│   ├── LevCinemaFetcher        → Tel Aviv (cinema)
│   └── NYCOpenDataFetcher      → NYC (free events)
├── Filter layer  (types, age, time-of-day, date, free)
├── Dedup layer   (same title + time across sources)
└── Rank layer    (chronological, no-time events last)

Extending

To add a new city or source:

1. Create clawevents/fetchers/your_source.py implementing BaseFetcher
2. Register in _FETCHER_REGISTRY and _CITY_FETCHERS in engine.py
3. Add city alias in cli.py