Exporte dados do Apple Search Ads

A Hermoso se conecta ao Apple Search Ads e o expõe como ferramentas que o seu agente pode chamar: Claude, ChatGPT, Cursor, Codex, Cline, a CLI ou HTTP simples. apple_ads_report puxa o desempenho de campanha, grupo de anúncios, anúncio, palavra-chave e termo de pesquisa, e as linhas voltam como dados, e não como um CSV para baixar e depois levar a algum lugar.

O conector do Apple Search Ads

A Apple não publica um fluxo OAuth para a API de anúncios, então conectar é uma troca de chaves, não um botão: a Hermoso gera a chave de assinatura, você cola a metade pública no Apple Ads e devolve três ids. O guia de configuração do Apple Search Ads mostra o caminho, incluindo o campo Public Key que a maioria das pessoas não encontra. Uma única conexão atende o app web, o servidor MCP, a CLI e a API REST, então a mesma exportação funciona a partir do Claude, do ChatGPT ou do Cursor: conecte o Apple Search Ads ao Claude ou ao ChatGPT uma vez, depois peça.

O relatório é só uma parte. A mesma conexão monta e administra a conta: campanhas, grupos de anúncios, palavras-chave e negativas, pedidos de orçamento, segmentação, sugestões de palavras-chave e histórico de alterações. A página do canal Apple Ads lista todas as ferramentas.

O que o relatório contém

Uma chamada, cinco níveis. apple_ads_report gera o relatório no nível de campanha, grupo de anúncios, anúncio, palavra-chave ou termo de pesquisa, e cada linha traz as métricas que o próprio painel da Apple mostra: impressões, toques, instalações, gasto, taxa de toque, custo por toque e custo por aquisição. Você pode pedir totais ou uma série com granularidade horária, diária, semanal ou mensal. As linhas voltam ordenadas por gasto, do maior para o menor, até 5.000 por página, com uma linha de totais gerais se você pedir. Relatórios da App Store também podem incluir entidades sem entrega, então uma palavra-chave pausada aparece como zero, e não como uma linha que some.

Duas regras que a Apple impõe, e que a ferramenta explica em vez de falhar em silêncio: um relatório abaixo do nível de campanha precisa de um id de campanha (só um relatório no nível de campanha cobre a conta inteira), e relatórios de termos de pesquisa rodam no fuso horário da própria organização, nunca em UTC. Os anúncios no Apple Maps também estão cobertos: um relatório de marcas de negócios sai da mesma ferramenta com um parâmetro trocado.

Conecte o Apple Search Ads ao Google Sheets

Este é o único destino para o qual a própria Hermoso escreve. Conecte o Google Drive ao lado do Apple Ads (uma única autorização do Google cobre Drive, Sheets e Docs) e então peça: "Puxe o desempenho do Apple Search Ads por palavra-chave dos últimos 30 dias e coloque em uma planilha nova chamada Apple Ads." O agente chama apple_ads_report, depois create_sheet, e devolve o link. Na semana seguinte, o mesmo pedido com "acrescente" adiciona linhas com append_to_sheet, em vez de começar do zero.

O escopo do Drive que a Hermoso pede ao Google é drive.file, que alcança apenas os arquivos que ela criou e os que você escolher, nunca o seu Drive inteiro. O passo a passo completo, incluindo substituir uma aba no lugar e formatá-la, está em Conecte o Apple Search Ads ao Google Sheets.

Exporte o Apple Search Ads para o Looker Studio

A Hermoso não tem conector nativo para o Looker Studio, e preferimos dizer isso a sugerir que existe um. Ela não precisa de um: o Looker Studio lê o Google Sheets com o conector integrado dele, então a planilha acima é a ponte.

1. Peça ao agente que grave o relatório em uma aba. Granularidade diária, uma linha por palavra-chave por dia, uma linha de cabeçalho e uma coluna de data. Peça para a coluna de data ser formatada como data (format_sheet faz isso), para que o Looker Studio a leia como data.
2. Adicione a planilha como fonte de dados. No Looker Studio, crie uma fonte de dados, escolha Google Sheets, selecione a planilha e aquela aba, e mantenha "Usar a primeira linha como cabeçalhos" ativado.
3. Monte o relatório uma vez. Gasto por dia, custo por aquisição por palavra-chave, instalações por campanha: o que você refaria toda segunda-feira em uma planilha.
4. Continue acrescentando. Toda semana o agente acrescenta linhas novas à mesma aba, e o painel as pega na próxima atualização de dados. Mantenha os nomes das colunas iguais entre as execuções, porque o Looker Studio mapeia os campos pelo cabeçalho.

A mesma planilha funciona para o Power BI e o Tableau, que também têm conectores próprios para o Google Sheets.

Exporte o Apple Search Ads para JSON

Se você quer as linhas brutas em vez de uma planilha, há três formas de obtê-las, todas usando a mesma conexão.

A API REST. Toda ferramenta da Hermoso pode ser chamada em POST /v1/tools/{name} com uma chave de API que você cria no app, na aba MCP & CLI. O corpo da requisição são os argumentos da ferramenta, e o campo data da resposta é o resultado estruturado, com as linhas em data.rows:

curl -sX POST https://app.hermoso.ai/v1/tools/apple_ads_report \
  -H "Authorization: Bearer hmk_..." -H 'content-type: application/json' \
  -d '{"level":"keyword","campaignId":"1234567890","startTime":"2026-09-01","endTime":"2026-09-07","granularity":"DAILY"}' \
  | jq '.data.rows' > apple-search-ads.json

A CLI. npx -y hermoso call apple_ads_report --json '{...}' --structured imprime o mesmo resultado estruturado em JSON, pronto para redirecionar para um arquivo ou passar para outro script.

O seu agente. Em qualquer chat, peça as linhas em JSON e elas vêm na resposta, já no formato que você pediu.

Para relatórios longos, limit aceita até 5.000 linhas por página e offset avança para a próxima; o campo hasMore do resultado diz se existe outra página. Ler um relatório não gasta créditos. A referência completa da API está na documentação para desenvolvedores.

Outros destinos

"Direto" quer dizer que a Hermoso escreve. Todo o resto é um passo que uma ferramenta que você já usa faz sozinha.

• Google Sheets, Google Docs, Google Drive, OneDrive: direto.
• Looker Studio, Power BI, Tableau: pela planilha, cada um com o seu próprio conector do Google Sheets.
• BigQuery: pela planilha, ou pelo seu próprio agente. O BigQuery consegue consultar uma planilha do Google como tabela externa. Se o seu agente roda em um lugar com um cliente do BigQuery e as credenciais do seu projeto, ele pode inserir direto em uma tabela as linhas que a Hermoso devolve.
• Excel: pela planilha ou por um arquivo. Baixe a planilha como .xlsx, ou peça ao agente que deixe um arquivo no Google Drive ou no OneDrive.
• PostgreSQL, Redshift, Snowflake ou qualquer data warehouse: pelo seu próprio agente ou pela API. A Hermoso devolve JSON; quem guarda as credenciais do seu banco de dados é quem grava. A Hermoso não guarda credenciais de warehouse.

Automatizando a exportação semanal

O prompt é a automação. Algo como "Toda segunda-feira, puxe o desempenho do Apple Search Ads da semana passada por palavra-chave de todas as campanhas, acrescente na planilha do Apple Ads e me diga quais palavras-chave mais mudaram no custo por aquisição" já é um trabalho completo. Rode em uma frequência com o agendamento que o seu cliente já tem (tarefas agendadas no Claude ou no ChatGPT, ou um cron chamando a CLI da Hermoso ou a API) e a planilha, e todos os painéis que a leem, continuam atualizados.

Como a mesma conexão também edita a conta, o relatório e a correção ficam no mesmo lugar: o agente que percebe que o custo por aquisição de uma palavra-chave dobrou pode pausá-la ou adicionar uma negativa na mesma conversa.

Perguntas frequentes

Como exporto dados do Apple Search Ads?

Conecte o Apple Ads à Hermoso uma vez, depois peça ao seu agente o relatório que você quer, por exemplo o desempenho por palavra-chave da semana passada. A ferramenta apple_ads_report puxa os dados da API de relatórios da Apple e o agente os grava em uma planilha do Google, entrega JSON para você, ou os dois.

Posso conectar o Apple Search Ads ao Google Sheets?

Sim. Conecte o Apple Ads e o Google Drive na Hermoso, depois peça ao agente que coloque o relatório em uma planilha. Ele cria a planilha com create_sheet, ou acrescenta linhas a uma existente com append_to_sheet, e pode repetir isso toda semana.

Posso exportar o Apple Search Ads para o Looker Studio?

Sim, pelo Google Sheets. A Hermoso não tem conector nativo para o Looker Studio. O agente grava o relatório em uma planilha, você adiciona essa planilha como fonte de dados do Google Sheets no Looker Studio uma vez, e cada acréscimo aparece na próxima atualização do painel.

Como exporto dados do Apple Search Ads para JSON?

Chame POST /v1/tools/apple_ads_report na API da Hermoso com uma chave de API e leia data.rows da resposta, ou rode hermoso call apple_ads_report --json '{...}' --structured pela CLI. Os dois devolvem as mesmas linhas em JSON.

Existe uma API de relatórios do Apple Search Ads?

Existe, e a Hermoso é construída sobre ela. apple_ads_report cobre o desempenho de campanha, grupo de anúncios, anúncio, palavra-chave e termo de pesquisa, e as outras ferramentas do Apple Ads montam e administram a conta.

Consigo relatórios de termos de pesquisa do Apple Search Ads?

Sim. Peça o nível de termo de pesquisa e informe a campanha. A Apple só entrega termos de pesquisa por campanha, no fuso horário da própria organização.

Quantas linhas um relatório pode ter?

Até 5.000 por página, ordenadas por gasto do maior para o menor, com um aviso dizendo ao agente se existem mais páginas. Um relatório semanal de palavras-chave para a maioria das contas cabe em uma página.

Isso cobre os anúncios no Apple Maps?

Sim. Relatórios de campanhas de marcas de negócios saem da mesma ferramenta, com o tipo de objeto promovido definido como Apple Maps em vez de App Store.

Preciso de um desenvolvedor para configurar isso?

Não. Conecte o Apple Ads uma vez no app, depois peça ao seu agente em linguagem simples: puxe a semana passada por palavra-chave e coloque em uma planilha. A API e a CLI estão lá se você quiser automatizar por script.