Iniciação rápida: Conecte-se ao FXMacroData com o Node.js

A API REST FXMacroData foi projetada para ser consumida a partir de qualquer linguagem que possa fazer uma solicitação HTTP GET. fetch Este guia o leva do zero para um script multi-indicador em menos de dez minutos.

Requisitos prévios

• Node.js 18 ou posterior v18 introduziu o global fetch API; recomenda-se a produção de versões v20+
• npm (composto com Node.js) só é necessário se você optar por adicionar pacotes opcionais
• Uma chave de API FXMacroData Inscreva-se em / subscrever e copiar a chave do painel

Verifique a versão do Node.js:

node --version   # should print v18.x.x or later

Passo 1 Guarde sua chave de API de forma segura

Nunca codifique uma chave de API em arquivos de origem que possam ser comprometidos com o controle de versão.

No Linux / macOS, adicione ao seu perfil de shell (~/.bashrc Ou ... ~/.zshrc):

export FXMD_API_KEY="your_actual_api_key_here"

No Windows (PowerShell):

$env:FXMD_API_KEY = "your_actual_api_key_here"

Para os projetos Node.js, um .env Ficheiro com o Dotenv O pacote é uma alternativa popular ver Passo 6 para essa configuração.

Passo 2 Compreender a forma da API

Cada endpoint do indicador FXMacroData segue o mesmo padrão, o que torna mais simples construir um auxiliar de busca genérico.

GET https://fxmacrodata.com/api/v1/announcements/{currency}/{indicator}?api_key=YOUR_API_KEY

A resposta é JSON com um nível superior data Cada elemento tem um dateUm número . val, e (na maioria dos indicadores) um announcement_datetime que indica o segundo em que o valor foi liberado:

{
  "data": [
    { "date": "2025-03-19", "val": 4.25, "announcement_datetime": "2025-03-19T18:00:00Z" },
    { "date": "2025-01-29", "val": 4.25, "announcement_datetime": "2025-01-29T19:00:00Z" },
    { "date": "2024-12-18", "val": 4.25, "announcement_datetime": "2024-12-18T19:00:00Z" }
  ]
}

Esta estrutura limpa e consistente não requer quase nenhuma transformação antes de ser usada em lógica de negócios, bancos de dados ou APIs a jusante.

Passo 3 A primeira chamada

Crie um arquivo chamado fxmd.js E adicionar o seguinte. Isto traz a taxa de política do Federal Reserve dos EUA para os últimos dois anos usando o Node.js embutido fetch- Não .

// fxmd.js  —  requires Node.js 18+
const API_KEY = process.env.FXMD_API_KEY;
const BASE    = "https://fxmacrodata.com/api/v1";

async function getIndicator(currency, indicator, startDate) {
  const url = new URL(`${BASE}/announcements/${currency}/${indicator}`);
  url.searchParams.set("api_key", API_KEY);
  if (startDate) url.searchParams.set("start", startDate);

  const res = await fetch(url.toString());
  if (!res.ok) {
    throw new Error(`API error ${res.status}: ${await res.text()}`);
  }
  const json = await res.json();
  return json.data ?? [];
}

// Fetch the Fed policy rate
const data = await getIndicator("usd", "policy_rate", "2023-01-01");
console.log(`Latest USD policy rate: ${data[0]?.val}% on ${data[0]?.date}`);

- Acerte:

FXMD_API_KEY=your_key node fxmd.js

Passo 4 Obter múltiplos indicadores em paralelo

Promise.all Aqui está um padrão reutilizável para puxar várias moedas e indicadores de uma só vez:

const CURRENCIES  = ["usd", "eur", "gbp", "aud", "jpy"];
const INDICATORS  = ["policy_rate", "inflation"];
const START       = "2024-01-01";

// Build a flat list of [currency, indicator] pairs
const pairs = CURRENCIES.flatMap(c => INDICATORS.map(i => [c, i]));

// Fire all requests in parallel
const results = await Promise.all(
  pairs.map(([currency, indicator]) =>
    getIndicator(currency, indicator, START)
      .then(data => ({ currency, indicator, latest: data[0] ?? null }))
      .catch(err => ({ currency, indicator, latest: null, error: err.message }))
  )
);

// Print a quick summary
for (const row of results) {
  if (row.error) {
    console.log(`${row.currency.toUpperCase()} ${row.indicator}: ERROR — ${row.error}`);
  } else if (row.latest) {
    console.log(
      `${row.currency.toUpperCase()} ${row.indicator}: ${row.latest.val} (${row.latest.date})`
    );
  }
}

O ... .catch Por pedido significa que uma única resposta negativa não interrompe o lote inteiro útil quando executar trabalhos noturnos onde os dados parciais ainda são acionáveis.

Passo 5 Plano de produção completo

Abaixo está um script compatível com o CommonJS completo com tratamento de erros adequado, listas de moeda e indicadores configuráveis e saída formatada para registro ou processamento a jusante:

// macro-snapshot.js  —  CommonJS, Node.js 18+
"use strict";

const API_KEY = process.env.FXMD_API_KEY;
const BASE    = "https://fxmacrodata.com/api/v1";

if (!API_KEY) {
  console.error("Error: FXMD_API_KEY environment variable is not set.");
  process.exit(1);
}

// ── Configuration ──────────────────────────────────────────────────────────
const CURRENCIES = ["usd", "eur", "gbp", "cad", "jpy", "aud", "nzd", "chf"];
const INDICATORS = ["policy_rate", "inflation", "unemployment"];
const START_DATE = "2024-01-01";
// ───────────────────────────────────────────────────────────────────────────

async function getIndicator(currency, indicator, startDate) {
  const url = new URL(`${BASE}/announcements/${currency}/${indicator}`);
  url.searchParams.set("api_key", API_KEY);
  if (startDate) url.searchParams.set("start", startDate);

  const res = await fetch(url.toString());
  if (!res.ok) {
    const body = await res.text().catch(() => "");
    throw new Error(`HTTP ${res.status}${body ? ": " + body.slice(0, 120) : ""}`);
  }
  const json = await res.json();
  return Array.isArray(json.data) ? json.data : [];
}

async function main() {
  const pairs = CURRENCIES.flatMap(c => INDICATORS.map(i => [c, i]));

  const results = await Promise.all(
    pairs.map(async ([currency, indicator]) => {
      try {
        const data = await getIndicator(currency, indicator, START_DATE);
        return { currency, indicator, latest: data[0] ?? null, error: null };
      } catch (err) {
        return { currency, indicator, latest: null, error: err.message };
      }
    })
  );

  // Group by currency for readable output
  const byCurrency = {};
  for (const row of results) {
    if (!byCurrency[row.currency]) byCurrency[row.currency] = [];
    byCurrency[row.currency].push(row);
  }

  console.log("\n=== FXMacroData Macro Snapshot ===\n");
  for (const [currency, rows] of Object.entries(byCurrency)) {
    console.log(`  ${currency.toUpperCase()}`);
    for (const row of rows) {
      if (row.error) {
        console.log(`    ${row.indicator.padEnd(20)} — error: ${row.error}`);
      } else if (row.latest) {
        console.log(
          `    ${row.indicator.padEnd(20)} ${String(row.latest.val).padStart(8)}  (${row.latest.date})`
        );
      } else {
        console.log(`    ${row.indicator.padEnd(20)} — no data`);
      }
    }
    console.log();
  }
}

main().catch(err => {
  console.error("Fatal:", err.message);
  process.exit(1);
});

Execute o script:

FXMD_API_KEY=your_key node macro-snapshot.js

Produto da amostra:

=== FXMacroData Macro Snapshot ===

  USD
    policy_rate             4.25  (2025-03-19)
    inflation               2.40  (2025-04-10)
    unemployment            4.20  (2025-04-04)

  EUR
    policy_rate             2.40  (2025-04-17)
    inflation               2.20  (2025-04-16)
    unemployment            6.10  (2025-03-31)

  GBP
    policy_rate             4.50  (2025-03-20)
    inflation               2.60  (2025-03-26)
    unemployment            4.40  (2025-04-15)
  ...

Passo 6 Utilização do Dotenv para o Desenvolvimento Local

Quando você está construindo um projeto maior do Node.js é mais conveniente manter sua chave de API em um .env arquivo e carregá-lo automaticamente com o Dotenv Pacote:

npm install dotenv

Crie um .env arquivo na raiz do seu projeto (adicione-o para .gitignore imediatamente):

FXMD_API_KEY=your_actual_api_key_here

Adicione uma linha no topo do seu script:

require("dotenv").config();   // CommonJS
// or
import "dotenv/config";       // ES module

O resto do guião diz: process.env.FXMD_API_KEY exactamente como antes não são necessárias outras alterações.

Passo 7 Explore o catálogo completo dos indicadores

O snapshot macro acima abrange três indicadores, mas o FXMacroData expõe mais de 80 séries temporais em 14 grandes blocos de moedas. getIndicator A ajuda funciona para todos eles apenas trocar a moeda e o indicador de lesma.

• Taxas reais Subtraia . inflation de policy_rate A diferença de taxa de câmbio real entre duas moedas é um dos principais factores que determinam a orientação do câmbio a médio prazo. Docs sobre a taxa de juro de política do dólar para os detalhes dos pontos finais.
• Dados do trabalho - Não . unemployment- Não . non_farm_payrollsE ... average_hourly_earnings (USD) dar sinais precoces sobre as funções de reacção dos bancos centrais.
• Sentimento - Não . consumer_confidence- Não . pmiE ... business_confidence Os indicadores de dados concretos são mais avançados em um a dois meses e podem preceder os movimentos cambiais antes de aparecerem nas decisões sobre as taxas.
• Fluxos comerciais - Não . trade_balance- Não . exportsE ... imports Relacionar os pares de commodities e moedas (AUD, NZD, CAD) com as variações das condições de troca.

Consulte o catálogo completo de qualquer moeda em https://fxmacrodata.com/api/v1/catalogue/{currency}?api_key=YOUR_API_KEY, ou explore os documentos interativos em Aplicativo de informação- Não .

Resumo

Agora você tem tudo o que precisa para consumir FXMacroData do Node.js:

• Um genérico . getIndicator(currency, indicator, startDate) auxiliar que lida com verificação de autenticação e erros
• Solicitações paralelas de múltiplos indicadores através de Promise.all com isolamento de erros por pedido
• Um script pronto para produção que você pode agendar, implantar em uma função sem servidor ou integrar em um backend existente do Node.js
• Gerenciamento seguro de chaves de API através de variáveis de ambiente ou dotenv

Próximos passos naturais: agendar o script do snapshot com um cron job ou um task runner como n8nA mesma estrutura JSON limpa que o script lê funciona da mesma forma, quer você esteja criando um painel de controle React, uma API Express ou um gatilho de função Cloud.

Para mais guias específicos para cada língua, ver o Guia de início rápido A secção os procedimentos de Python e R cobrem o mesmo conjunto de indicadores com ferramentas específicas do ecossistema para análise e visualização.