API Documentation

Welcome to the official Feriados API documentation. Our REST API provides accurate data on national, state, and municipal holidays in Brazil. All endpoints return responses in JSON format and use standard HTTP status codes.

Interactive API Reference

Explore our endpoints in real-time with our interactive documentation. Test requests directly from your browser and validate your integration instantly.

Open API Reference

Base URL:

https://feriadosapi.com

OpenAPI Spec (YAML)

Choose example code language

Usage Limits & Plans

Feriados API offers different levels of service depending on your plan. Understanding the limits is fundamental to ensuring your integration stability.

Free Plan

Access to National and State holidays
Access to all 27 state capital cities
Rate Limit: 60 requests per minute

Paid Plans

Access to all 5,570 municipalities
Date verification & advanced endpoints
Developer: Rate Limit of 60 req/min
Starter & Professional: Unlimited (No Rate Limit)

About the 60 RPM Rate Limit: The 60 requests per minute limit applies globally per token on Free and Developer plans. If you require higher volume or throughput without rate limiting, consider the Starter or Professional plans.

Authentication

All requests must include your API key in the Authorization header. You can obtain your key in the Dashboard.

Don't have an API key yet?

Create your free account right now and start integrating.

Create Free Account

Header example

bash

Authorization: Bearer your_token_here

Pagination & Filters

The API supports pagination via query parameters on listing endpoints. Additionally, all endpoints return useful response metadata inside the meta object.

Query Parameters

Parameter	Description	Default
page	Current page number	1
limit	Items per page (max 100)	50
ano	Filters holidays by year (e.g. 2026)	All
facultativos	If true, includes optional holidays	false

National Holidays

GETFree

Returns all national holidays for a given year.

Endpoint

/api/v1/feriados/nacionais?ano=2026

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/nacionais?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example

json

{
  "tipo": "NACIONAL",
  "ano": "2026",
  "feriados": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "data": "01/01/2026",
      "nome": "Confraternização Universal",
      "tipo": "NACIONAL"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "data": "25/12/2026",
      "nome": "Natal",
      "tipo": "NACIONAL"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

State Holidays

GETFree

Returns state holidays (including national ones) for a specific state (UF — Unidade da Federação, the 2-letter Brazilian state code like SP or RJ).

Endpoint

/api/v1/feriados/estado/{uf}?ano=2026

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/estado/SP?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example (SP)

json

{
  "uf": "SP",
  "ano": "2026",
  "feriados": [
    {
      "id": "...",
      "data": "09/07/2026",
      "nome": "Revolução Constitucionalista",
      "tipo": "ESTADUAL"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Municipal Holidays

GETCapitals FreeOthers Consume Quota

Returns all holidays (municipal, state, and national) for a specific city by its 7-digit IBGE code (Brazil's standardized municipal census code, equivalent to US FIPS or French INSEE codes).

Free for the 27 state capitals. Other municipalities consume 1 unit of monthly quota.

Endpoint

/api/v1/feriados/cidade/{ibge}?ano=2026

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/cidade/3550308?ano=2026" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example (São Paulo - 3550308)

json

{
  "cidade": {
    "ibge": 3550308,
    "nome": "São Paulo",
    "uf": "SP"
  },
  "ano": "2026",
  "feriados": [
    {
      "id": "...",
      "data": "25/01/2026",
      "nome": "Aniversário de São Paulo",
      "tipo": "MUNICIPAL"
    }
  ],
  "meta": {
    "total": 18,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Check Date

GETConsumes Quota

Checks whether a specific date is a holiday. Returns 404 if not.

Attention: This endpoint is available exclusively on paid plans and consumes 1 unit of your monthly quota per query.

Endpoint

/api/v1/feriados/data/{ano-mes-dia}

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/feriados/data/2026-12-25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Banking Holidays

The API includes the official banking calendar based on CMN Resolution 4,880/2020 and the FEBRABAN calendar. All endpoints return the bancario (boolean) field indicating whether it is a banking holiday. Includes all national holidays plus optional dates when banks are closed: Carnival (Mon/Tue), Ash Wednesday (open after noon), Corpus Christi, and New Year's Eve (Dec 31).

Filter banking holidays only

Add ?bancarios=true to any existing endpoint to return only banking holidays.

bash

GET /api/v1/feriados/nacionais?ano=2026&bancarios=true

Dedicated Endpoint: List banking holidays

Free

json

GET /api/v1/feriados/bancarios?ano=2026

Optional parameters: uf (2-letter state code), ibge (7-digit municipal code), facultativos.

Check banking business day

Free

json

GET /api/v1/feriados/dia-util-bancario/2026-02-16

Returns whether a date is a banking business day. If not, provides the reason and next business day. Date format: YYYY-MM-DD.

List States

GETFree

Returns the list of all 27 Brazilian states and federal districts (UFs) with their abbreviations and names.

Endpoint

/api/v1/estados

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/estados" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

List Municipalities

GETFree

Returns the complete list of all 5,570 Brazilian municipalities and their official IBGE geographic codes.

Endpoint

/api/v1/municipios

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/municipios" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Search Municipality

GETFree

Returns data for a specific municipality by its 7-digit IBGE geographic census code.

Endpoint

/api/v1/municipio/{ibge}

Example (curl)

bash

curl -X GET "https://feriadosapi.com/api/v1/municipio/3550308" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Glossary & Models

Holiday Types

NACIONALHoliday valid throughout all of Brazil.
ESTADUALHoliday valid only in a specific state (UF — 2-letter state abbreviation like SP, RJ, MG).
MUNICIPALHoliday valid only in a specific city (e.g. City Anniversary, local religious observances).
FACULTATIVOOptional holiday (e.g. Carnival, Corpus Christi in some locations).

Holiday Object

json

{
  "id": "UUID",          // Unique identifier
  "data": "DD/MM/YYYY",  // Official date
  "nome": "String",      // Holiday name
  "tipo": "Enum",        // NACIONAL | ESTADUAL | MUNICIPAL | FACULTATIVO
  "descricao": "String", // Historical context
  "uf": "SP",            // (Optional) State UF
  "codigo_ibge": 12345,  // (Optional) City IBGE
  "bancario": true       // Banking holiday (FEBRABAN)
}

AI Agents via MCP

Exclusive MCP Server Portal

To see advanced setup options for VS Code, Copilot, Cursor, and full framework integration guides, visit our dedicated Model Context Protocol portal.

Access mcp.feriadosapi.com

In addition to our classic REST API, Feriados API is Brazil's First Model Context Protocol (MCP) Server for Holidays. Provide precise local date context to AI Agents built on OpenAI, Gemini, Claude, Manus, and more.

1. Remote Connection (Recommended)

Configure via URL by connecting the API in your client.

https://mcp.feriadosapi.com/api/mcp?apiKey=YOUR_KEY

2. Local Connection (npx)

Run directly via CLI (Node.js/npm).

npx -y @feriados-api/mcp-server

Connect Your Application

Example: Configuration File (MCP Clients & Frameworks)

json

{
  "mcpServers": {
    "feriadosapi": {
      "url": "https://mcp.feriadosapi.com/api/mcp?apiKey=YOUR_API_KEY"
    }
  }
}

Real-World AI Use Cases:

Logistics Agent: "Calculate the final delivery date for Salvador, ignoring weekends, national holidays, and Bahia state holidays."
Travel Agent: "Create an itinerary in Ouro Preto for next week. Avoid scheduling attractions on Tuesday if it is a municipal holiday."
HR/Payroll Agent: "Generate this month's timecard summary, identifying all overtime worked during bridges and optional holidays for the São Paulo branch."
Financial Assistant: "Check this invoice batch and advance bank payment for those whose due dates fall on holidays."

Tools Injected into Agent

buscar_feriadosFull search with flexible filters (date, type, UF, IBGE, year, banking).

feriados_nacionaisList of all national holidays.

feriados_por_estadoSearch state holidays using state UF code.

feriados_por_cidadeSearch municipal holidays using IBGE code.

feriados_bancariosList FEBRABAN banking holidays. Filters: year, UF, IBGE.

verificar_dia_util_bancarioCheck if a date is a banking business day (reason + next business day).

verificar_dataCheck if a date (YYYY-MM-DD) is a holiday.

listar_estadosList states and UFs for context.

buscar_municipiosSearch IBGE code for cities.