Skip to main content

​
Introduction

The TamborraData API provides programmatic access to historical data about the San Sebastián Children’s Tamborrada (Tamborrada Infantil). The API follows REST principles and returns JSON responses.

​
Base URL

https://tamborradata.com/api
For local development: 
http://localhost:3000/api

​
Authentication

The TamborraData API is publicly accessible and does not require authentication. All endpoints are available for read-only access without API keys.
The API is read-only. No authentication is required, but write operations are not permitted.

​
API Architecture

The API is built using Next.js 16 App Router with the following architecture:
  • Route Layer: Next.js API Routes handle HTTP requests
  • Service Layer: Business logic and data processing
  • Repository Layer: Database queries using Supabase PostgreSQL
  • Database: PostgreSQL with Row Level Security (RLS)

​
Rate Limits

Currently, there are no enforced rate limits on the API. However, please use the API responsibly:
  • Cache responses when possible
  • Avoid excessive polling
  • Use appropriate intervals for data updates
Rate limits may be introduced in the future to ensure fair usage.

​
Data Freshness

The TamborraData database is updated annually in January with new data from the previous year’s event. During update periods:
  • The system may return isUpdating: true
  • Some endpoints may return limited data
  • Check the /api/statistics endpoint for system status

​
Response Format

All API responses follow a consistent JSON format. See the Response Format documentation for details.

​
Error Handling

The API uses standard HTTP status codes and returns error messages in JSON format. See the Errors documentation for details.

​
Available Endpoints

The TamborraData API exposes 6 main endpoints:

Health Check

Verify API operational status

Years

Get list of available years with data

Statistics

Retrieve complete statistics for a specific year

Category

Get detailed data for a specific category and year

Companies

List all participating schools/companies

Participants

Search for individual participants by name and school

​
Quick Start

Here’s a simple example to get started: 
# Get available years
curl https://tamborradata.com/api/years

# Get statistics for 2024
curl https://tamborradata.com/api/statistics?year=2024

# Search for participants
curl "https://tamborradata.com/api/participants?name=Juan%20Garcia%20Lopez&company=Amara%20Berri"

​
TypeScript Support

The API is built with TypeScript. Type definitions are available in the source code:
  • app/(backend)/api/*/types/index.ts - Response and request types
  • Full type safety for integration with TypeScript projects

​
Data License

This project is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). When using the API data:

​
Support

For questions or issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us