Preço do ouro no Google Sheets e Excel: cotações ao vivo via API

Preços do ouro ao vivo em uma planilha

Muita precificação de ouro ainda acontece em planilhas: a tabela de preços de uma joalheria, um estoque de barras, uma planilha de cotação de ouro usado ou um acompanhamento de carteira. Com o preço do ouro ao vivo no Google Sheets ou no Excel, esses números se atualizam sozinhos em vez de serem copiados de um site. Este guia monta as duas coisas: uma função personalizada =GOLDPRICE("EUR", "gram") no Google Sheets com Apps Script e uma tabela do Power Query no Excel, ambas atualizadas automaticamente e com a chave de API fora das células.

As duas exigem um pouco de código. A MetalAPI retorna JSON, e nenhuma das duas planilhas tem uma fórmula que interprete JSON de uma URL e envie uma chave de API em um cabeçalho. O Apps Script e o Power Query fazem as duas coisas.

Você precisa de uma chave da MetalAPI: crie uma conta grátis, sem cartão de crédito, com 100 requisições por mês e atualização diária dos preços. Para o Excel, você também precisa de uma versão com Power Query (Obter e Transformar, ou Get & Transform), como o Excel para Microsoft 365 ou o Excel 2016 e posteriores no Windows. Os preços são tão recentes quanto o seu plano permite: diários no Free, a cada 30 minutos no Lite, a cada 10 minutos no Standard e até a cada 5 segundos no Enterprise.

Como obter preços do ouro ao vivo no Google Sheets

A configuração é um pequeno projeto do Apps Script vinculado à sua planilha: ele lê a chave de uma propriedade do script, busca os preços com UrlFetchApp, guarda-os em cache com CacheService e expõe funções personalizadas para as suas células. Um acionador baseado no tempo os mantém atualizados.

1. Abra a planilha e escolha Extensões → Apps Script (Extensions → Apps Script). Isso cria um projeto de script vinculado a esse arquivo.
2. No editor do Apps Script, abra Configurações do projeto (Project Settings, o ícone de engrenagem), role até Propriedades do script (Script Properties) e clique em Adicionar propriedade do script (Add script property). Digite METALAPI_KEY como propriedade, cole a sua chave como valor e clique em Salvar propriedades do script (Save script properties).
3. De volta ao Editor, substitua o conteúdo de Code.gs (Código.gs na interface em português) pelos dois blocos de código abaixo e salve.
4. Escolha refreshPrices no menu de funções e clique em Executar (Run). O Google pede uma única vez que você autorize o script a se conectar a um serviço externo e a editar a planilha.

Mantenha a sua chave de API fora das células

Não cole a chave em uma célula para montar a URL com uma fórmula. Uma chave em uma célula fica visível para todos que podem abrir a planilha, acompanha cada cópia e exportação e permanece no histórico de versões depois que você a apaga. Qualquer pessoa que a tenha pode gastar a sua cota.

As propriedades do script são um lugar melhor: elas não fazem parte da grade, então não aparecem em células, exportações nem no histórico de versões. Mas não são um cofre. Qualquer pessoa com acesso de edição à planilha pode abrir Extensões → Apps Script (Extensions → Apps Script) e lê-las. Portanto:

• Use uma chave separada por planilha, para poder revogá-la sem quebrar outras integrações. O guia de autenticação explica como criar e trocar chaves.
• Dê acesso de edição apenas a pessoas a quem você daria a chave. Leitores e comentaristas não conseguem abrir o editor de scripts, mas uma cópia da planilha inclui uma cópia do script vinculado. Para arquivos amplamente compartilhados, desative nas configurações de compartilhamento a opção de cópia para leitores e comentaristas.
• Envie a chave em um cabeçalho. O script usa X-API-Key em vez do parâmetro api_key, para que a chave não acabe em URLs registradas em log.
• Na dúvida, troque a chave: crie uma nova, atualize a propriedade do script e depois revogue a chave antiga no painel.

Uma função personalizada GOLDPRICE para o Google Sheets

Cole isto em Code.gs. METALPRICE cobre os quatro metais preciosos e GOLDPRICE é um atalho para o ouro. Uma requisição retorna os quatro metais, então ouro e prata na mesma moeda e unidade compartilham uma única resposta em cache.

// Preços da MetalAPI para o Google Sheets. A chave de API é lida da
// propriedade do script METALAPI_KEY (Configurações do projeto), nunca de uma célula.
const API = "https://metalapi.com/api/v1";
const SYMBOLS = ["XAU", "XAG", "XPT", "XPD"];
const CACHE_SECONDS = 3600; // 1 hora; o Apps Script permite até 21600

function fetchLatest_(base, unit) {
  const key = PropertiesService.getScriptProperties().getProperty("METALAPI_KEY");
  if (!key) throw new Error("Add the script property METALAPI_KEY first.");
  const url = API + "/latest?base=" + encodeURIComponent(base) +
    "&currencies=" + SYMBOLS.join(",") + "&unit=" + encodeURIComponent(unit);
  const res = UrlFetchApp.fetch(url, {
    headers: { "X-API-Key": key },
    muteHttpExceptions: true, // retorna as respostas de erro em vez de lançar uma exceção
  });
  let data;
  try {
    data = JSON.parse(res.getContentText());
  } catch (e) {
    throw new Error("MetalAPI: unexpected HTTP " + res.getResponseCode() + " response");
  }
  if (!data.success) {
    throw new Error("MetalAPI " + data.error.code + " (" + data.error.type + "): " + data.error.info);
  }
  return data;
}

function cachedLatest_(base, unit, refresh) {
  const cache = CacheService.getScriptCache();
  const cacheKey = ["latest", base, unit, refresh].join("|");
  const hit = cache.get(cacheKey);
  if (hit) return JSON.parse(hit);
  const data = fetchLatest_(base, unit);
  cache.put(cacheKey, JSON.stringify(data), CACHE_SECONDS);
  return data;
}

/**
 * Preço mais recente de um metal precioso, da MetalAPI.
 *
 * @param {string} symbol XAU (ouro), XAG (prata), XPT (platina) ou XPD (paládio).
 * @param {string} currency Código da moeda, como USD, EUR ou GBP. Padrão: USD.
 * @param {string} unit troy_oz (padrão), gram ou kilogram.
 * @param {any} refresh Célula opcional, como Prices!B1. Quando ela muda, os preços são buscados de novo.
 * @return O preço de uma unidade do metal na moeda.
 * @customfunction
 */
function METALPRICE(symbol, currency, unit, refresh) {
  const s = String(symbol || "XAU").trim().toUpperCase();
  const base = String(currency || "USD").trim().toUpperCase();
  const u = String(unit || "troy_oz").trim().toLowerCase();
  const data = cachedLatest_(base, u, String(refresh || ""));
  const price = data.rates[data.base + s];
  if (price === undefined) throw new Error("No " + s + " price in " + base + ".");
  return price;
}

/**
 * Preço mais recente do ouro, da MetalAPI; por exemplo, =GOLDPRICE("EUR", "gram").
 *
 * @param {string} currency Código da moeda, como USD, EUR ou GBP. Padrão: USD.
 * @param {string} unit troy_oz (padrão), gram ou kilogram.
 * @param {any} refresh Célula opcional, como Prices!B1. Quando ela muda, os preços são buscados de novo.
 * @return O preço do ouro na moeda, por unidade.
 * @customfunction
 */
function GOLDPRICE(currency, unit, refresh) {
  return METALPRICE("XAU", currency, unit, refresh);
}

Agora digite uma fórmula em qualquer célula. Em planilhas com a localidade Brasil, separe os argumentos com ponto e vírgula (;) em vez de vírgula:

Por dentro:

• @customfunction adiciona as funções ao preenchimento automático de fórmulas, com o comentário como texto de ajuda.
• muteHttpExceptions: true retorna as respostas de erro em vez de lançar uma exceção, então a célula mostra #ERROR! (#ERRO! na interface em português) com o código e a mensagem da MetalAPI ao passar o mouse, como 201 (invalid_base) para uma moeda desconhecida.
• CacheService guarda cada resposta por CACHE_SECONDS, no máximo seis horas. Células com a mesma moeda, unidade e valor de atualização a compartilham.
• Cada moeda e unidade fora do cache custa uma requisição, e cada célula com fórmula é uma chamada separada aos servidores do Google. Em planilhas com centenas de células de preço, referencie a aba Prices mostrada abaixo.

Erros de validação, como uma moeda desconhecida, são cobrados, então corrija logo as fórmulas quebradas. O guia de limites de requisições lista o que conta.

Atualize o preço do ouro no Google Sheets com um acionador baseado no tempo

O Google Sheets executa de novo uma função personalizada quando os argumentos dela mudam, e não de acordo com um relógio; a configuração de recálculo em Arquivo → Configurações → Cálculo (File → Settings → Calculation) só afeta funções como NOW e RAND (AGORA e ALEATÓRIO). Para atualizações agendadas, deixe um acionador baseado no tempo gravar os preços em uma aba. Adicione isto abaixo da parte 1:

/** Grava os preços mais recentes em uma aba chamada "Prices". Execute-a a partir de um acionador baseado no tempo. */
function refreshPrices() {
  const data = fetchLatest_("USD", "troy_oz");
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName("Prices") || ss.insertSheet("Prices");
  const rows = [
    ["Updated", new Date(data.timestamp * 1000)],
    ["Symbol", data.base + " per troy oz"],
  ];
  SYMBOLS.forEach(function (s) {
    rows.push([s, data.rates[data.base + s]]);
  });
  sheet.getRange(1, 1, rows.length, 2).setValues(rows);
}

/** Execute uma vez a partir do editor. Substitui qualquer agendamento existente de refreshPrices. */
function installTrigger() {
  ScriptApp.getProjectTriggers().forEach(function (t) {
    if (t.getHandlerFunction() === "refreshPrices") ScriptApp.deleteTrigger(t);
  });
  ScriptApp.newTrigger("refreshPrices").timeBased().everyHours(1).create();
}

Execute installTrigger uma vez a partir do editor, ou adicione o acionador manualmente em Acionadores (Triggers, o ícone de relógio) → Adicionar acionador (Add Trigger), com refreshPrices, Baseado no tempo (Time-driven) e um intervalo.

Cada execução custa uma requisição e grava o horário dos dados em Prices!B1 e uma linha por metal abaixo dele; Prices!B3 é o ouro em dólares americanos por onça troy. Referencie essas células diretamente ou passe Prices!B1 como argumento de atualização: =GOLDPRICE("EUR", "gram", Prices!B1) busca de novo sempre que o acionador grava um novo horário dos dados, uma vez por moeda e unidade, e nenhuma vez durante o fim de semana, quando o horário não muda. Para ter a aba Prices em outra moeda ou unidade, altere os argumentos de fetchLatest_ em refreshPrices.

Ajuste o intervalo ao seu plano; atualizar mais rápido do que os preços mudam só os repete:

As funções personalizadas com o argumento de atualização somam uma requisição por atualização para cada moeda e unidade. No Lite, um acionador de hora em hora mais GOLDPRICE("EUR", "gram", Prices!B1) pode chegar a cerca de 1.500 requisições por mês, acima das 1.000 do plano; use .everyHours(2) ou apenas a aba Prices. Os acionadores rodam perto do horário agendado, e não exatamente nele, e atHour usa o fuso horário do script.

Preço do ouro no Excel com Power Query

No Excel, o Power Query chama a API, interpreta o JSON e carrega uma tabela que é atualizada conforme um agendamento:

1. Na guia Dados (Data), escolha Obter Dados → De Outras Fontes → Consulta Nula (Get Data → From Other Sources → Blank Query).
2. No Editor do Power Query, escolha Página Inicial → Editor Avançado (Home → Advanced Editor), cole a consulta abaixo e clique em Concluído (Done).
3. Quando for perguntado como se conectar a https://metalapi.com/, clique em Editar Credenciais (Edit Credentials), escolha API Web (Web API), cole a sua chave em Chave (Key) e clique em Conectar (Connect).
4. Renomeie a consulta para GoldPrices e escolha Página Inicial → Fechar e Carregar (Home → Close & Load). O Excel a carrega em uma nova planilha, como uma tabela com o nome da consulta.

let
    BaseCurrency = "EUR",
    MassUnit = "gram",
    Symbols = {"XAU", "XAG", "XPT", "XPD"},
    Response = Json.Document(
        Web.Contents(
            "https://metalapi.com/api/v1/latest",
            [
                Query = [base = BaseCurrency, currencies = Text.Combine(Symbols, ","), unit = MassUnit],
                ApiKeyName = "api_key"
            ]
        )
    ),
    Updated = #datetime(1970, 1, 1, 0, 0, 0) + #duration(0, 0, 0, Response[timestamp]),
    Prices = Table.FromRecords(
        List.Transform(
            Symbols,
            (symbol) => [
                Symbol = symbol,
                Price = Record.Field(Response[rates], Response[base] & symbol),
                Currency = Response[base],
                Unit = MassUnit,
                #"Updated (UTC)" = Updated
            ]
        )
    ),
    Typed = Table.TransformColumnTypes(
        Prices,
        {{"Symbol", type text}, {"Price", type number}, {"Currency", type text},
         {"Unit", type text}, {"Updated (UTC)", type datetime}}
    )
in
    Typed

A consulta lê a chave prefixada com o base da resposta (EURXAU para EUR) e converte o timestamp Unix para UTC. Altere BaseCurrency e MassUnit conforme a sua necessidade.

ApiKeyName = "api_key" mantém a chave fora do arquivo: o Power Query a obtém da credencial API Web (Web API) e a anexa como o parâmetro de consulta api_key, uma das três formas como a MetalAPI aceita uma chave. A credencial fica nas configurações de fonte de dados do Excel no seu computador, e não na pasta de trabalho, então um colega que abrir o arquivo terá de informar a própria chave. Altere-a ou remova-a em Dados → Obter Dados → Configurações da Fonte de Dados (Data → Get Data → Data Source Settings).

Web.Contents também aceita Headers = [#"X-API-Key" = "..."], mas isso salva a chave dentro da pasta de trabalho. Use essa opção apenas em arquivos que nunca saem do seu computador.

Nas fórmulas, procure os preços na tabela: =XLOOKUP("XAU", GoldPrices[Symbol], GoldPrices[Price]) (PROCX no Excel em português, com ponto e vírgula entre os argumentos) retorna o ouro em euros por grama, e INDEX com MATCH (ÍNDICE e CORRESP) faz o mesmo em versões mais antigas.

Atualize os preços do ouro no Excel automaticamente

Uma tabela do Power Query não se atualiza sozinha. Abra Dados → Consultas e Conexões (Data → Queries & Connections), clique com o botão direito na consulta GoldPrices e escolha Propriedades (Properties). Em Controle de atualização (Refresh control):

• Atualizar a cada N minutos (Refresh every N minutes) executa a consulta de novo com um temporizador.
• Atualizar dados ao abrir o arquivo (Refresh data when opening the file) busca preços novos sempre que a pasta de trabalho é aberta.
• Habilitar atualização em segundo plano (Enable background refresh) mantém o Excel utilizável enquanto a consulta é executada.

Dados → Atualizar Tudo (Data → Refresh All, Ctrl+Alt+F5) atualiza sob demanda. O temporizador só funciona enquanto a pasta de trabalho está aberta.

Cada atualização é uma requisição. De hora em hora durante uma jornada de oito horas, são cerca de 180 por mês; a cada 10 minutos, cerca de 1.050. No Free, em que os preços são atualizados diariamente, atualizar ao abrir o arquivo é suficiente.

Preços históricos do ouro no Sheets e no Excel

Os preços de fechamento passados vêm de /timeframe: uma entrada por pregão entre start_date e end_date, até 30 dias por requisição no Free e 365 nos planos pagos. No Excel, uma segunda consulta gera uma coluna de datas e uma coluna por metal:

let
    Response = Json.Document(
        Web.Contents(
            "https://metalapi.com/api/v1/timeframe",
            [
                Query = [start_date = "2026-09-24", end_date = "2026-10-23", currencies = "XAU,XAG"],
                ApiKeyName = "api_key"
            ]
        )
    ),
    Days = Record.ToTable(Response[rates]),
    History = Table.FromRecords(
        List.Transform(
            Table.ToRecords(Days),
            (row) => [
                Date = Date.FromText(row[Name]),
                Gold = Record.FieldOrDefault(row[Value], Response[base] & "XAU", null),
                Silver = Record.FieldOrDefault(row[Value], Response[base] & "XAG", null)
            ]
        )
    ),
    Typed = Table.TransformColumnTypes(History, {{"Date", type date}, {"Gold", type number}, {"Silver", type number}})
in
    Typed

Fins de semana e feriados do mercado ficam de fora, então espere menos linhas do que dias corridos. No Apps Script, chame /timeframe com UrlFetchApp da mesma forma que fetchLatest_ chama /latest e grave todas as linhas com uma única chamada a setValues.

Os fechamentos passados nunca mudam, então carregue um intervalo uma vez e guarde-o. Preços históricos de ouro e prata via API aborda backfills longos, armazenamento e gráficos.

Próximos passos

Crie uma conta grátis, adicione a chave como propriedade do script ou como credencial de API Web, e você terá o preço do ouro na sua planilha em cerca de dez minutos. Os preços diários do plano Free atendem a uma tabela de preços diária ou a uma planilha de carteira; para preços mais recentes ou mais atualizações, compare os planos na página de preços. A documentação da API lista todos os endpoints que você pode chamar da mesma forma, incluindo /convert e /carat, para preços do ouro por quilate nos planos pagos.

Perguntas frequentes

Posso importar os preços do ouro com IMPORTDATA ou IMPORTXML?

Não da MetalAPI. Essas funções (IMPORTARDADOS e IMPORTXML em português) leem CSV, TSV, XML ou HTML, enquanto a API retorna JSON, e não conseguem enviar um cabeçalho, então a chave ficaria na fórmula, à vista de qualquer leitor.

Com que frequência o preço do ouro é atualizado na minha planilha?

Com a frequência com que você o atualiza e que o seu plano permite: diariamente no Free, a cada 30 minutos no Lite, a cada 10 minutos no Standard e mais rápido nos planos superiores. Das 17h de sexta às 17h de domingo, horário de Nova York, o mercado à vista fica fechado e o preço permanece no fechamento de sexta-feira.

Quantas requisições à API a minha planilha vai usar?

Uma por atualização da aba Prices ou da tabela do Power Query, mais uma por moeda e unidade quando as funções personalizadas buscam preços novos. Um acionador de hora em hora gera cerca de 744 requisições por mês, e um diário, cerca de 31. /usage informa o seu consumo sem contar para a cota.

É seguro compartilhar uma planilha que puxa os preços do ouro?

Sim, se a chave ficar fora das células: em uma propriedade do script no Google Sheets, com acesso de edição apenas para pessoas a quem você confiaria a chave, e na credencial de API Web no Excel. Use uma chave separada por arquivo compartilhado, para poder revogá-la isoladamente.

Posso obter o preço do ouro por grama ou na minha moeda local?

Sim. Passe um código de moeda e gram ou kilogram, como em =GOLDPRICE("INR", "gram"), ou altere BaseCurrency e MassUnit na consulta do Power Query. A API converte os dois a partir do mesmo instantâneo.