{"openapi":"3.1.0","info":{"title":"DondeGo Public API","version":"0.1.0","summary":"Verified public DondeGo API discovery specification.","description":"Minimal OpenAPI v0.1 for verified public DondeGo endpoints. This spec is based on Phase 2A public API verification and intentionally excludes unverified date filters, root-index families, backend/private surfaces, runnable examples, MCP, OAuth/OIDC metadata, and WebMCP. Any public integration that displays DondeGo event descriptions or substantial event data must include a visible direct link to the canonical DondeGo.es event page using EventDetail.site_url.","contact":{"name":"DondeGo","email":"bcn@dondego.es"}},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://dondego.es/public-api/v1.4","description":"Verified public API base URL from Phase 2A."}],"tags":[{"name":"Locations","description":"Supported public DondeGo locations."},{"name":"Events","description":"Public event list and detail endpoints. Rendered event displays must fetch detail and link EventDetail.site_url."},{"name":"Places","description":"Public place list and detail endpoints."},{"name":"News","description":"Public news list and detail endpoints."},{"name":"EventsOfTheDay","description":"Daily wrapper rows that reference event IDs."},{"name":"Search","description":"Experimental mixed-result discovery endpoint with loose result schema."}],"paths":{"/locations/":{"get":{"tags":["Locations"],"operationId":"listLocations","summary":"List supported locations","description":"Returns supported DondeGo city slugs and names. Phase 2A observed barcelona and madrid. No coordinates or timezone fields were observed.","parameters":[],"responses":{"200":{"description":"Supported locations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}}}}}}},"/events/":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List event summaries","description":"Returns compact event rows with id, title, and slug. Event list rows did not expose site_url or location in Phase 2A; clients that render event descriptions or substantial event data must fetch event detail and use EventDetail.site_url for visible source attribution.","parameters":[{"$ref":"#/components/parameters/LocationParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}}}}},"/events/{id}/":{"get":{"tags":["Events"],"operationId":"getEvent","summary":"Get event detail","description":"Returns event detail. EventDetail.site_url is the verified DondeGo.es event page source-link field for sampled event details. Public displays of DondeGo event descriptions or substantial event data must include a visible direct link to this event page.","parameters":[{"$ref":"#/components/parameters/EventIdParam"},{"$ref":"#/components/parameters/EventExpandParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/places/":{"get":{"tags":["Places"],"operationId":"listPlaces","summary":"List place summaries","description":"Returns paginated public place rows. Phase 2A verified location and page parameters for places.","parameters":[{"$ref":"#/components/parameters/LocationParam"},{"$ref":"#/components/parameters/PageParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceListResponse"}}}}}}},"/places/{id}/":{"get":{"tags":["Places"],"operationId":"getPlace","summary":"Get place detail","description":"Returns public place detail fields, including DondeGo place site_url where present. foreign_url, when present, must not be confused with event attribution requirements.","parameters":[{"$ref":"#/components/parameters/PlaceIdParam"},{"$ref":"#/components/parameters/ImagesCategoriesExpandParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/news/":{"get":{"tags":["News"],"operationId":"listNews","summary":"List news summaries","description":"Returns paginated public news rows. Phase 2A verified location and page parameters for news.","parameters":[{"$ref":"#/components/parameters/LocationParam"},{"$ref":"#/components/parameters/PageParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsListResponse"}}}}}}},"/news/{id}/":{"get":{"tags":["News"],"operationId":"getNews","summary":"Get news detail","description":"Returns public news detail fields, including DondeGo news site_url where present. Avoid copying long article text into examples.","parameters":[{"$ref":"#/components/parameters/NewsIdParam"},{"$ref":"#/components/parameters/ImagesCategoriesExpandParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/events-of-the-day/":{"get":{"tags":["EventsOfTheDay"],"operationId":"listEventsOfTheDay","summary":"List daily event picks","description":"Returns wrapper rows, not full event objects. Sampled object.id values mapped to GET /events/{id}/. Clients should fetch event detail and use EventDetail.site_url before rendering substantial event data.","parameters":[{"$ref":"#/components/parameters/LocationParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsOfTheDayResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/search/":{"get":{"tags":["Search"],"operationId":"search","summary":"Search public DondeGo content","description":"Experimental mixed-result discovery endpoint. Requires q and returns results with ctype and item_url, but fields vary by result type and URL path. Do not treat search item_url as equivalent to verified event detail site_url for rendered event attribution without resolving event detail.","parameters":[{"$ref":"#/components/parameters/SearchQueryParam"},{"$ref":"#/components/parameters/LocationParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","description":"Observed error responses used a top-level detail key. The exact message text is not part of the public contract.","properties":{"detail":{"description":"Human-readable error detail.","type":["string","object","array","null"]}},"required":["detail"],"additionalProperties":true},"Location":{"type":"object","description":"Supported DondeGo location returned by /locations/. Phase 2A observed barcelona and madrid.","properties":{"slug":{"type":"string","enum":["barcelona","madrid"],"description":"Location slug observed in Phase 2A. Clients should still read /locations/ for future supported cities."},"name":{"type":"string","description":"Human-readable location name."}},"required":["slug","name"],"additionalProperties":true},"PaginatedResponseBase":{"type":"object","description":"Shared observed pagination envelope. Most content lists returned count, next, previous, and results.","properties":{"count":{"type":"integer","minimum":0},"next":{"type":["string","null"],"format":"uri"},"previous":{"type":["string","null"],"format":"uri"}},"required":["count","next","previous"],"additionalProperties":true},"LocationRef":{"type":"object","description":"Minimal location reference observed on event detail responses.","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":true},"Coords":{"type":"object","description":"Coordinate object. Exact numeric/string typing should be treated permissively until broader verification.","properties":{"lat":{"type":["number","string","null"]},"lon":{"type":["number","string","null"]}},"additionalProperties":true},"ImageSource":{"type":"object","description":"Image source metadata observed as name/link keys.","properties":{"name":{"type":["string","null"]},"link":{"type":["string","null"],"format":"uri"}},"additionalProperties":true},"Image":{"type":"object","description":"Image object observed on event, place, and news detail responses.","properties":{"image":{"type":["string","null"],"format":"uri"},"thumbnails":{"type":["object","null"],"additionalProperties":true},"source":{"$ref":"#/components/schemas/ImageSource"}},"additionalProperties":true},"Category":{"type":"string","description":"Category slug observed as a string."},"Tag":{"type":"string","description":"Tag slug observed as a string."},"Participant":{"type":"object","description":"Participant objects were not populated in sampled responses; keep permissive until verified.","additionalProperties":true},"EventDate":{"type":"object","description":"Event date object. Compact detail responses may include start/end epoch fields; expanded responses included separate date/time and scheduling flags.","properties":{"start":{"type":["integer","null"]},"end":{"type":["integer","null"]},"start_date":{"type":["string","null"]},"start_time":{"type":["string","null"]},"end_date":{"type":["string","null"]},"end_time":{"type":["string","null"]},"is_continuous":{"type":["boolean","null"]},"is_endless":{"type":["boolean","null"]},"is_startless":{"type":["boolean","null"]},"schedules":{"type":["array","null"],"items":{"type":"object","additionalProperties":true}},"use_place_schedule":{"type":["boolean","null"]}},"additionalProperties":true},"PlaceRef":{"type":"object","description":"Place reference. Without expand this may contain only id; expanded event detail may include venue fields.","properties":{"id":{"type":"integer"},"title":{"type":["string","null"]},"slug":{"type":["string","null"]},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"subway":{"type":["string","null"]},"location":{"type":["string","null"]},"site_url":{"type":["string","null"],"format":"uri"},"is_closed":{"type":["boolean","null"]},"coords":{"$ref":"#/components/schemas/Coords"},"is_stub":{"type":["boolean","null"]}},"required":["id"],"additionalProperties":true},"EventSummary":{"type":"object","description":"Compact event list row. Phase 2A did not observe site_url or location on event list rows.","properties":{"id":{"type":"integer"},"title":{"type":"string"},"slug":{"type":"string"}},"required":["id","title","slug"],"additionalProperties":true},"EventListResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponseBase"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/EventSummary"}}},"required":["results"]}]},"EventDetail":{"type":"object","description":"Event detail. The site_url field is the verified DondeGo.es event page source link for sampled event details. Public displays of event descriptions or substantial event data must include a visible direct link to this event page.","properties":{"id":{"type":"integer"},"publication_date":{"type":["integer","null"]},"dates":{"type":"array","items":{"$ref":"#/components/schemas/EventDate"}},"title":{"type":"string"},"slug":{"type":"string"},"place":{"$ref":"#/components/schemas/PlaceRef"},"description":{"type":["string","null"]},"body_text":{"type":["string","null"]},"location":{"$ref":"#/components/schemas/LocationRef"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"tagline":{"type":["string","null"]},"age_restriction":{"type":["string","null"]},"price":{"type":["string","null"]},"is_free":{"type":["boolean","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"favorites_count":{"type":["integer","null"]},"comments_count":{"type":["integer","null"]},"site_url":{"type":"string","format":"uri","description":"Verified source-link field for sampled event details. Use this for visible event-level DondeGo attribution."},"short_title":{"type":["string","null"]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"disable_comments":{"type":["boolean","null"]},"participants":{"type":"array","items":{"$ref":"#/components/schemas/Participant"}}},"required":["id","title","slug","site_url"],"additionalProperties":true},"PlaceSummary":{"type":"object","description":"Place list row observed in Phase 2A.","properties":{"id":{"type":"integer"},"title":{"type":"string"},"slug":{"type":"string"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"site_url":{"type":["string","null"],"format":"uri"},"subway":{"type":["string","null"]},"is_closed":{"type":["boolean","null"]},"location":{"type":["string","null"]},"has_parking_lot":{"type":["boolean","null"]}},"required":["id","title","slug"],"additionalProperties":true},"PlaceListResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponseBase"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/PlaceSummary"}}},"required":["results"]}]},"PlaceDetail":{"type":"object","description":"Place detail observed in Phase 2A.","properties":{"id":{"type":"integer"},"title":{"type":"string"},"slug":{"type":"string"},"address":{"type":["string","null"]},"timetable":{"type":["string","null"]},"phone":{"type":["string","null"]},"is_stub":{"type":["boolean","null"]},"body_text":{"type":["string","null"]},"description":{"type":["string","null"]},"site_url":{"type":["string","null"],"format":"uri"},"foreign_url":{"type":["string","null"],"format":"uri"},"coords":{"$ref":"#/components/schemas/Coords"},"subway":{"type":["string","null"]},"favorites_count":{"type":["integer","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"comments_count":{"type":["integer","null"]},"is_closed":{"type":["boolean","null"]},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"short_title":{"type":["string","null"]},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"location":{"type":["string","null"]},"age_restriction":{"type":["string","null"]},"disable_comments":{"type":["boolean","null"]},"has_parking_lot":{"type":["boolean","null"]}},"required":["id","title","slug"],"additionalProperties":true},"NewsSummary":{"type":"object","properties":{"id":{"type":"integer"},"publication_date":{"type":["integer","null"]},"title":{"type":"string"},"slug":{"type":"string"}},"required":["id","title","slug"],"additionalProperties":true},"NewsListResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponseBase"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/NewsSummary"}}},"required":["results"]}]},"NewsDetail":{"type":"object","description":"News detail observed in Phase 2A. Avoid copying long article text into examples.","properties":{"id":{"type":"integer"},"publication_date":{"type":["integer","null"]},"title":{"type":"string"},"slug":{"type":"string"},"place":{"type":["object","null"],"additionalProperties":true},"description":{"type":["string","null"]},"body_text":{"type":["string","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"site_url":{"type":["string","null"],"format":"uri"},"favorites_count":{"type":["integer","null"]},"comments_count":{"type":["integer","null"]},"disable_comments":{"type":["boolean","null"]}},"required":["id","title","slug"],"additionalProperties":true},"ContentObjectRef":{"type":"object","description":"Nested content object reference from events-of-the-day rows.","properties":{"id":{"type":"integer"},"ctype":{"type":"string"}},"required":["id","ctype"],"additionalProperties":true},"EventsOfTheDayItem":{"type":"object","description":"Daily event wrapper row. This is not a full event; resolve object.id with getEvent before rendering substantial event data.","properties":{"date":{"type":"string","format":"date"},"location":{"type":"string"},"object":{"$ref":"#/components/schemas/ContentObjectRef"},"title":{"type":"string"}},"required":["date","location","object","title"],"additionalProperties":true},"EventsOfTheDayResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponseBase"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/EventsOfTheDayItem"}}},"required":["results"]}]},"SearchResult":{"type":"object","description":"Loose mixed search result. Fields vary by ctype and result URL path. Do not treat item_url as equivalent to EventDetail.site_url for event attribution without resolving event detail.","properties":{"id":{"type":"integer"},"title":{"type":"string"},"favorites_count":{"type":["integer","null"]},"comments_count":{"type":["integer","null"]},"description":{"type":["string","null"]},"item_url":{"type":["string","null"],"format":"uri"},"disable_comments":{"type":["boolean","null"]},"ctype":{"type":"string"}},"required":["id","title","item_url","ctype"],"additionalProperties":true},"SearchResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponseBase"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"required":["results"]}]}},"parameters":{"LocationParam":{"name":"location","in":"query","required":false,"description":"Verified city filter. Values observed from /locations/ were barcelona and madrid.","schema":{"type":"string","enum":["barcelona","madrid"]}},"PageParam":{"name":"page","in":"query","required":false,"description":"Verified pagination page parameter for events, places, and news.","schema":{"type":"integer","minimum":1}},"PageSizeParam":{"name":"page_size","in":"query","required":false,"description":"Verified page-size parameter for events and search. Do not use limit; it did not reduce page size in Phase 2A tests.","schema":{"type":"integer","minimum":1}},"EventIdParam":{"name":"id","in":"path","required":true,"description":"Integer event ID.","schema":{"type":"integer"}},"PlaceIdParam":{"name":"id","in":"path","required":true,"description":"Integer place ID.","schema":{"type":"integer"}},"NewsIdParam":{"name":"id","in":"path","required":true,"description":"Integer news ID.","schema":{"type":"integer"}},"EventExpandParam":{"name":"expand","in":"query","required":false,"description":"Optional free-form expand string. Phase 2A verified the combined value place,images,dates,categories,tags,participants on event detail; individual tokens were not exhaustively verified.","schema":{"type":"string"},"example":"place,images,dates,categories,tags,participants"},"ImagesCategoriesExpandParam":{"name":"expand","in":"query","required":false,"description":"Optional free-form expand string. Phase 2A verified the combined value images,categories on place and news detail.","schema":{"type":"string"},"example":"images,categories"},"SearchQueryParam":{"name":"q","in":"query","required":true,"description":"Required search query. Missing q returned 400 JSON with detail.","schema":{"type":"string","minLength":1}}},"responses":{"BadRequest":{"description":"Bad request. Missing search q and some invalid requests returned JSON with detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not found. Invalid detail IDs returned JSON with detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}