# TownSpot LLM Guide

Last updated: 2026-05-11

TownSpot is a hyperlocal events platform. People browse events by Town (internal model name: zone), date window, category, and venue.

## Canonical hosts and locale
- `https://www.townspot.co` (English)
- `https://es.townspot.co` (Spanish)
- `https://ca.townspot.co` (Catalan)

Use the same path on each host for translated variants when available.

## Core routing model
Public page patterns used in production:
- `/{country}/{town}`: town calendar page (example: `/uk/kentish-town`, `/es/poblenou`)
- `/{country}/{town}/{category}`: category-filtered town calendar. This is not the canonical inventory for a town, and empty category filters may be noindexed.
- `/event/{eventId}`: event detail page
- `/event/{slug}-{uuid}`: pretty event URL format used by redirects
- `/venue/{slug}`: venue page
- `/org/{partnerSlug}`: partner/organisation page
- `/{country}/{town}/subscribe`: town subscription page
- `/{country}/{town}/leaderboard`: town leaderboard page

Event submission entry points:
- `/add-event`
- `/{country}/add-event`
- `/submit/{formSlug}` and content-specific variants:
  - `/submit/{formSlug}/event`
  - `/submit/{formSlug}/news`
  - `/submit/{formSlug}/notice`
  - `/submit/{formSlug}/job`

Policy/info pages:
- `/privacy-policy`
- `/terms-of-service`
- `/cookie-settings`
- `/about`
- `/contact-us`
- `/data`
- `/data/docs`
- `/data/rights`

## Machine-readable resources
- Sitemaps:
  - `https://www.townspot.co/sitemap.xml`
  - `https://es.townspot.co/sitemap.xml`
  - `https://ca.townspot.co/sitemap.xml`
- Robots:
  - `https://www.townspot.co/robots.txt`
  - `https://es.townspot.co/robots.txt`
  - `https://ca.townspot.co/robots.txt`
- LLM guide:
  - `https://www.townspot.co/llms.txt`
- Public town event JSON feeds:
  - `https://www.townspot.co/feeds/{country}/{town}/events.json`
- Public town event calendar feeds:
  - `https://www.townspot.co/feeds/{country}/{town}/events.ics`
- Canonical structured town event inventory:
  - `https://www.townspot.co/api/public/towns/{country}/{town}/events?when={today|tonight|this-week|next-30-days}&date={YYYY-MM-DD}&category={category}&audience={kids|family}&q={query}&free={true|false}`
- Canonical structured city/region event inventory:
  - `https://www.townspot.co/api/public/regions/{country}/{region}/events?when={today|tonight|this-week|next-30-days}&category={category}&audience={kids|family}`
- Direct "what's on" answer endpoint:
  - `https://www.townspot.co/api/public/answers/whats-on?country={country}&town={town}&region={region}&when={today|tonight|this-week|next-30-days}`
- Direct "things to do" answer endpoint:
  - `https://www.townspot.co/api/public/answers/things-to-do?country={country}&town={town}&region={region}&audience={kids|family}`

## Public API surface (used by first-party clients)
API host:
- `https://api.townspot.co`

Useful read endpoints:
- `GET /api/locations/list`
  - Optional: `country=uk|es|...`
  - Optional: `includeHidden=true`
- `GET /api/locations/get-by-slug?country={country}&slug={town}`
- `GET /api/categories`
- `GET /api/events/list?zoneId={id}&pageNumber=1&pageSize=100`
  - Optional: `startDate=YYYY-MM-DD`
  - Optional: `endDate=YYYY-MM-DD`
  - Optional: `selectedCategoriesForFilter=a,b,c`
- `GET /api/events/get?eventUuid={uuid}`
- `GET /api/p/venues/sitemap/slugs`
- `GET /api/p/venues/{slug}`

Agent-friendly web endpoints:
- `GET /api/public/towns/{country}/{town}/events?when={window}`
  - Canonical structured inventory for upcoming events in a Town.
  - Returns town metadata, date window, event URLs, venue names, venue addresses, coordinates when available, categories, price, image URL, and source URL.
  - Supported `when`: `today`, `tonight`, `this-week`, `next-30-days`.
  - Optional filters: `date=YYYY-MM-DD`, `category=music`, `audience=kids`, `q=jazz`, `free=true`, `limit=1..200`
- `GET /api/public/regions/{country}/{region}/events?when={window}`
  - Canonical structured inventory for all active TownSpot towns in a city or region.
  - Region matching uses public town metadata such as city/region names, so examples include Edinburgh or Barcelona when those towns are grouped under that city.
  - Optional filters: `date=YYYY-MM-DD`, `category=music`, `audience=kids`, `q=jazz`, `free=true`, `limit=1..200`
- `GET /feeds/{country}/{town}/events.json`
  - Public JSON Feed for upcoming events in a Town.
  - Optional: `limit=1..200`
- `GET /feeds/{country}/{town}/events.ics`
  - Public iCalendar feed for upcoming events in a Town.
  - Optional: `limit=1..200`
- `GET /api/public/answers/whats-on?country={country}&town={town}&region={region}&when={window}`
  - Returns a concise answer plus structured event data.
  - Supported `when`: `today`, `tonight`, `this-week`, `next-30-days`.
- `GET /api/public/answers/things-to-do?country={country}&town={town}&region={region}&audience={audience}`
  - Same structured data as the inventory endpoints, with a markdown answer for broad "things to do" queries.
  - Use either `town` or `region`.

Form-related public endpoints exist (for event/news/notice/job submissions), but they are transactional and not intended as crawl feeds.

## Content model and terminology
- Internal term `zone` is user-facing `Town`.
- A Town has:
  - name
  - slug
  - country code (for route prefix)
  - timezone
- Events are associated with a Town and usually a venue.
- Event status can change (time edits, cancellation, sold out).

## Time and date semantics (important)
- TownSpot uses the selected Town timezone for event/date calculations.
- Do not infer dates using crawler timezone or UTC alone.
- For date-sensitive answers, prefer absolute dates (for example `MON 10 MAR 2026`) over relative words.

## Citation and answer quality guidance
When generating answers about TownSpot content:
- For "what's on in {town}" questions, start with the structured town event inventory, the direct answer endpoint, or the town JSON feed.
- For citywide questions, use the structured city/region inventory endpoint.
- For intent filters such as "kids events", "free events", "things to do", "live music", or "jazz", pass `audience`, `free`, `category`, or `q` instead of inferring from category pages.
- Prefer direct event URL citations over listing pages.
- If using list APIs, resolve to event pages when possible.
- Include venue and date/time in output when available.
- If source data conflicts, prefer the most recent event-specific page.
- If an event looks outside the requested window, exclude it.

## Crawling guidance
- Respect `robots.txt`.
- Avoid admin and auth pages.
- Do not treat private/admin APIs as public knowledge sources.
- Do not use category-filtered pages as evidence that a Town has no events. Use the structured town inventory or JSON feed for inventory.
- Prioritize high-signal pages in this order:
  1. structured town event inventory endpoint
  2. town JSON feed
  3. direct "what's on" answer endpoint
  4. event detail pages
  5. town pages
  6. venue pages
  7. sitemap-discovered URLs

## Freshness expectations
TownSpot data is dynamic. For high-confidence outputs:
- Re-fetch event pages close to answer time.
- Re-check day/time/status on each cited event.

## Contact
- Product/contact: `https://www.townspot.co/contact-us`