Brazil Holidays & Business Days (Feriados)

Brazilian national and state holidays for all 27 states (UFs), each with the law that creates it and an official source. Built for AI agents and apps that compute deadlines, schedules and business days in Brazil.

Three modes:

1. List holidays by year and state.
2. Check dates: is each date a business day in a given state, and why not?
3. Add N business days to a date (or go back), skipping weekends, national and state holidays.

Runs offline from a versioned legal table: no external API, results in seconds.

What you get

• National fixed holidays (Lei 662/1949 as amended, Lei 6.802/1980, Lei 14.759/2023)
• Movable dates calculated from Easter: Good Friday, Carnival, Ash Wednesday, Corpus Christi, plus state ones such as Our Lady of Penha (ES) and Carnival Tuesday (RJ)
• State holidays of the 27 UFs, including statutory transfers (Acre moves most holidays to Friday; Santa Catarina celebrates on Sunday)
• For each holiday: date, weekday, official date if moved, type (national, state or optional), law, source URL and a verification flag

Optional days (pontos facultativos: Carnival, Ash Wednesday until 2 pm, Corpus Christi) are not holidays by federal law. They are listed with type: "optional" and count as business days unless you turn on optionalAsHolidays.

Input

Field	Mode	Description
mode	all	list (default), check or addBusinessDays.
year, yearTo	list	Year or range, 2024 to 2100. Empty = current year.
states	list	UFs to add, e.g. ["SP", "RJ"], or ["ALL"]. Empty = national only.
includeOptional	list	List optional days too (default true).
state	check, add	UF whose state holidays apply, e.g. "SP". Empty = national only.
dates	check	Dates in YYYY-MM-DD. Empty = today in Brasília.
startDate, businessDays	add	Count N business days from the start date (start not counted). Negative goes back; 0 returns the date itself or the next business day.
optionalAsHolidays	check, add	Treat optional days as non-business days.

Output examples

List ({"year": 2026, "states": ["SP"]}):

{
  "date": "2026-07-09",
  "weekday": "Thursday",
  "name": "Revolução Constitucionalista de 1932",
  "nameEn": "Constitutionalist Revolution Day",
  "type": "state",
  "state": "SP",
  "officialDate": "2026-07-09",
  "moved": false,
  "law": "Lei estadual nº 9.497/1997",
  "source": "https://www.al.sp.gov.br/documentacao/estudos-e-manuais/feriado-9-julho/",
  "verification": "official"
}

Check ({"mode": "check", "state": "SP", "dates": ["2026-07-09"]}):

{ "date": "2026-07-09", "weekday": "Thursday", "state": "SP", "isBusinessDay": false, "isWeekend": false, "reason": "Holiday: Revolução Constitucionalista de 1932", "holidays": [{ "name": "Revolução Constitucionalista de 1932", "type": "state", "state": "SP", "law": "Lei estadual nº 9.497/1997", "source": "..." }] }

Add business days ({"mode": "addBusinessDays", "state": "SP", "startDate": "2026-12-23", "businessDays": 5}):

{ "startDate": "2026-12-23", "businessDays": 5, "state": "SP", "resultDate": "2026-12-31", "resultWeekday": "Thursday", "calendarDays": 8, "holidaysSkipped": [{ "date": "2026-12-25", "name": "Natal" }] }

How much does it cost?

Pay per event: one result per row returned (one holiday, one checked date or one calculation).

$0.001 per result (result event, pay per event). Charged once per row returned: a holiday, a checked date or a business-day calculation.

You get	Free tier	Bronze tier (10% off)	Gold tier (30% off)
100 results	$0.10	$0.09	$0.07
1,000 results	$1.00	$0.90	$0.70
10,000 results	$10.00	$9.00	$7.00

Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. No subscription to this Actor and no charge for platform usage: you pay only for results. The Apify Free plan includes $5 of monthly credit, enough for about 5,000 results at the list price. You can cap the cost of any run with Maximum cost per run; the Actor stops when it is reached.

Legal basis and limits

• The legal table is in data/feriados.json, versioned with the code. Each row cites the law and the official page used to confirm it (court, prosecutor, legislature or government calendars). Rows marked verification: "secondary" were only confirmed by press or unofficial copies.
• Years 2024 to 2100, using the laws in force in 2026. A future law changing a holiday needs a table update.
• One-off transfers by decree (a governor moving a holiday in a given year) are not modeled; statutory transfer rules are.
• Some state holidays are legally disputed (federal Lei 9.093/1995 allows states only one "data magna"); the notes field flags known disputes.
• Municipal holidays are not included yet (city anniversaries, patron saints, Corpus Christi where it is a city holiday). They are planned for a later version.

This Actor does one thing: Brazilian holidays and business days. Other Brazilian public data (companies, procurement) is available from the same publisher.

More questions

Is November 20 (Black Consciousness Day) a national holiday?

Yes, since 2024, by Lei 14.759/2023. The Actor lists it as a national holiday from 2024 on, with the law and the official source.

Are Carnival and Corpus Christi holidays?

Not by federal law: they are pontos facultativos (optional days), listed with type: "optional". In check and add modes they count as business days unless you turn on Treat optional days as non-business days (optionalAsHolidays), which is how many companies and banks work. Where a state law makes Carnival Tuesday a holiday (RJ), it is a state holiday.

Does it handle holidays that are moved by law?

Yes, the transfers written in state laws: Acre moves most holidays to Friday, Santa Catarina celebrates some on the following Sunday. The output keeps both the date actually observed and the officialDate of the law, with moved: true. One-off transfers by decree in a single year are not modeled.

How is "N business days" counted?

The start date is not counted; each following day that is not a Saturday, Sunday or holiday (national, plus the state you choose) counts as one. A negative number counts backwards. With 0, you get the start date itself if it is a business day, otherwise the next one. holidaysSkipped lists the weekday holidays that were jumped over. It is a calendar calculation, not a legal opinion on procedural deadlines (courts may have their own suspension days).

Are municipal holidays included?

Not yet. City anniversaries, patron saints and Corpus Christi where it is a city holiday are not in the table. If your deadline depends on a city holiday, add that day yourself.

Which years are supported?

2024 to 2100, computed with the laws in force in 2026. Movable dates (Good Friday, Carnival, Corpus Christi) are calculated from Easter for each year.

How many dates can I check in one run?

Up to 1,000 dates in check mode (format YYYY-MM-DD), and business-day counts of up to 3,650 days forward or back. Everything runs offline, so a run takes a few seconds.

How reliable is the legal table?

Each row cites the law and the official page used to confirm it. Rows confirmed only by press or unofficial copies come with verification: "secondary", and the notes field flags state holidays whose legality is disputed.

Use it via API

Run it from any language and get the results as JSON. Replace <YOUR_API_TOKEN> with your Apify API token.

curl -X POST "https://api.apify.com/v2/acts/br_data_hub~br-holidays/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "list", "includeOptional": true, "businessDays": 5, "optionalAsHolidays": false}'

from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("br_data_hub/br-holidays").call(run_input={'mode': 'list', 'includeOptional': True, 'businessDays': 5, 'optionalAsHolidays': False})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

You can also schedule runs, send results to webhooks, or connect the Actor to Make, Zapier, n8n, Google Sheets and other integrations.

Use it with AI agents (MCP)

This Actor is ready for AI agents: typed input and output schemas, pay-per-event pricing, limited permissions and short runs.

• Apify MCP server: add https://mcp.apify.com/?tools=br_data_hub/br-holidays to Claude, ChatGPT, Cursor, VS Code or any MCP client, and the agent can call this Actor as a tool.
• Agent frameworks: call it from LangChain, LlamaIndex, CrewAI or the OpenAI Agents SDK through the Apify integrations, or with the API call above.
• Results come as structured JSON with stable field names, documented in the Output tab.

FAQ

Where does the data come from?

• The legal table is in data/feriados.json, versioned with the code. Each row cites the law and the official page used to confirm it (court, prosecutor, legislature or government calendars). Rows marked verification: "secondary" were only confirmed by press or unofficial copies. - Years 2024 to 2100, using the laws in force in 2026. A future law changing a holiday needs a table update. - One-off transfers by decree (a governor moving a holiday in a given year) are not modeled; statutory transfer rules are. - Some state holidays are legally disputed (federal Lei 9.093/1995 allows states only one "data magna"); the notes field flags known disputes. - Municipal holidays are not included yet (city anniversaries, patron saints, Corpus Christi where it is a city holiday). They are planned for a later version.

How much does it cost?

$0.001 per result. Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. See How much does it cost? above for examples.

Do I pay for errors or empty results?

No. Charged once per row returned: a holiday, a checked date or a business-day calculation.

Can I run it on a schedule or connect it to other tools?

Yes. Use Apify schedules to run it daily or weekly, webhooks to get notified, and integrations such as Make, Zapier, n8n and Google Sheets. Everything also works through the API.

Can AI agents use it?

Yes. It works as a tool in the Apify MCP server and in agent frameworks, and AI agents can pay per event. See Use it with AI agents (MCP).

Is it legal to use this data?

The Actor reads only public, official sources and keeps personal data masked as the source publishes it. You are responsible for how you use the data, including LGPD compliance.

I found a bug or need a feature. What should I do?

Open an issue in the Issues tab. We answer within 14 days, usually much sooner.

More Actors from BR Data Hub

Actor	What it does
Brazil CNPJ Lookup API (Consulta CNPJ)	Look up Brazilian companies by CNPJ: registration status, partners (masked CPF), activities, tax regime and sc
Brazil Public Contracts API (PNCP Contratos)	Get Brazilian government contracts from PNCP, the official national procurement portal: buyer, supplier, objec
Brazil Open Tenders API (Licitações Abertas)	Find Brazilian government tenders that are open for proposals right now, from PNCP, the official national proc
Brazil Municipalities & IBGE Codes (Municípios)	List Brazilian municipalities, search them by name (accents and typos tolerated) or resolve IBGE codes
Brazil Banks & Pix Directory (Bancos e ISPB)	Every Brazilian bank and payment institution from official Banco Central lists: ISPB, COMPE bank code, short a
Brazil Boleto Validator & Parser (Boleto)	Validate Brazilian boletos in bulk (digitable line or barcode, bank and utility/tax slips): check digits per f

See all our Actors at apify.com/br_data_hub.

Usar em português

Feriados nacionais e estaduais e cálculo de dias úteis, com a lei de cada feriado. A tabela cobre os feriados nacionais (inclusive o Dia da Consciência Negra, nacional desde 2024), as datas móveis calculadas pela Páscoa e os feriados estaduais das 27 UFs, com as transferências previstas em lei (Acre para a sexta-feira, Santa Catarina para o domingo). Roda sem API externa e responde em segundos.

Para que serve: calcular prazos e vencimentos em dias úteis, montar agendas e escalas, saber se uma data é dia útil numa UF e dar a agentes de IA uma ferramenta confiável de calendário brasileiro.

Como usar em 3 passos:

1. Clique em Try for free e escolha o modo: List holidays (listar), Check if dates are business days (conferir datas) ou Add N business days (somar dias úteis).
2. Preencha os campos do modo: ano e UFs para listar; UF e datas para conferir; UF, data inicial e número de dias úteis para somar.
3. Clique em Start e veja o resultado na aba Output ou pela API.

Exemplos de entrada:

{ "mode": "list", "year": 2027, "states": ["SP", "RJ"] }

{ "mode": "addBusinessDays", "state": "SP", "startDate": "2026-12-23", "businessDays": 5 }

Campos principais: no modo lista, date, weekday, name (nome em português), nameEn, type (national, state ou optional), state, officialDate, moved, law, source, verification e notes. No modo conferir, isBusinessDay, isWeekend, reason e holidays. No modo somar, resultDate, resultWeekday, calendarDays e holidaysSkipped.

Bom saber: Carnaval, Quarta-feira de Cinzas e Corpus Christi são ponto facultativo (optional) e contam como dia útil, a menos que você ligue optionalAsHolidays. A data inicial não entra na contagem. Feriados municipais ainda não estão incluídos. Anos de 2024 a 2100.

O que é grátis: entrada inválida (data, UF ou ano fora do intervalo) faz a execução parar com a mensagem do erro, sem cobrança. Você paga por linha entregue: um feriado, uma data conferida ou um cálculo.

Quanto custa: $0.001 por resultado (result); 1.000 resultados saem por $1.00. Desconto pelo nível da assinatura Apify: Bronze 10%, Silver 20%, Gold ou acima 30%. Erros e consultas sem resultado não são cobrados. Use também pela API ou por agentes de IA no servidor MCP da Apify (https://mcp.apify.com/?tools=br_data_hub/br-holidays).