feriado.dev v1.0.0

Documentacao da API

API REST de feriados brasileiros. Consulte feriados nacionais, estaduais e municipais, incluindo feriados moveis derivados da Pascoa.

BASE URL https://feriado.dev/api/v1

Quick Start

Crie sua chave de API

Registre-se para obter uma chave gratuita com 1.000 requisicoes/mes.

cURL

curl -X POST https://feriado.dev/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "name": "Meu App"}'

Faca sua primeira requisicao

Use sua chave no header X-API-Key para consultar feriados.

cURL

curl https://feriado.dev/api/v1/holidays?year=2025 \
  -H "X-API-Key: fdev_sua_chave_aqui"

Explore os endpoints

Consulte feriados, estados, cidades e calcule dias uteis. Veja todos os endpoints abaixo.

Authentication

Todas as requisicoes autenticadas devem incluir o header X-API-Key.

Header

X-API-Key: fdev_sua_chave_aqui

Planos

Plano	Limite Mensal	Endpoints
Free	1.000 req/mes	Todos os endpoints
Pro	50.000 req/mes	Todos os endpoints

Rate Limit Headers

Cada resposta inclui headers indicando seu uso:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2025-02-01

GET /holidays Free

Retorna uma lista de feriados filtrados por ano, mes, estado, cidade e/ou tipo.

Parametros

Parametro	Tipo	Obrigatorio	Descricao
`year`	integer	Sim	Ano para consulta (2020-2045)
`month`	integer	Nao	Mes para filtro (1-12)
`state`	string	Nao	Codigo UF do estado (ex: SP, RJ)
`city`	string	Nao	Codigo IBGE da cidade (7 digitos). Requer `state`.
`type`	string	Nao	Tipos separados por virgula: national, state, municipal, optional

Exemplo de Requisicao

cURL

curl "https://feriado.dev/api/v1/holidays?year=2025&state=SP" \
  -H "X-API-Key: fdev_sua_chave"

Exemplo de Resposta

JSON

{
  "year": 2025,
  "count": 2,
  "holidays": [
    {
      "date": "2025-01-01",
      "name": "Confraternizacao Universal",
      "name_en": "New Year's Day",
      "type": "national",
      "scope_type": "national",
      "scope_code": "BR",
      "category": "civil",
      "half_day": false
    },
    {
      "date": "2025-04-18",
      "name": "Sexta-feira Santa",
      "name_en": "Good Friday",
      "type": "national",
      "scope_type": "national",
      "scope_code": "BR",
      "category": "religious",
      "half_day": false
    }
  ]
}

GET /holidays/:date Free

Verifica se uma data especifica e feriado e retorna os feriados correspondentes.

Parametros

Parametro	Tipo	Obrigatorio	Descricao
`date`	string (path)	Sim	Data no formato YYYY-MM-DD
`state`	string (query)	Nao	Codigo UF do estado
`city`	string (query)	Nao	Codigo IBGE da cidade. Requer `state`.

Exemplo de Requisicao

cURL

curl "https://feriado.dev/api/v1/holidays/2025-12-25" \
  -H "X-API-Key: fdev_sua_chave"

Exemplo de Resposta

JSON

{
  "date": "2025-12-25",
  "is_holiday": true,
  "holidays": [
    {
      "date": "2025-12-25",
      "name": "Natal",
      "name_en": "Christmas",
      "type": "national",
      "scope_type": "national",
      "scope_code": "BR",
      "category": "religious",
      "half_day": false
    }
  ]
}

GET /states Free

Retorna todos os 26 estados brasileiros mais o Distrito Federal.

Exemplo de Requisicao

cURL

curl "https://feriado.dev/api/v1/states" \
  -H "X-API-Key: fdev_sua_chave"

Exemplo de Resposta

JSON

{
  "count": 27,
  "states": [
    {
      "uf": "SP",
      "name": "Sao Paulo",
      "ibge_code": "35"
    }
  ]
}

GET /states/:uf/cities Free

Retorna todas as cidades de um estado.

Parametros

Parametro	Tipo	Obrigatorio	Descricao
`uf`	string (path)	Sim	Codigo UF do estado (ex: SP)
`search`	string (query)	Nao	Filtro de busca por nome (minimo 2 caracteres)

Exemplo de Requisicao

cURL

curl "https://feriado.dev/api/v1/states/SP/cities?search=Camp" \
  -H "X-API-Key: fdev_sua_chave"

Exemplo de Resposta

JSON

{
  "state": "SP",
  "count": 2,
  "cities": [
    {
      "ibge_code": "3509502",
      "name": "Campinas",
      "state_uf": "SP"
    }
  ]
}

GET /business-days Pro

Calcula o numero de dias uteis entre duas datas, excluindo fins de semana e feriados.

Parametros

Parametro	Tipo	Obrigatorio	Descricao
`start`	string	Sim	Data inicial no formato YYYY-MM-DD
`end`	string	Sim	Data final no formato YYYY-MM-DD
`state`	string	Nao	Codigo UF para incluir feriados estaduais
`city`	string	Nao	Codigo IBGE para incluir feriados municipais. Requer `state`.
`include_optional`	boolean	Nao	Incluir pontos facultativos (default: false)

Exemplo de Requisicao

cURL

curl "https://feriado.dev/api/v1/business-days?start=2026-01-01&end=2026-01-31&state=SP" \
  -H "X-API-Key: fdev_sua_chave"

Exemplo de Resposta

JSON

{
  "start": "2026-01-01",
  "end": "2026-01-31",
  "business_days": 21,
  "total_days": 31,
  "weekends": 9,
  "holidays": 1,
  "holidays_on_weekends": 0
}

POST /keys Free

Cria uma nova chave de API gratuita.

Body (JSON)

Campo	Tipo	Obrigatorio	Descricao
`email`	string	Sim	Endereco de email valido
`name`	string	Sim	Nome do aplicativo ou projeto

Exemplo de Requisicao

cURL

curl -X POST "https://feriado.dev/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "name": "Meu App"}'

Exemplo de Resposta

JSON — 201 Created

{
  "api_key": "fdev_abc123def456ghi789jkl012mno345",
  "plan": "free",
  "limits": {
    "monthly": 1000
  }
}

Response Codes

200 OK — Requisicao bem-sucedida.

JSON

{
  "year": 2025,
  "count": 12,
  "holidays": [...]
}

400 Bad Request — Parametro ausente ou invalido.

JSON

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Parameter 'year' is required",
    "param": "year"
  }
}

403 Forbidden — Chave invalida ou endpoint restrito ao seu plano.

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This endpoint requires a Pro plan"
  }
}

429 Too Many Requests — Limite de requisicoes excedido.

JSON

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly request limit exceeded. Upgrade to Pro for higher limits."
  }
}

SDKs & Exemplos

Exemplos de uso em diferentes linguagens.

cURL

# Listar feriados de 2025
curl "https://feriado.dev/api/v1/holidays?year=2025" \
  -H "X-API-Key: fdev_sua_chave"

# Verificar se uma data e feriado
curl "https://feriado.dev/api/v1/holidays/2025-12-25" \
  -H "X-API-Key: fdev_sua_chave"

# Calcular dias uteis
curl "https://feriado.dev/api/v1/business-days?start=2026-01-01&end=2026-01-31" \
  -H "X-API-Key: fdev_sua_chave"

JavaScript (fetch)

const API_KEY = 'fdev_sua_chave';
const BASE = 'https://feriado.dev/api/v1';

// Listar feriados
const res = await fetch(`${BASE}/holidays?year=2025`, {
  headers: { 'X-API-Key': API_KEY }
});
const data = await res.json();
console.log(data.holidays);

// Verificar data especifica
const check = await fetch(`${BASE}/holidays/2025-12-25`, {
  headers: { 'X-API-Key': API_KEY }
});
const result = await check.json();
console.log(result.is_holiday); // true

// Calcular dias uteis
const bd = await fetch(
  `${BASE}/business-days?start=2026-01-01&end=2026-01-31`,
  { headers: { 'X-API-Key': API_KEY } }
);
const days = await bd.json();
console.log(days.business_days); // 21

Python (requests)

import requests

API_KEY = "fdev_sua_chave"
BASE = "https://feriado.dev/api/v1"
headers = {"X-API-Key": API_KEY}

# Listar feriados
res = requests.get(f"{BASE}/holidays", params={"year": 2025}, headers=headers)
holidays = res.json()["holidays"]
print(f"Encontrados {len(holidays)} feriados")

# Verificar data especifica
res = requests.get(f"{BASE}/holidays/2025-12-25", headers=headers)
print(res.json()["is_holiday"])  # True

# Calcular dias uteis
res = requests.get(
    f"{BASE}/business-days",
    params={"start": "2026-01-01", "end": "2026-01-31"},
    headers=headers,
)
print(res.json()["business_days"])  # 21