# Brazil Holidays & Business Days (Feriados) (`br_data_hub/br-holidays`) Actor Brazilian national and state holidays for all 27 states, with the law behind each one. List holidays by year, check if a date is a business day and add N business days for deadlines. - **URL**: https://apify.com/br_data_hub/br-holidays.md - **Developed by:** [br_data_hub](https://apify.com/br_data_hub) (community) - **Categories:** AI, Developer tools, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.70 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## 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"]}`): ```json { "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"]}`): ```json { "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}`): ```json { "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`](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 `` with your [Apify API token](https://console.apify.com/settings/integrations). ```bash curl -X POST "https://api.apify.com/v2/acts/br_data_hub~br-holidays/run-sync-get-dataset-items?token=" \ -H "Content-Type: application/json" \ -d '{"mode": "list", "includeOptional": true, "businessDays": 5, "optionalAsHolidays": false}' ``` ```python from apify_client import ApifyClient client = ApifyClient("") 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](https://docs.apify.com/platform/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`](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)](https://apify.com/br_data_hub/br-cnpj-lookup) | Look up Brazilian companies by CNPJ: registration status, partners (masked CPF), activities, tax regime and sc | | [Brazil Public Contracts API (PNCP Contratos)](https://apify.com/br_data_hub/br-pncp-contracts) | Get Brazilian government contracts from PNCP, the official national procurement portal: buyer, supplier, objec | | [Brazil Open Tenders API (Licitações Abertas)](https://apify.com/br_data_hub/br-pncp-open-tenders) | Find Brazilian government tenders that are open for proposals right now, from PNCP, the official national proc | | [Brazil Municipalities & IBGE Codes (Municípios)](https://apify.com/br_data_hub/br-ibge-localities) | List Brazilian municipalities, search them by name (accents and typos tolerated) or resolve IBGE codes | | [Brazil Banks & Pix Directory (Bancos e ISPB)](https://apify.com/br_data_hub/br-bank-pix-directory) | Every Brazilian bank and payment institution from official Banco Central lists: ISPB, COMPE bank code, short a | | [Brazil Boleto Validator & Parser (Boleto)](https://apify.com/br_data_hub/br-boleto-parser) | 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](https://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:** ```json { "mode": "list", "year": 2027, "states": ["SP", "RJ"] } ``` ```json { "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`). # Actor input Schema ## `mode` (type: `string`): Choose List to get the holidays of a year, Check to test whether dates are business days, or Add to find the date N business days after (or before) a start date. Each mode uses the fields of its section below. ## `year` (type: `integer`): Set the year to list, 2024 to 2100. Leave empty for the current year. ## `yearTo` (type: `integer`): Set the last year of a range, e.g. 2030 to list 2026 to 2030. Leave empty to list a single year. ## `states` (type: `array`): Enter states whose holidays are added to the national ones, e.g. SP, RJ, AC, or ALL for the 27 states. Leave empty for national holidays only. ## `includeOptional` (type: `boolean`): Keep on to also list Carnival Monday/Tuesday, Ash Wednesday and Corpus Christi (pontos facultativos), marked as type 'optional'. They are not holidays by federal law. ## `state` (type: `string`): Type a two-letter state, e.g. SP, so its state holidays are not business days. Leave empty for national holidays only. ## `dates` (type: `array`): Check mode: enter dates as YYYY-MM-DD, one per line, up to 1,000. Leave empty to check today (Brasília time). ## `startDate` (type: `string`): Add mode: type the date to count from as YYYY-MM-DD (not counted itself). Leave empty for today (Brasília time). ## `businessDays` (type: `integer`): Add mode: set the number of business days, e.g. 5. Use a negative number to count backwards; 0 returns the start date if it is a business day, otherwise the next one. ## `optionalAsHolidays` (type: `boolean`): Turn on to treat Carnival Monday/Tuesday, Ash Wednesday and Corpus Christi as non-business days, as many companies do. Off follows the law strictly. ## Actor input object example ```json { "mode": "list", "states": [ "SP" ], "includeOptional": true, "state": "", "dates": [], "startDate": "", "businessDays": 5, "optionalAsHolidays": false } ``` # Actor output Schema ## `dataset` (type: `string`): Dataset with all results # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "states": [ "SP" ] }; // Run the Actor and wait for it to finish const run = await client.actor("br_data_hub/br-holidays").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "states": ["SP"] } # Run the Actor and wait for it to finish run = client.actor("br_data_hub/br-holidays").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "states": [ "SP" ] }' | apify call br_data_hub/br-holidays --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,br_data_hub/br-holidays" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/NfghbPSCpd0Pzg1wu/builds/eFWgPflambrpaC9Td/openapi.json