Developers and AI discovery

API de DondeGo

Este repositorio es el punto publico de descubrimiento, documentacion, OpenAPI y guias para asistentes IA de la API de DondeGo: eventos, lugares y noticias locales de Barcelona y Madrid.

En DondeGo trabajamos con contenido local pensado para la vida real de la ciudad. Publicamos conciertos, exposiciones, teatro, festivales, ferias, actividades para niños, planes de temporada y propuestas urbanas que ayudan a responder una pregunta muy simple: qué hacer hoy y qué está pasando ahora mismo.

Este repositorio no es el backend de la API. Su funcion es ayudar a desarrolladores, medios, mapas, apps, newsletters, productos editoriales y asistentes IA a entender como descubrir e integrar la API publica sin exponer detalles internos de DondeGo.

Estado actual

La base publica verificada en la fase de descubrimiento es https://dondego.es/public-api/v1.4. La especificacion OpenAPI v0.1 esta disponible en este repositorio en openapi/dondego-public-api.openapi.json (info.version 0.1.0) y se sirve en vivo en https://dondego.es/openapi.json. El discovery pack se publica como release v0.1.1.

OpenAPI v0.1 es un contrato de descubrimiento conservador con esquemas permisivos. Cubre solo endpoints publicos verificados. Los filtros por fecha siguen sin verificar y no estan documentados. Los ejemplos ejecutables todavia estan planeados, no publicados.

Requisito de atribucion publica

Cualquier web, app, newsletter, bot, asistente IA o integracion publica que muestre descripciones de eventos de DondeGo o una parte sustancial de datos de eventos debe incluir un enlace visible y directo a la pagina canonica del evento en DondeGo.es como fuente.

El campo verificado de URL de pagina de evento es EventDetail.site_url en el detalle del evento. Las filas de listado de eventos no exponen site_url ni location, asi que las tarjetas, digests y ejemplos renderizados deben primero pedir el detalle GET /events/{id}/ y usar EventDetail.site_url como enlace visible a la fuente.

Familias de endpoints verificadas

OpenAPI v0.1 cubre las siguientes familias publicas verificadas en https://dondego.es/public-api/v1.4: 

GET /locations/
GET /events/
GET /events/{id}/
GET /places/
GET /places/{id}/
GET /news/
GET /news/{id}/
GET /events-of-the-day/
GET /search/?q=...

/events-of-the-day/ devuelve filas envoltorio, no objetos de evento completos: para renderizar datos sustanciales de un evento hay que resolver el detalle con GET /events/{id}/. /search/ es un endpoint experimental con resultados mixtos (ctype e item_url); el item_url de search no equivale al site_url verificado del detalle de evento para atribucion a menos que se verifique por tipo de resultado.

Familias root-index como categories, agents, lists, movies, showings, mixes, classifiers o tag-pages no estan incluidas en OpenAPI v0.1 porque no se han sondeado.

OpenAPI v0.1

La especificacion completa esta en openapi/dondego-public-api.openapi.json (OpenAPI 3.1.0, version 0.1.0). Notas de la spec y caveats viven en openapi/README.md.

Operaciones incluidas: listLocations, listEvents, getEvent, listPlaces, getPlace, listNews, getNews, listEventsOfTheDay y search.

No incluido en v0.1: filtros por fecha (sin verificar), parametro limit (no redujo el tamaño de pagina en las pruebas), familias root-index no sondeadas, detalles privados de backend, staging, importador, worker o base de datos, y tampoco superficies MCP, OAuth/OIDC o WebMCP como endpoints implementados.

CORS y ejemplos en navegador

La verificacion no observo cabecera Access-Control-Allow-Origin, asi que los ejemplos solo-navegador deben mantenerse con caveats. Prefiere ejemplos del lado servidor en Python, Node o curl mientras el comportamiento CORS no se verifique o cambie de forma intencionada.

URLs publicas de descubrimiento

El discovery worker de DondeGo sirve las siguientes URLs estables sobre dondego.es. Agentes y herramientas deberian usar estas antes que los blobs de GitHub: 

https://dondego.es/llms.txt
https://dondego.es/.well-known/llms.txt
https://dondego.es/openapi.json
https://dondego.es/api/openapi.json            (301 a /openapi.json)
https://dondego.es/.well-known/api-catalog     (application/linkset+json)
https://dondego.es/api-catalog.json            (application/json)
https://dondego.es/.well-known/agent-skills/index.json
https://dondego.es/.well-known/agent-skills/dondego-api-discovery/SKILL.md

/.well-known/api-catalog sirve un linkset estilo RFC 9264 con anchors y hrefs absolutos, e incluye una cabecera Link: <https://dondego.es/api-catalog.json>; rel="alternate"; type="application/json". /api-catalog.json preserva el JSON de descubrimiento mas rico de DondeGo. El indice de Agent Skills y su SKILL.md son solo documentacion: no contienen scripts ni codigo ejecutable, y no afirman soporte de OAuth, OIDC, MCP ni WebMCP.

Uso por LLMs y asistentes IA

Para asistentes y agentes el indice de descubrimiento esta en https://dondego.es/llms.txt y el catalogo en https://dondego.es/.well-known/api-catalog (linkset) y https://dondego.es/api-catalog.json (JSON rico). La guia de uso por LLMs vive en docs/llm-usage.md.

Las respuestas generadas por asistentes IA que muestren descripciones o datos sustanciales de eventos de DondeGo deben incluir un enlace visible al EventDetail.site_url verificado de cada evento.

Documentacion en este repositorio

README.md
openapi/dondego-public-api.openapi.json
openapi/README.md
docs/api-overview.md
docs/attribution.md
docs/llm-usage.md
docs/endpoint-notes.md
docs/verification-log.md
docs/changelog.md
examples/README.md
public/llms.txt
public/api-catalog.draft.json

Hay ejemplos server-side/CLI listos para usar en examples/README.md: curl en examples/curl/, Python (solo libreria estandar) en examples/python/ y Node 18+ (con fetch global, sin dependencias npm) en examples/node/. Los ejemplos today_digest aplican el patron detail-first: /events-of-the-day/ → /events/{id}/ → EventDetail.site_url.

No hay ejemplos solo-navegador en esta fase mientras CORS no se verifique. Los flujos de deploy publico para llms.txt, el catalogo de API y la spec OpenAPI siguen planeados para fases siguientes.

Paginas publicas de ejemplo

Estas paginas de DondeGo.es son referencias publicas para navegacion y contexto, no endpoints de la API:

Events in Barcelona · Events in Madrid today · Exhibitions in Madrid · Concerts in Barcelona

Estos enlaces de ciudad/categoria son utiles para navegacion y contexto y no sustituyen al enlace especifico a la pagina canonica del evento en DondeGo.es cuando se muestran descripciones o datos sustanciales de un evento concreto.

Para quién está pensada

La API de DondeGo puede ser útil para medios, apps de ocio, guías urbanas, mapas interactivos, newsletters locales, asistentes, productos de recomendación y cualquier proyecto que quiera trabajar con datos útiles sobre planes y lugares en la ciudad.

También es una buena base para equipos que necesitan una capa local bien estructurada sobre Barcelona y Madrid sin tener que construir ese dataset desde cero.

Una API pensada para producto

No queríamos publicar solo una base de datos. Queríamos ofrecer una capa reutilizable de contenido local con sentido editorial, útil para interfaces reales y fácil de integrar en productos digitales.

Por eso la API de DondeGo está orientada a consultas que suelen tener valor inmediato: qué hacer hoy, qué hay cerca de aquí, qué lugares entran en esta zona, qué eventos pertenecen a una categoría o qué contenido puede alimentar una agenda local.

Contacto

Si quieres acceder a la API, conocer la documentación o comentar tu caso de uso, escríbenos a bcn@dondego.es.

Esta pagina resume el discovery pack publico y la OpenAPI v0.1 actual. Para el contrato tecnico consulta directamente openapi/dondego-public-api.openapi.json y las notas de verificacion en docs/verification-log.md.