open-deputado

Type-safe API client for Brazil's Chamber of Deputies (Câmara dos Deputados).

import od from 'open-deputado'

// List deputies from São Paulo
const deputies = await od.deputies.list({ state: 'SP', party: 'PT' })

// Get deputy details
const deputy = await od.deputies.getById(74693)

// Works in Portuguese too!
const deputados = await od.deputados.listar({ siglaUf: 'SP' })

Features

• Complete API coverage - All 77 endpoints from the Câmara API
• 100% TypeScript - Full type safety with IntelliSense support
• Zero configuration - Just import and use
• Bilingual - English API with Portuguese aliases
• Pagination helpers - Manual pagination + async iterators
• Error handling - Typed errors + .safe() variants

Install

bun add open-deputado
# or
npm install open-deputado

Quick Start

import od from 'open-deputado'

// List deputies with filters
const result = await od.deputies.list({
  party: 'PT',
  state: 'SP',
  gender: 'F',
  limit: 50,
})

console.log(result.data)        // Deputy[]
console.log(result.pagination)  // { page, totalPages, hasNext, ... }

// Get deputy by ID
const deputy = await od.deputies.getById(74693)
console.log(deputy.civilName, deputy.latestStatus.party)

// Get deputy expenses
const expenses = await od.deputies.getExpenses(74693, { year: 2024 })

Resources

Deputies (Deputados)

// List all deputies
od.deputies.list({ party, state, gender, legislatureId, page, limit })

// Async iterate through all
for await (const dep of od.deputies.listAll({ party: 'PT' })) {
  console.log(dep.name)
}

// Get by ID
od.deputies.getById(id)

// Sub-resources
od.deputies.getExpenses(id, { year, month })
od.deputies.getSpeeches(id, { startDate, endDate })
od.deputies.getEvents(id)
od.deputies.getFronts(id)
od.deputies.getCommittees(id)
od.deputies.getHistory(id)
od.deputies.getProfessions(id)
od.deputies.getExternalMandates(id)
od.deputies.getOccupations(id)

Parties (Partidos)

od.parties.list({ legislatureId })
od.parties.getById(id)
od.parties.getLeaders(id)
od.parties.getMembers(id)

Votes (Votações)

od.votes.list({ propositionId, startDate, endDate })
od.votes.getById(id)
od.votes.getOrientations(id)  // How parties oriented members to vote
od.votes.getVotes(id)         // Individual deputy votes

Propositions (Proposições)

od.propositions.list({ typeAcronym, year, authorId, keywords })
od.propositions.getById(id)
od.propositions.getAuthors(id)
od.propositions.getRelated(id)
od.propositions.getThemes(id)
od.propositions.getProgress(id)  // Tramitação
od.propositions.getVotes(id)

Committees (Órgãos)

od.committees.list({ typeCode, acronym })
od.committees.listActive()
od.committees.getById(id)
od.committees.getMembers(id)
od.committees.getEvents(id)
od.committees.getVotes(id)

Legislatures (Legislaturas)

od.legislatures.list()
od.legislatures.getById(id)
od.legislatures.getBoard(id)   // Mesa diretora
od.legislatures.getLeaders(id)

Blocks (Blocos)

od.blocks.list({ legislatureId })
od.blocks.getById(id)
od.blocks.getParties(id)

Fronts (Frentes)

od.fronts.list({ legislatureId })
od.fronts.getById(id)
od.fronts.getMembers(id)

Groups (Grupos)

od.groups.list({ legislatureId, typeCode })
od.groups.getById(id)
od.groups.getHistory(id)
od.groups.getMembers(id)

Events (Eventos)

od.events.list({ typeCode, startDate, endDate, committeeId })
od.events.getById(id)
od.events.getDeputies(id)
od.events.getCommittees(id)
od.events.getAgenda(id)
od.events.getVotes(id)

References (Referências)

od.references.states()           // Brazilian states
od.references.propositionTypes() // PL, PEC, MPV, etc.
od.references.eventTypes()
od.references.committeeTypes()
od.references.deputies.expenseTypes()
od.references.deputies.situations()

Pagination

Manual Pagination

const page1 = await od.deputies.list({ page: 1, limit: 100 })
console.log(page1.pagination.hasNext)  // true
console.log(page1.pagination.totalPages)

const page2 = await od.deputies.list({ page: 2, limit: 100 })

Async Iterators

// Iterate through all (fetches pages automatically)
for await (const deputy of od.deputies.listAll({ party: 'PT' })) {
  console.log(deputy.name)
}

// Collect into array
const all = await od.deputies.listAll({ state: 'RJ' }).toArray()

// Take first N
const first50 = await od.deputies.listAll().take(50).toArray()

// Filter while iterating
const filtered = await od.deputies
  .listAll()
  .filter(d => d.name.startsWith('A'))
  .take(10)
  .toArray()

Error Handling

Typed Exceptions (default)

import { NotFoundError, RateLimitError } from 'open-deputado'

try {
  await od.deputies.getById(999999)
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log(`Deputy ${e.resourceId} not found`)
  } else if (e instanceof RateLimitError) {
    console.log(`Wait ${e.retryAfter} seconds`)
  }
}

Safe Variant (never throws)

const { data, error } = await od.deputies.getById.safe(999999)

if (error) {
  console.log(error.code)  // 'NOT_FOUND'
  console.log(error.message)
} else {
  console.log(data.name)
}

Portuguese Aliases

All resources and methods have Portuguese aliases:

// These are equivalent:
od.deputies.list({ party: 'PT', state: 'SP' })
od.deputados.listar({ siglaPartido: 'PT', siglaUf: 'SP' })

od.deputies.getById(123)
od.deputados.obterPorId(123)

od.parties.getMembers(1)
od.partidos.obterMembros(1)

Resource Mapping

| English | Portuguese | |---------|------------| | deputies | deputados | | parties | partidos | | votes | votacoes | | propositions | proposicoes | | committees | orgaos | | legislatures | legislaturas | | blocks | blocos | | fronts | frentes | | groups | grupos | | events | eventos | | references | referencias |

Method Mapping

| English | Portuguese | |---------|------------| | list | listar | | listAll | listarTodos | | getById | obterPorId | | getExpenses | obterDespesas | | getSpeeches | obterDiscursos | | getMembers | obterMembros | | ... | ... |

TypeScript

All types are exported:

import type {
  Deputy,
  DeputyDetails,
  DeputyExpense,
  Party,
  Vote,
  Proposition,
  PaginatedResponse,
  // Portuguese aliases
  Deputado,
  Partido,
  Votacao,
} from 'open-deputado'

API Reference

The Câmara API documentation: https://dadosabertos.camara.leg.br/swagger/api.html

Contributing

# Install dependencies
bun install

# Run tests
bun test              # Unit tests (mocked)
bun test:integration  # Real API tests

# Type check
bun run typecheck

License

MIT