Skip to main content

​
Standard Response Structure

All TamborraData API responses return JSON with consistent structures based on the endpoint.

​
Content Type

All responses use the application/json content type: 
Content-Type: application/json

​
Success Responses

​
Years Endpoint

{
  "years": ["2025", "2024", "2023", "2022", "2020", "2019", "2018", "global"]
}
​
years
string[]
required
Array of available years in descending order, including “global” for all-time statistics.

​
Statistics Endpoint

{
  "isUpdating": false,
  "year": "2024",
  "total_categories": 21,
  "statistics": {
    "topNames": [
      {
        "category": "topNames",
        "public_data": [{"name": "Nora", "count": 98}],
        "summary": "Nora fue el nombre más frecuente..."
      }
    ],
    "totalParticipants": [
      {
        "category": "totalParticipants",
        "public_data": [{"year": 2024, "count": 5039}],
        "summary": "En 2024 la festividad contó con 5.039 niños..."
      }
    ]
  }
}
​
isUpdating
boolean
required
Indicates if the system is currently being updated. When true, limited data may be available.
​
year
string
required
The year for which statistics are returned (e.g., “2024” or “global”).
​
total_categories
number
required
Total number of statistical categories available for the year.
​
statistics
object
required
Object containing statistics grouped by category. Each category contains an array with:
  • category (string): Category identifier
  • public_data (array|number|string): The actual statistical data
  • summary (string): Human-readable summary in Spanish

​
Category Endpoint

{
  "stats": [
    {
      "category": "topNames",
      "public_data": [
        {"name": "Nora", "count": 98},
        {"name": "Ane", "count": 88},
        {"name": "Jon", "count": 85}
      ],
      "summary": "Nora encabeza el ranking de 2025 con 98 participaciones..."
    }
  ]
}
​
stats
array
required
Array of category data objects with:
  • category (string): Category identifier
  • public_data (varies): Category-specific data structure
  • summary (string): Descriptive summary of the data

​
Companies Endpoint

{
  "companies": [
    "Amara Berri",
    "Santo Tomas Lizeoa",
    "Aldapeta María Ikastetxea",
    "Sagrado Corazon Mundaiz"
  ]
}
​
companies
string[]
required
Array of school/company names that have participated in the event.

​
Participants Endpoint

{
  "participants": [
    {
      "name": "Juan Garcia Lopez",
      "school": "Amara Berri",
      "year": 2024
    },
    {
      "name": "Juan Garcia Lopez",
      "school": "Amara Berri",
      "year": 2023
    }
  ]
}
​
participants
array
required
Array of participant records, ordered by year (descending). Each record contains:
  • name (string): Full name of the participant
  • school (string): School/company name
  • year (number): Year of participation

​
Error Responses

Error responses have a simple structure: 
{
  "error": "El parámetro 'year' es obligatorio"
}
​
error
string
required
Human-readable error message describing what went wrong.
Optionally, detailed errors include: 
{
  "error": "Error al obtener el estado del sistema",
  "details": "Additional technical information"
}
​
details
string
Technical details about the error (present in some 500 errors).
See Error Handling for complete error documentation.

​
Data Types

​
Public Data Structures

The public_data field varies by category:

​
Array of Objects (Most Common)

"public_data": [
  {"name": "Nora", "count": 98},
  {"name": "Ane", "count": 88}
]

​
Array of Strings

"public_data": ["Keity", "Aurkene", "Johsuar", "Ulises"]

​
Single Number

"public_data": 1950

​
Complex Nested Objects

"public_data": [
  {
    "total": 1568,
    "school": "Amara Berri",
    "years": [
      {"year": 2018, "count": 214},
      {"year": 2019, "count": 230}
    ]
  }
]

​
TypeScript Types

The API source code includes TypeScript definitions:

​
Years Response

type YearsResponse = {
  years: string[];
};

​
Statistics Response

type StatisticsResponse = {
  isUpdating: boolean;
  year: string;
  total_categories: number;
  statistics: Record<string, CategoryData[]>;
};

type CategoryData = {
  category: string;
  public_data: any; // Varies by category
  summary: string;
};

​
Category Response

type CategoryResponse = {
  stats: CategoryData[];
};

​
Companies Response

type CompaniesResponse = {
  companies: string[];
};

​
Participants Response

type ParticipantsResponse = {
  participants: Participant[];
};

type Participant = {
  name: string;
  school: string;
  year: number;
};

​
Error Response

type ErrorResponse = {
  error: string;
  details?: string;
};

​
Field Descriptions

​
Common Fields

​
Participant Fields

​
Response Examples by Category

​
Top Names

{
  "public_data": [
    {"name": "Nora", "count": 98},
    {"name": "Ane", "count": 88},
    {"name": "Jon", "count": 85}
  ]
}

​
Schools Evolution

{
  "public_data": [
    {
      "total": 1568,
      "school": "Amara Berri",
      "years": [
        {"year": 2018, "count": 214},
        {"year": 2019, "count": 230}
      ]
    }
  ]
}

​
Names Diversity

{
  "public_data": 1950
}

​
New Names by Year

{
  "public_data": ["Keity", "Aurkene", "Johsuar", "Ulises", "Meri"]
}

​
Null Handling

The API may return null for data fields when:
  • No data is available
  • Database query fails
  • System is updating
Always check for null values: 
const data = await response.json();
if (data.statistics === null) {
  console.log('No statistics available');
}

​
Pagination

The API currently does not support pagination. All results are returned in a single response.
  • /api/years: Returns all available years
  • /api/companies: Returns all companies
  • /api/statistics: Returns all categories for a year
  • /api/participants: Returns all matching participants

​
Caching Headers

The API does not currently set explicit caching headers. Implement client-side caching for optimal performance: 
const CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours

function getCachedData(key) {
  const cached = localStorage.getItem(key);
  if (cached) {
    const {data, timestamp} = JSON.parse(cached);
    if (Date.now() - timestamp < CACHE_DURATION) {
      return data;
    }
  }
  return null;
}

​
Data Encoding

All text data is UTF-8 encoded and may include:
  • Spanish characters (á, é, í, ó, ú, ñ)
  • Basque characters (special letters and diacritics)
  • International names (various Unicode characters)
Ensure your client handles UTF-8 properly: 
const response = await fetch(url, {
  headers: {
    'Accept': 'application/json',
    'Accept-Charset': 'utf-8'
  }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us