Esportare i dati da Apple Search Ads

Hermoso si collega ad Apple Search Ads e lo espone come strumenti che il tuo agente può richiamare: Claude, ChatGPT, Cursor, Codex, Cline, la CLI o HTTP semplice. apple_ads_report estrae le prestazioni di campagne, gruppi di annunci, annunci, parole chiave e termini di ricerca, e le righe tornano come dati, non come un file CSV da scaricare e poi portare da qualche parte.

Il connettore Apple Search Ads

Apple non pubblica un flusso OAuth per la sua API pubblicitaria, quindi il collegamento è uno scambio di chiavi e non un semplice pulsante: Hermoso genera la chiave di firma, tu incolli la sua metà pubblica in Apple Ads e incolli indietro tre identificativi. La guida alla configurazione di Apple Search Ads ti accompagna passo passo, incluso il campo Public Key che la maggior parte delle persone non trova. Una sola connessione serve poi l'app web, il server MCP, la CLI e l'API REST, quindi lo stesso export funziona da Claude, ChatGPT o Cursor: collega Apple Search Ads a Claude o a ChatGPT una volta, poi chiedi.

Il reporting è solo una parte. La stessa connessione costruisce e gestisce l'account: campagne, gruppi di annunci, parole chiave e negative, ordini di budget, targeting, suggerimenti di parole chiave e storico delle modifiche. La pagina del canale Apple Ads elenca ogni strumento.

Cosa contiene il report

Una chiamata, cinque livelli. apple_ads_report riporta a livello di campagna, gruppo di annunci, annuncio, parola chiave o termine di ricerca, e ogni riga porta le metriche che mostra la dashboard di Apple: impression, tap, installazioni, spesa, tasso di tap, costo per tap e costo per acquisizione. Chiedi i totali oppure una serie a granularità oraria, giornaliera, settimanale o mensile. Le righe arrivano ordinate per spesa, dalla più alta, fino a 5.000 per pagina, con una riga di totali generali se la richiedi. I report App Store possono includere anche entità senza consegna, quindi una parola chiave in pausa compare come zero invece di mancare del tutto.

Due regole che Apple impone, e che lo strumento spiega invece di fallire in silenzio: un report sotto il livello di campagna richiede un id di campagna (solo un report a livello di campagna può coprire l'intero account), e i report sui termini di ricerca girano nel fuso orario della tua organizzazione, mai in UTC. Sono coperti anche gli annunci su Apple Maps: un report per i brand aziendali arriva dallo stesso strumento con un solo parametro cambiato.

Collegare Apple Search Ads a Google Sheets

È l'unica destinazione in cui Hermoso scrive direttamente. Collega Google Drive insieme ad Apple Ads (una sola autorizzazione Google copre Drive, Sheets e Docs), poi chiedi: "Estrai le prestazioni di Apple Search Ads per parola chiave degli ultimi 30 giorni e mettile in un nuovo foglio chiamato Apple Ads." L'agente chiama apple_ads_report, poi create_sheet, e ti restituisce il link. La settimana dopo, la stessa richiesta con "aggiungi" aggiunge le righe con append_to_sheet invece di ricominciare da capo.

Hermoso chiede a Google lo scope drive.file, che raggiunge solo i file che ha creato e quelli che scegli tu, mai tutto il tuo Drive. La procedura completa, incluso come sostituire una scheda sul posto e come formattarla, è in Collegare Apple Search Ads a Google Sheets.

Esportare Apple Search Ads in Looker Studio

Hermoso non ha un connettore nativo per Looker Studio, e preferiamo dirlo piuttosto che lasciar credere il contrario. Non ne ha bisogno: Looker Studio legge i Google Sheet con il suo connettore integrato, quindi il foglio qui sopra fa da ponte.

1. Fai scrivere il report in una scheda. Granularità giornaliera, una riga per parola chiave per giorno, una riga di intestazione e una colonna data. Chiedi che la colonna data sia formattata come data (format_sheet lo fa), così Looker Studio la legge come tale.
2. Aggiungi il foglio come origine dati. In Looker Studio crea un'origine dati, scegli Google Sheets, seleziona il foglio di calcolo e quella scheda, e lascia attiva l'opzione "Usa la prima riga come intestazioni".
3. Costruisci il report una volta. Spesa per giorno, costo per acquisizione per parola chiave, installazioni per campagna: tutto ciò che altrimenti ricostruiresti in un foglio di calcolo ogni lunedì.
4. Continua ad aggiungere dati. Ogni settimana l'agente aggiunge le nuove righe alla stessa scheda, e la dashboard le recupera al successivo aggiornamento dei dati. Mantieni gli stessi nomi di colonna tra un'esecuzione e l'altra, perché Looker Studio associa i campi per intestazione.

Lo stesso foglio funziona per Power BI e Tableau, che hanno ciascuno un proprio connettore per Google Sheets.

Esportare Apple Search Ads in JSON

Se vuoi le righe grezze invece di un foglio di calcolo, ci sono tre modi per ottenerle, tutti con la stessa connessione.

L'API REST. Ogni strumento Hermoso è richiamabile su POST /v1/tools/{name} con una chiave API che crei nell'app nella scheda MCP & CLI. Il corpo della richiesta sono gli argomenti dello strumento, e il campo data della risposta è il risultato strutturato, con le righe in 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

La CLI. npx -y hermoso call apple_ads_report --json '{...}' --structured stampa lo stesso risultato strutturato in JSON, pronto da reindirizzare in un file o da passare a un altro script.

Il tuo agente. In qualsiasi chat chiedi le righe in JSON e le ottieni nella risposta, già formattate come le hai chieste.

Per i report lunghi, limit accetta fino a 5.000 righe per pagina e offset passa alla pagina successiva; il campo hasMore del risultato indica se esiste un'altra pagina. Leggere un report non consuma crediti. La documentazione completa dell'API è nella documentazione per sviluppatori.

Altre destinazioni

"Diretto" significa che è Hermoso a scrivere. Tutto il resto richiede un solo passaggio che uno strumento che già usi fa da sé.

• Google Sheets, Google Docs, Google Drive, OneDrive: diretto.
• Looker Studio, Power BI, Tableau: tramite il foglio, ciascuno con il proprio connettore Google Sheets.
• BigQuery: tramite il foglio, o tramite il tuo agente. BigQuery può interrogare un Google Sheet come tabella esterna. Se il tuo agente gira dove c'è un client BigQuery e le tue credenziali di progetto, può inserire direttamente in una tabella le righe che Hermoso restituisce.
• Excel: tramite il foglio o un file. Scarica il foglio in .xlsx, oppure fai lasciare all'agente un file in Google Drive o OneDrive.
• PostgreSQL, Redshift, Snowflake o qualsiasi data warehouse: tramite il tuo agente o l'API. Hermoso restituisce JSON; ciò che custodisce le credenziali del tuo database le scrive. Hermoso non custodisce credenziali di warehouse.

Automatizzare l'esportazione settimanale

Il prompt è l'automazione. Una frase come "Ogni lunedì estrai le prestazioni di Apple Search Ads della settimana scorsa per parola chiave e per ogni campagna, aggiungile al foglio Apple Ads e dimmi quali parole chiave si sono mosse di più sul costo per acquisizione" è un lavoro completo. Eseguilo a una cadenza con la pianificazione che il tuo client già offre (attività pianificate in Claude o ChatGPT, oppure un cron job che richiama la CLI o l'API di Hermoso) e il foglio, insieme a ogni dashboard che lo legge, resta aggiornato.

Poiché la stessa connessione modifica anche l'account, il report e la correzione vivono nello stesso posto: l'agente che nota che il costo per acquisizione di una parola chiave è raddoppiato può metterla in pausa o aggiungere una negativa nella stessa conversazione.

Domande frequenti

Come esporto i dati da Apple Search Ads?

Collega Apple Ads a Hermoso una volta, poi chiedi al tuo agente il report che ti serve, per esempio le prestazioni per parola chiave della settimana scorsa. Lo strumento apple_ads_report lo estrae dall'API di reporting di Apple e l'agente lo scrive in un Google Sheet, ti consegna il JSON, o entrambi.

Posso collegare Apple Search Ads a Google Sheets?

Sì. Collega Apple Ads e Google Drive in Hermoso, poi chiedi all'agente di mettere il report in un foglio. Crea il foglio con create_sheet, oppure aggiunge righe a uno esistente con append_to_sheet, e può ripetere l'operazione ogni settimana.

Posso esportare Apple Search Ads in Looker Studio?

Sì, tramite Google Sheets. Hermoso non ha un connettore nativo per Looker Studio. L'agente scrive il report in un foglio, tu aggiungi quel foglio come origine dati Google Sheets in Looker Studio una sola volta, e ogni aggiunta compare al successivo aggiornamento della dashboard.

Come esporto i dati di Apple Search Ads in JSON?

Richiama POST /v1/tools/apple_ads_report sull'API di Hermoso con una chiave API e leggi data.rows dalla risposta, oppure esegui hermoso call apple_ads_report --json '{...}' --structured dalla CLI. Entrambi restituiscono le stesse righe in JSON.

Esiste un'API di reporting per Apple Search Ads?

Sì, ed è su quella che è costruito Hermoso. apple_ads_report copre le prestazioni di campagne, gruppi di annunci, annunci, parole chiave e termini di ricerca, e gli altri strumenti Apple Ads costruiscono e gestiscono l'account.

Posso ottenere i report sui termini di ricerca di Apple Search Ads?

Sì. Chiedi il livello dei termini di ricerca e indica la campagna. Apple fornisce i termini di ricerca solo per campagna, nel fuso orario dell'organizzazione.

Quante righe può restituire un singolo report?

Fino a 5.000 per pagina, ordinate per spesa dalla più alta alla più bassa, con un segnale che indica all'agente se esistono altre pagine. Un report settimanale per parola chiave della maggior parte degli account sta in una sola pagina.

Questo copre gli annunci su Apple Maps?

Sì. I report per le campagne di brand aziendali arrivano dallo stesso strumento, con il tipo di oggetto promosso impostato su Apple Maps invece che sull'App Store.

Serve uno sviluppatore per configurarlo?

No. Collega Apple Ads una volta nell'app, poi chiedi al tuo agente in linguaggio semplice: estrai la settimana scorsa per parola chiave e mettila in un foglio. L'API e la CLI ci sono se vuoi scriptarlo.