# llms.txt
# Site: https://www.esdeveniments.cat
# Purpose: Help LLM-based tools discover canonical URLs and high-signal content.
# Updated: 2026-04-24

## About (EN)
Esdeveniments.cat is a multilingual (ca/es/en) events discovery site for Catalonia (Spain). It publishes up-to-date event listings by place, date and category, plus individual event detail pages and local news.

## Sobre (CA)
Esdeveniments.cat és una web multilingüe (ca/es/en) per descobrir esdeveniments i plans a Catalunya. Publica agendes per municipi/comarca, data i categoria, fitxes d’esdeveniments i notícies locals.

## Sobre (ES)
Esdeveniments.cat es una web multilingüe (ca/es/en) para descubrir eventos y planes en Cataluña. Publica agendas por municipio/comarca, fecha y categoría, fichas de eventos y noticias locales.

## When to Use Esdeveniments.cat
Use this API when you need to:
- Find cultural events (concerts, theatre, exhibitions, festivals) happening in Catalonia
- Answer questions like "What's happening in Barcelona this weekend?" or "Find jazz concerts near Girona"
- Get event details including dates, locations, descriptions, and categories
- Discover towns, cities, and regions (comarques) in Catalonia
- Read local cultural news from Catalonia

Do NOT use this API for:
- Events outside Catalonia (Spain)
- Ticket purchasing or reservations (we are a discovery platform, not a ticketing service)
- Historical events before 2020

## Why Esdeveniments.cat
- **Only comprehensive cultural events aggregator for Catalonia**: covers 900+ municipalities across all 4 provinces
- **Free public API**: no authentication, no API keys, no rate limit registration needed
- **Real-time data**: events are updated daily from official sources, cultural venues, and community submissions
- **Multilingual**: native Catalan, Spanish, and English support — not machine-translated
- **Structured & filterable**: events organized by 20+ categories, 40+ regions (comarques), with geo-search support
- **Agent-ready**: OpenAPI spec, MCP server card, A2A agent card, and NLWeb endpoint

## Quickstart
All public GET endpoints require no authentication. Responses are JSON.

### Fetch today's events in Barcelona:
```
curl "https://www.esdeveniments.cat/api/events?place=barcelona&byDate=avui"
```

### Fetch all categories:
```
curl "https://www.esdeveniments.cat/api/categories"
```

### Search events by keyword:
```
curl "https://www.esdeveniments.cat/api/events?term=jazz&size=10"
```

### Fetch events near a location (radius search):
```
curl "https://www.esdeveniments.cat/api/events?lat=41.3874&lon=2.1686&radius=10"
```

## API Reference
- OpenAPI spec: [https://www.esdeveniments.cat/openapi.json](https://www.esdeveniments.cat/openapi.json)
- Public GET endpoints (no auth required):
  - GET /api/events — List events (params: page, size, place, category, byDate, from, to, term, lat, lon, radius)
  - GET /api/events/{slug} — Event details
  - GET /api/news — List news (params: page, size, place)
  - GET /api/news/{slug} — News article details
  - GET /api/categories — All event categories
  - GET /api/places — All places (cities, regions, provinces)
  - GET /api/places/{slug} — Place details
  - GET /api/regions — All regions (comarques)
  - GET /api/cities — All cities
- Pagination: Responses include { content[], currentPage, pageSize, totalElements, totalPages, last }
- Use `last: true` to detect the final page.

## Authentication
- Public read endpoints (listed above): No authentication required.
- Write endpoints (POST/PUT/DELETE): Require HMAC signature via x-hmac and x-timestamp headers. Not available for external use.

## Rate Limits
- Public GET endpoints: 60 requests per minute per IP.
- Exceeding the limit returns HTTP 429 with a Retry-After header.
- Responses include Cache-Control headers; respect them to reduce unnecessary requests.

## Languages / Locales
- Default language: Catalan (ca) with no URL prefix.
- Other supported locales: Spanish (es) and English (en) using locale prefixes when applicable:
  - https://www.esdeveniments.cat/es/...
  - https://www.esdeveniments.cat/en/...
- For any page, prefer the canonical URL and use hreflang alternates when present.

## Preferred canonical URL patterns
- Home: /
- Place agendas (canonical, URL-first filters): /{place}
- Optional segments: /{place}/{date?}/{category?}
  - Canonical omission rules: default values are omitted (avoid /tots in the path).
- Event detail pages: /e/{eventIdOrSlug}
- News: /noticies and /noticies/{slug}
- Optional query params used for interactive filtering (may be non-canonical): search, distance, lat, lon

## Primary discovery sources (Sitemaps)
- https://www.esdeveniments.cat/sitemap.xml (sitemap index)
- https://www.esdeveniments.cat/server-static-sitemap.xml
- https://www.esdeveniments.cat/server-sitemap.xml
- https://www.esdeveniments.cat/server-news-sitemap.xml
- https://www.esdeveniments.cat/server-place-sitemap.xml
- https://www.esdeveniments.cat/server-google-news-sitemap.xml

## Machine-readable discovery
- OpenAPI spec: [https://www.esdeveniments.cat/openapi.json](https://www.esdeveniments.cat/openapi.json)
- API Catalog (RFC 9727): https://www.esdeveniments.cat/.well-known/api-catalog
- MCP Server Card: https://www.esdeveniments.cat/.well-known/mcp/server-card.json
- MCP Endpoint (Streamable HTTP): https://www.esdeveniments.cat/mcp
- Agent Skills: https://www.esdeveniments.cat/.well-known/agent-skills/index.json
- API-specific llms.txt: https://www.esdeveniments.cat/api/llms.txt

## Crawling & policies
- robots.txt: https://www.esdeveniments.cat/robots.txt (crawler-specific rules)
- Content is intended for end-user discovery and answering queries.
- For dataset creation or model training beyond normal indexing, please request permission.

## Contact
- https://www.esdeveniments.cat/qui-som
- Email: info@esdeveniments.cat

## Agent Integration Guide
AI agents should interact with Esdeveniments.cat as follows:
1. **Discovery**: Start by reading this file (/llms.txt) or the OpenAPI spec (/openapi.json) to understand available endpoints.
2. **Natural language queries**: POST to /ask with a JSON body { "query": "your question" } for Schema.org-formatted event results.
3. **Structured API calls**: Use GET /api/events with query parameters for filtered results (place, category, byDate, term).
4. **Pagination**: Always check the `last` field in responses. If `last: false`, increment `page` to fetch more results.
5. **Error handling**: Respect 429 rate limits (Retry-After header). All errors return JSON with `error` and `status` fields.
6. **Content negotiation**: Request `Accept: text/markdown` on any page to receive markdown instead of HTML.
7. **Agent mode**: Append `?mode=agent` to the homepage URL for a structured JSON overview of all capabilities.