consultar_terminais_atm
Query ATM terminal statistics by quarter to analyze Brazil's Central Bank payment infrastructure data, with options to filter results and limit records.
Instructions
Consulta estatísticas sobre terminais de autoatendimento (ATM/caixas eletrônicos) por trimestre.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trimestre | Yes | Ano e trimestre no formato YYYYQ (exemplo: '20234') | |
| top | No | Número máximo de registros a retornar (padrão: 100) | |
| filtro | No | Filtro OData para refinar a consulta |
Implementation Reference
- src/index.ts:421-442 (handler)Handler for the 'consultar_terminais_atm' tool. Extracts parameters, calls fetchBCBData on the 'TerminaisATMDA' endpoint with the trimestre parameter, and returns the JSON data as text content.
case "consultar_terminais_atm": { const { trimestre, top = 100, filtro } = args as { trimestre: string; top?: number; filtro?: string; }; const data = await fetchBCBData(`TerminaisATMDA(trimestre=@trimestre)?@trimestre='${trimestre}'`, { formato: "json", top, filter: filtro, }); return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; } - src/index.ts:216-237 (schema)Tool definition including name, description, and input schema for 'consultar_terminais_atm'. Requires 'trimestre' (YYYYQ format), optional 'top' and 'filtro'.
{ name: "consultar_terminais_atm", description: "Consulta estatísticas sobre terminais de autoatendimento (ATM/caixas eletrônicos) por trimestre.", inputSchema: { type: "object", properties: { trimestre: { type: "string", description: "Ano e trimestre no formato YYYYQ (exemplo: '20234')", }, top: { type: "number", description: "Número máximo de registros a retornar (padrão: 100)", }, filtro: { type: "string", description: "Filtro OData para refinar a consulta", }, }, required: ["trimestre"], }, }, - src/index.ts:37-52 (helper)Shared helper function to make API requests to the BCB Olinda service, builds URL with OData params and fetches JSON data. Used by all tool handlers including consultar_terminais_atm.
async function fetchBCBData(endpoint: string, params: QueryParams = {}) { try { const url = buildUrl(endpoint, params); const response = await axios.get(url, { headers: { "Accept": "application/json" } }); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`Erro ao consultar API do BCB: ${error.message}`); } throw error; } } - src/index.ts:24-34 (helper)Helper function to construct OData query URLs for BCB API endpoints, appending parameters like $top, $filter, etc. Used by fetchBCBData.
function buildUrl(endpoint: string, params: QueryParams = {}): string { const url = new URL(`${API_BASE_URL}/${endpoint}`); if (params.formato) url.searchParams.append("$format", params.formato); if (params.top) url.searchParams.append("$top", params.top.toString()); if (params.skip) url.searchParams.append("$skip", params.skip.toString()); if (params.filter) url.searchParams.append("$filter", params.filter); if (params.orderby) url.searchParams.append("$orderby", params.orderby); return url.toString(); } - src/index.ts:263-267 (registration)Registers the handler for ListToolsRequestSchema, which returns the tools array including 'consultar_terminais_atm'.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools, }; });