bcb_serie_valores
Retrieve historical economic data from the Brazilian Central Bank's time series database. Query indicators like IPCA, Selic, and exchange rates by code with optional date filters.
Instructions
Consulta valores de uma série temporal do BCB por código. Retorna dados históricos com data e valor.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| codigo | Yes | Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic) | |
| dataInicial | No | Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional) | |
| dataFinal | No | Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional) |
Implementation Reference
- src/tools.ts:351-390 (handler)The handler function `handleSerieValores` performs the API request to the BCB (Banco Central do Brasil) service, formats the dates, fetches the data, and returns the result.
export async function handleSerieValores( args: { codigo: number; dataInicial?: string; dataFinal?: string }, timeoutMs?: number, maxRetries?: number ): Promise<ToolResult> { try { let url = `${BCB_API_BASE}.${args.codigo}/dados?formato=json`; if (args.dataInicial) url += `&dataInicial=${formatDateForApi(args.dataInicial)}`; if (args.dataFinal) url += `&dataFinal=${formatDateForApi(args.dataFinal)}`; const data = await fetchBcbApi(url, timeoutMs, maxRetries) as SerieValor[]; if (!Array.isArray(data) || data.length === 0) { return { content: [{ type: "text" as const, text: `Nenhum dado encontrado para a série ${args.codigo} no período solicitado.` }] }; } const serieInfo = SERIES_POPULARES.find(s => s.codigo === args.codigo); const result = { serie: { codigo: args.codigo, nome: serieInfo?.nome || `Série ${args.codigo}`, categoria: serieInfo?.categoria || "Desconhecida", periodicidade: serieInfo?.periodicidade || "Desconhecida" }, totalRegistros: data.length, periodoInicial: data[0].data, periodoFinal: data[data.length - 1].data, dados: data.map(d => ({ data: d.data, valor: parseFloat(d.valor) })) }; return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error) { return { content: [{ type: "text" as const, text: `Erro ao consultar série ${args.codigo}: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } - src/tools.ts:743-754 (schema)The tool definition for `bcb_serie_valores` includes its name, description, and input schema (requiring a `codigo`, with optional `dataInicial` and `dataFinal`).
{ name: "bcb_serie_valores", description: "Consulta valores de uma série temporal do BCB por código. Retorna dados históricos com data e valor.", inputSchema: { type: "object" as const, properties: { codigo: { type: "number" as const, description: "Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)" }, dataInicial: { type: "string" as const, description: "Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)" }, dataFinal: { type: "string" as const, description: "Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)" } }, required: ["codigo"] } - src/tools.ts:846-847 (registration)The tool `bcb_serie_valores` is registered within the `dispatchTool` switch statement to map the tool name to the handler function.
case "bcb_serie_valores": return handleSerieValores(args as { codigo: number; dataInicial?: string; dataFinal?: string }, timeoutMs, maxRetries);