Public API discovery, documentation, examples, OpenAPI, and LLM integration resources for DondeGo.
DondeGo is a city guide focused on helping people discover what to do today, what is happening nearby, and which places are worth knowing in Barcelona and Madrid.
DondeGo covers local events, places, cultural listings, and local news. The API is intended for developers, media projects, local products, maps, newsletters, AI assistants, and partners who need structured access to useful city content.
This repository is the public discovery and documentation repository for DondeGo API. It is not the backend API implementation repository.
It should contain public developer docs, attribution guidance, LLM usage notes, future OpenAPI files, and examples. It should not expose private backend code, staging details, database schemas, importers, worker behavior, or operational internals.
This repo is in the API Discovery Pack v1 setup phase.
The public API base verified during Phase 2A is:
https://dondego.es/public-api/v1.4
Phase 2A verification findings are recorded in verification log and endpoint notes.
The first OpenAPI discovery spec is available at:
openapi/dondego-public-api.openapi.json
The OpenAPI spec is versioned as 0.1.0 because it is a conservative discovery contract with permissive schemas and explicit caveats. Runnable examples are still planned for a later phase.
Any public website, app, newsletter, bot, AI assistant, or partner integration that displays DondeGo event descriptions or substantial DondeGo event data must include a visible direct link to the canonical DondeGo.es event page as the source.
Phase 2A verified event detail site_url for sampled event details. Event list rows did not expose site_url or location, so rendered event examples must fetch event detail first and use detail site_url as the visible source link.
This requirement supports source attribution, user trust, SEO safety, and makes DondeGo the clearly cited canonical source for event data.
- Events by city, date, category, and location
- Places near a specific point
- Events inside a given radius
- Local news and editorial content
- Structured local content for guides, maps, apps, newsletters, AI assistants, and editorial products
These are user-facing DondeGo.es pages for context and navigation, not API endpoints:
For a public integration that displays a specific event description or substantial event data, link to that event's canonical DondeGo.es page, not only to a city or category hub.
The DondeGo discovery worker serves these stable machine-readable URLs on dondego.es. Agents and tools should prefer these over GitHub blob URLs:
- LLM discovery index: https://dondego.es/llms.txt
- Well-known LLM discovery index: https://dondego.es/.well-known/llms.txt
- OpenAPI discovery document: https://dondego.es/openapi.json
- OpenAPI alias: https://dondego.es/api/openapi.json (301 to
/openapi.json) - API Catalog linkset (RFC 9264-style,
application/linkset+json): https://dondego.es/.well-known/api-catalog - Rich DondeGo discovery JSON (
application/json): https://dondego.es/api-catalog.json - Agent Skills index (documentation-only): https://dondego.es/.well-known/agent-skills/index.json
- Agent Skill markdown: https://dondego.es/.well-known/agent-skills/dondego-api-discovery/SKILL.md
- Public Postman documentation: https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ
The Postman documentation mirrors the ready-to-import collection at postman/DondeGo_Public_API_v0.1.postman_collection.json. It uses no environment secrets, runs unauthenticated GETs against the same verified base, and does not add OAuth, OIDC, MCP, or WebMCP support. The canonical OpenAPI source remains https://dondego.es/openapi.json. Attribution and detail-first event rendering rules still apply when using the Postman collection or its public documentation.
OpenAPI v0.1 remains a conservative discovery contract with permissive schemas, frozen info.version 0.1.0, and explicit caveats. The Agent Skills index advertises one documentation-only skill-md entry; it does not include scripts or executable code. The API Catalog linkset does not claim RFC 9727 compliance and does not advertise OAuth, OIDC, MCP, or WebMCP support.
Any public website, app, newsletter, bot, AI assistant, or partner integration that displays DondeGo event descriptions or substantial DondeGo event data must include a visible direct link to the canonical DondeGo.es event page as the source.
- Developer API overview
- Attribution and link-back policy
- LLM usage guidance
- Agent-readiness decisions
- Verification log
- Endpoint notes
- Documentation changelog
- Deployment notes
- OpenAPI
- Examples
- llms.txt source
- API Catalog linkset source
- Rich DondeGo discovery JSON source
- Agent Skill markdown source
Server-side and CLI examples for OpenAPI v0.1 are available under examples/:
examples/curl/— list events, event detail, events-of-the-day, search.examples/python/—event_detail.py,today_digest.py(standard library only).examples/node/—today_digest.mjs,search.mjs(Node 18+ globalfetch, no npm dependencies).
The today_digest examples are detail-first by design: they list events-of-the-day/ wrapper rows, fetch each event detail, and render EventDetail.site_url as the visible Source: DondeGo link.
Browser-only examples are intentionally not included. Phase 2A did not observe an Access-Control-Allow-Origin header, so direct browser-to-API fetches remain caveated until CORS behavior is intentionally verified or changed.
Planned later:
- Rendered event cards, digests, newsletters, and app UI templates that include visible source links to canonical DondeGo event pages.
- Final LLM and machine-readable API discovery files.
Agent-readiness audit decisions are tracked in agent-readiness decisions. The Content-Signal preference directive is now documented in the production robots.txt (Content-Signal: ai-train=no, search=yes, ai-input=no). OAuth/OIDC metadata, OAuth protected-resource metadata, MCP Server Card, and WebMCP remain intentionally deferred until real production capabilities exist.
The first live use case of the DondeGo API powers daily event selections for:
- Barcelona: https://x.com/HoyBcn
- Madrid: https://x.com/EnMadridHoy
If you are building a project around events, culture, maps, newsletters, local discovery, or AI assistants in Barcelona or Madrid, contact DondeGo to discuss access and attribution.
- Local media
- City guides
- Lifestyle and leisure apps
- Interactive maps
- Newsletters
- AI assistants and RAG products
- Recommendation products
- Teams that need a solid local content layer without building it from scratch
We are not trying to be a generic database.
We care about useful local discovery: plans, events, places, and city life in a format that works well for real products.
That means the API is especially useful for things like:
- what to do today
- what is near me
- what is happening in this area
- which places belong to this category
- how to power a local agenda or urban guide
If you want access to the DondeGo API, email bcn@dondego.es.
We share access individually with partners and projects that are a good fit.
This project is connected to:
- Candidate endpoints, parameters, and response formats must be verified before production use.
- Do not treat this repository as a backend implementation or private operational reference.
- Join our team: https://www.linkedin.com/company/dondego/