Townbase API

The Townbase API is a REST API that gives developers and organisations programmatic access to structured, curated local event and content data. It lets you embed live local event feeds, search, and discovery features into any app, website, or digital service.

The API is designed for two audiences: developers who want to build local discovery features into their products, and organisations such as municipalities, tourism boards, DMOs, and media groups who want to distribute their content beyond their own websites, services and platform.

Contact Townbase to request an API key. Once you have your key, you can start making requests to any public endpoint. You need to sign a contract before getting the key.

Yes — a test API key is available for development and testing purposes. Contact us to request one.

A basic integration — such as embedding an event feed into an existing website — can be up and running in a few hours. A full custom-built discovery experience typically takes a few days to a few weeks depending on scope.

The API itself is developer-facing, but your organisation does not need an in-house developer to benefit from it. Townbase works with a network of integration partners, and many common use cases have ready-made solutions. Partners we work can also suggest great new use cases.

You do. The API exposes only the content that is published and approved on your Townbase deployment. You retain full editorial control at all times.

Changes are reflected in the API in real time. When you publish, edit, or remove content on your Townbase platform, the API feed updates automatically — no manual sync required.

This depends on the licence agreement. Townbase provides the technical infrastructure and commercial use terms for your content, but you decide always what is published.

API access is available as part of select Townbase plans. Contact us to confirm what is included in your current agreement.

API keys are issued per integration, giving you visibility into who is accessing your content feed. Usage reporting is available through your Townbase dashboard.

Yes. The API allows developers to embed your content into apps, platforms, and services that already have established audiences — hotel concierge apps, news sites, regional tourism portals, digital signage, and more — without any additional work on your part.

Townbase powers city guide, local guide, event and activity guide platforms for municipalities, media and other organisations like universities across Finland, Sweden and the UK. Currently more than 50 000 organisations have signed up to create content. The City of Tampere (tapahtumat.tampere.fi) is one publicly available example of a Townbase-powered deployment.

All API responses are in JSON format.

Authentication is handled via an API key. Include your key in the request header or as a query parameter as specified in the API documentation.

Yes, rate limits apply to prevent abuse and ensure reliability for all users. Details are provided with your API licensing terms and are always negotiable. If your use case requires higher limits, contact us to discuss options.

Yes, content is updated in real time. As soon as a publisher updates an event on the platform, the change is immediately reflected in the API response.

A typical item includes title, description, dates and times, location (long/lat), address, categories, tags, target audiences, images, organiser information, and language variants where available.

The /api/public/search endpoint supports date range filtering, allowing you to query only future events. Refer to the API documentation for the full list of supported parameters.

Yes. The search endpoint supports combining filters such as category, area, tag, target audience, and date range in a single request.

The site/* endpoints — covering areas, categories, tags, languages, target audiences, and organiser collections — expose the full taxonomy of a deployment. This allows you to build fully dynamic UIs that require no hardcoded values and adapt automatically as the platform content evolves.

Currently the API is REST-only with no official SDK. It is compatible with any language or framework that can make HTTP requests.

Webhooks are not currently available. For real-time updates, we recommend polling the relevant endpoints at a suitable interval for your use case.

Errors are returned as JSON with an error_type and error_message field, making them straightforward to handle programmatically.

Yes. Breaking changes will always be introduced under a new version, and existing versions are supported with advance notice of deprecation.

Full documentation including endpoint references, parameters, and example responses is available at /api/docs/.

The API exposes events, activities, and local content items — including cultural events, sports, community activities, exhibitions, concerts and more, and places like venues, restaurants, hotels etc — depending on what is published on each deployment.

Yes. The /api/public/site/languages endpoint returns the languages available for a given deployment, and content items include language variants where they have been provided by the publisher. For more advanced use cases Townbase offers dynamic translations.

Yes. The /api/public/site/targets endpoint returns all available audience segments for a deployment, and these can be used as filters in search and content queries.

Yes. The /api/public/site/areas endpoint returns all defined geographic areas (geoJSON polygon boxes) for a deployment, which can be used to filter content by location.

Both past and upcoming content is accessible via the API. Date range parameters in the search endpoint give you full control over the time window you query. Past events API access requires additional parameters to be enabled. To enable past events queries please mention this in your request.

Common integrations include city and municipal apps, tourism and destination portals, hotel concierge and hospitality apps, regional news and media sites with automated event listings, digital signage and public screens, AI assistants and chatbots with local event awareness, and calendar apps enriched with local content like activity and hobby guides and other recreational experiences. If you want people to find what is happening in your city, you can power that view with Townbase instead of writing lots of feeds by hand or trying to integrate many touchpoints into your own set-up. If we are missing an important touch point we are happy to review adding it to our partner list.

Yes. The /api/public/content-by-host endpoint returns a structured list of all published content for a given deployment, making it straightforward to render a live event feed on any website or app.

Yes. The API is designed to support fully custom front-end experiences. All taxonomy data — categories, areas, tags, audiences — is available dynamically via the site/* endpoints, so your UI can reflect the platform's content without any hard coding.

Yes. The structured JSON responses and search capabilities make the Townbase API well suited for powering AI assistants, voice interfaces, and chatbots that need to answer questions about local events and activities. Some clients use it to power voice assistants for accessibility reasons, some want to provide a local guide via agentic interface. Ask for examples.