Forem: Alexander Prokofiev

Making a Local Events API Discoverable to Developers and AI Assistants

Alexander Prokofiev — Thu, 21 May 2026 23:14:32 +0000

Local cultural data should not only live as web pages.
That is the idea behind the public discovery layer we just shipped for the DondeGo API.
DondeGo is a local discovery platform for Barcelona and Madrid, focused on events, places, cultural life, and local news. We are building it as a media and discovery product, but we also want the data surface to be understandable by developers, API clients, documentation tools, and AI assistants.
So instead of only publishing a human-readable API page, we built a small discovery package around the API.
It includes OpenAPI, llms.txt, an API Catalog linkset, Postman documentation, examples, and a documentation-only Agent Skills index.
The goal is simple:
make the API easier to discover, understand, cite, and use without pretending to support capabilities that do not exist yet.

What is live

Here are the main public entry points.
OpenAPI 3.1:
https://dondego.es/openapi.json
llms.txt:
https://dondego.es/llms.txt
API Catalog linkset:
https://dondego.es/.well-known/api-catalog
Rich DondeGo discovery JSON:
https://dondego.es/api-catalog.json
Documentation-only Agent Skills index:
https://dondego.es/.well-known/agent-skills/index.json
Postman documentation:
https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ
GitHub repository:
https://github.com/revanbcn/DondeGo-API
The repository also includes server-side examples for curl, Python, and Node:
https://github.com/revanbcn/DondeGo-API/tree/main/examples
And a ready-to-import Postman Collection:
https://github.com/revanbcn/DondeGo-API/tree/main/postman

Why not just publish OpenAPI?

OpenAPI is the most important artifact, but it is not the whole discovery story.
Different tools look for different signals:

developers want examples and a clear README
API clients want OpenAPI
Postman users want a collection
LLM-oriented tools can benefit from llms.txt
API discovery systems can use a linkset
agents need short, explicit usage guidance
partners need attribution and usage rules So the discovery layer is intentionally made of several small, stable surfaces instead of one giant documentation page. ## Verified endpoint families The current OpenAPI v0.1 spec is intentionally conservative. It documents only endpoint families we have verified and are ready to describe clearly: 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=...

We did not add endpoints just because they might exist somewhere.

We did not document parameters that still need verification.

We did not generate a huge speculative spec.

The goal of v0.1 is to describe what can be described accurately.

Quick example

The public API base is:

https://dondego.es/public-api/v1.4

List supported locations:

curl -s https://dondego.es/public-api/v1.4/locations/ | jq

List a few Barcelona event summaries:

curl -s "https://dondego.es/public-api/v1.4/events/?location=barcelona&page_size=3" | jq

Fetch event details:

curl -s "https://dondego.es/public-api/v1.4/events/{id}/?expand=place,images,dates,categories,tags,participants" | jq

More complete examples are available here:

https://github.com/revanbcn/DondeGo-API/tree/main/examples

The detail-first attribution rule

One important rule in the current API is event attribution.

Event list rows are useful for discovery, but they do not expose everything needed for safe public rendering. In particular, list rows do not expose the canonical DondeGo event page URL.

For public event rendering, the rule is:

event list -> fetch event detail -> use EventDetail.site_url as the visible DondeGo source link

This matters because 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.

That rule is repeated across the docs, examples, Postman collection, llms.txt, and API catalog.

It is not just a legal or SEO detail. It is part of making local data trustworthy.

If a user sees an event recommendation in an app or assistant, they should be able to click through to the original canonical page.

llms.txt

We publish:

https://dondego.es/llms.txt

This file is a short LLM-oriented index.

It points to the most important resources:

what DondeGo is
what the public API covers
where the OpenAPI spec lives
where the API Catalog lives
where examples live
what attribution rule must be followed
what is not supported yet

It does not magically make every model use the API.

But it gives AI systems and developer tools a clear, stable, crawlable reference.

API Catalog linkset

We also publish:

https://dondego.es/.well-known/api-catalog

This is served as:

application/linkset+json

It links to the core discovery resources:

OpenAPI
documentation
llms.txt
attribution policy
examples
version history
richer DondeGo discovery JSON

The richer DondeGo-specific JSON is available separately:

https://dondego.es/api-catalog.json

This split is intentional.

The .well-known/api-catalog route is a compact machine-readable linkset. The /api-catalog.json route carries richer DondeGo-specific context.

Documentation-only Agent Skills

We also publish a documentation-only Agent Skills index:

https://dondego.es/.well-known/agent-skills/index.json

The important part is “documentation-only”.

There are no scripts. No executable code. No hidden tool access. No permission escalation. No OAuth. No MCP transport.

The skill exists to teach an AI agent how to discover and correctly use the DondeGo public API documentation.

It explains the stable discovery URLs, verified endpoint families, attribution requirement, and detail-first event rendering rule.

What we intentionally do not advertise

This is probably the most important architectural decision in the whole package.

We do not advertise OAuth or OIDC support, because DondeGo does not currently run an OAuth issuer.

We do not publish OAuth Protected Resource Metadata, because the current public discovery package does not expose OAuth-protected scopes.

We do not claim to have an MCP server.

We do not claim to have WebMCP tools.

We do not document date filters or the limit parameter in OpenAPI v0.1, because those still need separate verification.

We do not publish browser-only examples yet, because CORS behavior should be handled deliberately, not assumed.

Accurate discovery metadata is more useful than fake “agent-ready” metadata.

If a site publishes machine-readable discovery files, those files should describe real capabilities.

Postman documentation

For developers who prefer Postman, we published public documentation:

https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ

The repository also includes a ready-to-import Postman Collection v2.1:

https://github.com/revanbcn/DondeGo-API/tree/main/postman

The collection uses only public GET requests. It does not include environments, secrets, API keys, cookies, bearer tokens, or OAuth settings.

What this enables

This discovery layer is useful for several types of builders:

local newsletters that want to enrich issues with cultural events
city guides that need venues and event details
travel or lifestyle apps building a Barcelona or Madrid experience layer
AI assistants that need structured local data instead of guessing
developers who want to explore the API through OpenAPI or Postman
partners who need clear attribution rules before building on the data

The package is not a huge platform launch.

It is a foundation.

But I think this foundation matters.

Local media and cultural platforms should be easier to integrate with. They should publish machine-readable contracts. They should be understandable by AI-assisted tools. And they should be clear about attribution.

That is the direction we are taking with DondeGo.

Start here

GitHub repository:
https://github.com/revanbcn/DondeGo-API

Live OpenAPI:
https://dondego.es/openapi.json

Postman documentation:
https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ

llms.txt:
https://dondego.es/llms.txt

API Catalog:
https://dondego.es/.well-known/api-catalog

If you are building a local guide, AI assistant, cultural newsletter, events app, map product, or city discovery experience for Barcelona or Madrid, I would be happy to talk.

Partner access and integration discussions:
bcn@dondego.es

First real use case of the DondeGo API: daily event picks for Barcelona and Madrid

Alexander Prokofiev — Mon, 04 May 2026 11:24:36 +0000

We have reached a small but important milestone for DondeGo API.

The first working use case is already live: we are using our API to power daily event selections for two local projects:

The idea is simple: every day, the system uses DondeGo data to select some of the best events happening today in Barcelona and Madrid.

Instead of manually searching across dozens of pages, calendars and sources, we can now use a structured local data layer with events, cities, dates, categories and editorial signals. This makes it much easier to build useful local discovery products.

Why this matters

A local event project usually needs three things:

Fresh event data
A way to filter it by city, date and category
Enough structure to build products on top of it

That is exactly what we are building with DondeGo API.

For our own use case, the API helps us answer questions like:

What is happening in Barcelona today?
What are the most interesting events in Madrid today?
Which events are good enough to recommend?
How can we turn local data into a useful daily feed?

This is still an early version, but it already shows the direction clearly.

DondeGo API is not just a technical experiment. It is becoming a practical content layer for local discovery.

Want to build something with events in Barcelona or Madrid?

If you are building a project about events, culture, local plans, maps, newsletters or city discovery in Barcelona or Madrid, we would be happy to share the data with you for free.

The only thing we ask is simple:
Please link back to DondeGo as the source.

That helps us keep building the project, improve the data and support independent local media.

Possible use cases

You can use DondeGo API to build:

local event newsletters
city guides
interactive maps
Telegram or WhatsApp bots
daily event feeds
cultural recommendation tools
“what to do today” pages
travel and expat guides
niche projects for families, concerts, exhibitions or free events

We are especially interested in small independent projects, local builders and media experiments.

Links

If you want to test the API or build something with local event data for Barcelona or Madrid, feel free to contact us.

We would love to see more projects using structured local data to make city life easier to discover.

We’re opening our events & local news API for Barcelona and Madrid. Free to use for side projects and products – the only requirement is a visible link back to the source.

Alexander Prokofiev — Fri, 27 Mar 2026 22:47:56 +0000

Alexander Prokofiev for API for events in Madrid and Barcelona

Mar 27

We built an API for events, places, and local news in Barcelona and Madrid

#api #barcelona #madrid #opendata

Comments

3 min read

We built an API for events, places, and local news in Barcelona and Madrid

Alexander Prokofiev — Fri, 27 Mar 2026 22:34:02 +0000

Building a local API for events, places, and news in Barcelona and Madrid GitHub

Most city products run into the same problem sooner or later.

You want to answer simple questions like:

What is happening today?
What is near these coordinates?
Which places belong to this category?
Which local news is still actually relevant?

But once you start building, local data is rarely clean enough. Events, places, and news often live in separate systems, use different filters, and do not map well to the way people actually explore a city.

That is one of the reasons we started opening up the data layer behind DondeGo.

DondeGo is a local media and city guide focused on Barcelona and Madrid. The editorial side is built around practical discovery: things to do, places to know, and local news that matters in city life. Recently, we have been turning more of that into an API that can be reused in real products.

What the API is trying to solve

The goal is not to build a huge generic directory.

The goal is to make local urban content easier to work with for developers, editorial teams, maps, newsletters, recommendation tools, and city-focused products.

Right now the API is centered around three main object types:

events
places
news

That makes it possible to support workflows like:

showing events happening today in Madrid
finding places within a radius from a point on the map
filtering objects by tags or categories
returning only current news items
building city guides or local recommendation layers

Recent changes in v0.1.0

We have just published v0.1.0, partly because I wanted the project to have a visible public milestone and partly because the API has become much more usable recently.

A few of the changes included in this version:

daily events now also include films
daily events can now return a title override
event and place categories now expose identifiers
filtering by tag slugs is supported via tags
news now supports an actual_only filter for current items
event date serialization now includes:
- start_date
- start_time
- end_date
- end_time
- is_continuous
- is_endless
- is_startless
- schedules
image serialization now includes authorship
it is now possible to fetch only films with free screenings
it is now possible to fetch only places with free events
is_free is now interpreted more strictly
categories for events and places can now be disabled in collection responses

None of this is especially flashy, but it moves the API closer to being something that is genuinely usable in production.

The kind of queries we care about

The API is most useful when it reflects how people actually navigate a city.

For example, a basic daily query:

GET /api/v1/events/?location=madrid&date=hoy

A proximity-based query:

GET /api/v1/events/?lat=40.4168&lon=-3.7038&radius=3000&date=hoy

And place discovery around a point:

GET /api/v1/places/?lat=41.3874&lon=2.1686&radius=2000

That may sound simple, but in practice this is the layer many local products need most.

Not “all possible city data”, but structured answers to questions like:

what can I do today?
what is nearby?
what is free?
what is still current?
what belongs to this area or category?

Why I find local APIs interesting

There are many great APIs in the world, but local discovery still feels oddly underserved.

A lot of the difficulty is not in storing records. It is in making the data useful in the context of a real city. Dates matter. Geography matters. Editorial freshness matters. Category structure matters. Free vs paid matters. Sometimes a simple “today” filter matters more than a complex taxonomy.

That is why I think local APIs are interesting. They sit somewhere between media, maps, structured data, and product design.

If you are building in this space

We are opening access gradually, but if you are working on a project around Barcelona or Madrid and need local events, places, or news, that is what we are building toward.

The public project is here, a bit more context lives there: DondeGo

I would also be curious how other people here would design this kind of API.

Would you prioritize geospatial search first, editorial freshness first, or category and tag structure first?