Documentação

A Holiday API retorna feriados publicos e observancias por pais e/ou religiao. O endpoint Business days (GET /api/business-days) usa a mesma autenticacao por chave de API. Todas as requisicoes exigem autenticacao com API key. Voce pode criar e gerenciar API keys no seu dashboard. O plano Free (padrao) usa a mesma URL base e a mesma API key para voce testar a integracao antes de ir para producao.

Toda conta verificada comeca no plano Free. Voce pode usar os mesmos endpoints, parametros e autenticacao para construir e testar sua integracao. Quando o plano Free nao for mais suficiente, faca upgrade no dashboard.

O que funciona igual

Voce tem acesso a mesma Holiday API: a mesma URL base, GET /api/holidays e os mesmos parametros de consulta (country, religion, from, to, lang, region, provisional, type, scope). GET /api/business-days tambem esta disponivel com a mesma autenticacao e o formato da resposta e identico, entao voce pode desenvolver e testar seu codigo contra a API real sem mudar nada ao fazer upgrade.

Limitacoes

• Cota mensal de requisicoes: O plano Free inclui um numero fixo de requisicoes por mes calendario. Quando voce atinge a cota, as requisicoes ficam bloqueadas ate o proximo mes ou ate voce fazer upgrade.
• Limites de recursos: O plano Free limita API keys, idiomas e acesso a feriados por subdivisao. Veja precos para os limites completos.
• Sem overage no Free: O plano Free nao inclui overage pago. Faca upgrade para continuar depois de atingir o limite.

Para obter o conjunto completo de resultados e limites prontos para producao, escolha um plano em precos ou acesse Uso ou Cobranca no seu dashboard.

Envie sua API key no cabecalho Authorization como token Bearer. Crie chaves na pagina API Keys do seu dashboard.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

Use https://api.holidaydb.com para todas as requisicoes da API. Para CURL e integracoes no servidor voce deve usar esta URL absoluta.

Retorna feriados filtrados por country e/ou religion. Pelo menos um entre country ou religion e obrigatorio.

Parametros de consulta

Response: array JSON de objetos de feriado com uuid, country_code, religion_slug, type, scope, region_codes, region_names, start_date, end_date, provisional, substitute, summary, language. Para calendarios por pais (country_code nao nulo), type e scope descrevem categorias territoriais (feriado publico vs observancia, nacional vs subnacional). Para calendarios religiosos (religion_slug nao nulo e muitas vezes country_code nulo), type e scope podem ser "unknown" e nao devem ser interpretados como territoriais; use religion_slug (e datas) para trabalhar com essas observancias. Feriados substitutos incluem canonical_uuid. Use include=canonical para embutir o feriado canonico de cada substituto; use include=substitute para embutir um array substitutes em cada canonico.

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "country_code": "US",
    "religion_slug": null,
    "type": "public_holiday",
    "scope": "national",
    "region_codes": [],
    "region_names": [],
    "start_date": "2026-07-04",
    "end_date": "2026-07-04",
    "provisional": false,
    "summary": "Independence Day",
    "language": "en"
  }
  // ... mais objetos de feriado na resposta completa
]

Retorna quantos dias uteis caem em um mes calendario ou ano completo para um pais ISO. Por padrao, a semana util e de segunda a sexta (dias ISO 1,2,3,4,5); voce pode sobrescrever com weekdays opcional. Por padrao, apenas feriados nacionais sao excluidos. Com region opcional, a contagem tambem exclui feriados subnacionais cujos region_codes contenham esse codigo ISO 3166-2: a mesma regra de GET /api/holidays?country=...&region=... (dias nacionais sempre contam; region nao significa 'somente regiao'). Este endpoint exige o mesmo Bearer API key e as mesmas permissoes de token de GET /api/holidays.

Filtragem por subdivisao exige um plano que inclua feriados de subdivisao (Pro/Full), igual a API de feriados.

Parametros de consulta

Response: objeto JSON com country_code, region (codigo normalizado ou null), weekdays (array de inteiros realmente usados na contagem), year e month (ambos null no modo intervalo), range (datas from/to, sempre a janela inclusiva resolvida) e business_days (contagem inteira). Quando include e 1 ou true, a resposta tambem traz holidays: feriados publicos usados na contagem (somente nacional quando region e omitido; nacional + subnacional correspondente quando region e informado), com campos completos como no ultimo tab de exemplo.

Se ainda nao cobrimos o calendario desse pais, a API retorna 404 com error e country_code (nao e o mesmo corpo de "Country not found" em GET /api/holidays).

Os quatro primeiros tabs de exemplo omitem include (sem holidays no JSON de exemplo). O ultimo tab mostra include=1 com array holidays.

Os exemplos abaixo usam 2026. Os numeros de business_days foram conferidos manualmente com regras nacionais oficiais: feriados federais dos EUA (OPM); feriados alemaes observados em todos os estados naquela data; feriados estatutarios federais do Canada (julho de 2026 tem Canada Day em uma quarta-feira). Feriados fixos no fim de semana nao reduzem a contagem de dias de semana. Valores da API ao vivo seguem os feriados armazenados no HolidayDB e devem bater para as mesmas regras; se uma linha for adicionada ou corrigida em nossos dados, as contagens podem mudar levemente.

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/business-days?country=US&year=2026&month=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "business_days": 20
}

Retorna quantos working minutes (e um resumo de horas/minutos) caem em um mes calendario, ano completo ou intervalo de datas inclusivo para um pais ISO. Usa as mesmas regras de dias da semana e feriados de GET /api/business-days, depois multiplica por uma duracao de jornada obrigatoria (workday).

Filtragem por subdivisao (region) exige plano com feriados de subdivisao (Pro/Full), igual a API de feriados e business-days.

Parametros de consulta

Response: objeto JSON com os mesmos campos base de business-days, mais working_days, workday, workday_minutes, working_minutes e working_hours (resumo horas/minutos).

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/working-hours?country=US&year=2026&month=1&workday=08:00"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "working_days": 20,
  "workday": "08:00",
  "workday_minutes": 480,
  "working_minutes": 9600,
  "working_hours": {
    "hours": 160,
    "minutes": 0
  }
}

Prorrateia um valor salarial com base em working days dentro de uma janela selecionada de um periodo de folha. Working days sao contados como dias ISO selecionados (padrao seg-sex) menos feriados publicos (e feriados regionais opcionais quando region e usado).

Voce pode escolher o periodo de folha pelo modo calendario (year/month) ou por datas explicitas (period_from/period_to). Opcionalmente, informe uma janela personalizada de proracao (from/to) dentro desse periodo; caso contrario, a janela e o periodo inteiro.

Parametros de consulta

Response: objeto JSON com period_working_days, window_working_days, ratio, salary e prorated_salary. Use period para os limites do periodo de folha e range para a janela de proracao.

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/salary-proration?country=US&year=2026&month=1&salary=5000"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 20,
  "window_working_days": 20,
  "ratio": "1.000000",
  "salary": "5000.00",
  "salary_scale": 2,
  "prorated_salary": "5000.00"
}

Calcula licenca acumulada, licenca tirada (janela opcional) e saldo final para um periodo de apuracao. O tempo de trabalho e derivado dos weekdays selecionados menos feriados publicos para o country selecionado e region opcional.

Parametros de consulta

Response: objeto JSON com limites do periodo, totais de trabalho e campos hibridos de saldo: accrued_hours/taken_hours/ending_balance_hours mais valores derivados *_days.

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/leave-pto?country=US&year=2026&month=1&workday=08:00&accrual_hours_per_month=8"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "workday": "08:00",
  "workday_minutes": 480,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 21,
  "accrued_hours": "8.00",
  "taken_hours": "0.00",
  "ending_balance_hours": "8.00"
}

Calcula uma data de vencimento adicionando dias uteis a uma data inicial, excluindo fins de semana e feriados publicos para o country selecionado e region opcional.

Parametros de consulta

Os parametros obrigatorios sao country, start e sla_business_days.

Response: objeto JSON com deadline e campos de contexto relacionados (country/region, weekdays e intervalo de analise).

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/sla-deadline?country=US&start=2026-01-02&sla_business_days=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "sla_business_days": 1,
  "deadline": "2026-01-05"
}

Calcula uma data estimada de entrega adicionando dias uteis a uma data inicial, excluindo fins de semana e feriados publicos para o country selecionado e region opcional.

Parametros de consulta

Os parametros obrigatorios sao country, start e delivery_business_days.

Response: objeto JSON com delivery_date e campos de contexto relacionados (country/region, weekdays e intervalo de analise).

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/delivery-date?country=US&start=2026-01-02&delivery_business_days=3"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "delivery_business_days": 3,
  "delivery_date": "2026-01-07"
}

Retorna oportunidades de 'bridge day' para um country e year - sequencias curtas de dias de trabalho entre dias nao uteis, onde pelo menos um bloco vizinho contem feriado publico. Cada oportunidade inclui o bloco consecutivo de folga resultante e uma razao de eficiencia para voce classificar boas oportunidades de feriado prolongado.

Parametros de consulta

Os parametros obrigatorios sao country e year.

Response: objeto JSON com um array bridge_opportunities ordenado por eficiencia decrescente. Cada oportunidade expoe os dias uteis que precisam ser tirados, o bloco consecutivo de folga resultante, a quantidade de dias de folga, a razao de eficiencia (dias de folga / dias de ponte) e os feriados ancora.

Exemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/bridge-days?country=DE&year=2026"

{
  "country_code": "DE",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": null,
  "max_gap": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  },
  "bridge_opportunities": [
    {
      "bridge_days": [
        "2026-05-15"
      ],
      "bridge_days_count": 1,
      "off_block": {
        "from": "2026-05-14",
        "to": "2026-05-17"
      },
      "off_days_count": 4,
      "efficiency": 4,
      "anchor_holidays": [
        {
          "uuid": "...",
          "summary": "Christi Himmelfahrt",
          "start_date": "2026-05-14",
          "end_date": "2026-05-14"
        }
      ]
    }
  ]
}

Retorna a lista de codigos de idioma suportados pelo HolidayDB para nomes de feriados traduzidos. Este endpoint esta disponivel para planos que incluem varios idiomas (Full). Se o seu plano incluir apenas ingles, a API retorna `403`.

Parametros de consulta

Nenhum.

Resposta

Objeto JSON com um array languages. Cada item contem um code (ex.: en, de, pt_BR, en_US) e um name. Passe esses codigos em lang; veja o parametro lang para correspondencia e fallback de tags primary.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/languages"

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "de", "name": "German" }
 ]
}

As paginas de calculadora deste site usam um endpoint auxiliar publico GET /api/tools/languages para preencher seletores de idioma sem exigir API key.

Corpo da resposta de erro

Respostas de erro sao JSON na API de produto autenticada (GET /api/holidays, endpoints de calculadora, etc.).

Rotas publicas /api/tools/* usam outro formato de erro e nao sao descritas aqui.

{
  "error": "Unauthorized. Provide a valid API key in the Authorization header as Bearer token."
}

O parametro region (feriados de subdivisao) e o parametro lang (multiplos idiomas) exigem planos Pro ou Full. Basic inclui apenas feriados nacionais em ingles. Veja precos ou suas paginas Cobranca e Uso para detalhes.