Search Console: API i BigQuery a gran escala

A gran escala, el contracte de dades pesa més que el quadre de comandament. La interfície, l’API Search Analytics i BigQuery difereixen en cobertura, històric i operació. Una font mal triada deixa l’anàlisi incompleta encara que l’SQL sigui correcte.

Aquesta guia pressuposa una propietat verificada i el domini de les mètriques bàsiques. La guia pràctica de Search Console cobreix la configuració; aquí tractem la recuperació fiable a escala.

Tria la via més simple que respongui la pregunta

Les tres vies d’accés se superposen, però resolen feines diferents.

Comença per la interfície quan calgui inspecció humana, com ara comprovar una caiguda per dispositiu o provar filtres. La taula de rendiment mostra com a màxim 1.000 files, mentre que els totals poden incloure files que no hi apareixen (explicació de Google sobre les dades de Search Console). Serveix per investigar, però no és una base de dades completa.

Tria l’exportació massiva quan la cobertura i la continuïtat pesin més que la comoditat. Search Console la descriu com una exportació diària de dades de rendiment a BigQuery i indica que proporciona totes les dades de rendiment disponibles excepte les consultes anonimitzades. No revela el text de les consultes protegides (descripció de l’exportació massiva de Search Console). Sí que ofereix un conjunt de treball molt més complet que les files principals de la interfície o de l’API, a més d’emmagatzematge sota control de l’organització.

El magatzem no és sempre més madur. Un lloc petit pot funcionar amb un script i una taula; una xarxa de propietats amb encreuaments i històric superarà els fulls de càlcul. L’escala depèn de la feina repetida.

Interpreta els números com a observacions agregades

Search Console no ofereix un registre d’esdeveniments en brut. Cada fila agrega dimensions com ara data, consulta, pàgina, país, dispositiu, tipus de cerca i aparició a la cerca (documentació sobre les dades de Search Console). Quan canvien les dimensions, canvia la granularitat del resultat. Per tant, sumar conjunts recuperats de manera independent pot comptar dues vegades el mateix rendiment.

Les dates demanen una atenció especial. Search Console etiqueta el rendiment diari segons l’hora del Pacífic i l’API espera que l’interval de dates segueixi el mateix fus horari. Google indica que les dades recopilades acostumen a estar disponibles al cap de dos o tres dies, tot i que publica actualitzacions a intervals (documentació sobre les dades de Search Console). El paràmetre dataState de l’API pot incloure dades recents i preliminars quan pren el valor all; si s’omet, la resposta conté dades finalitzades (referència de la consulta Search Analytics). Una canalització diària ha de registrar si ha acceptat files preliminars i si després les ha substituït.

La protecció de la privacitat explica una altra discrepància aparent. Les consultes poc freqüents o sensibles es poden anonimitzar. Poden contribuir als totals del gràfic encara que el text no aparegui a la taula de consultes. Aplicar un filtre de consulta també pot alterar el càlcul d’aquests totals. En l’exportació massiva, is_anonymized_query identifica les files anonimitzades i el valor de la consulta queda buit. Això permet conservar-ne els clics i les impressions agregats sense atribuir-los a termes que no coneixem (referència de les taules de l’exportació).

Etiqueta les consultes identificades com a subtotal. Utilitza propietat per als totals i URL per al detall, sense barrejar-los.

La posició mitjana és ponderada; no és la mitjana aritmètica de mitjanes de fila. A l’exportació massiva, la posició de propietat es calcula amb SUM(sum_top_position) / SUM(impressions) + 1; per a URL, s’aplica la mateixa fórmula amb sum_position. La referència de taules de Google defineix tots dos camps com a sumes amb base zero (referència de les taules de l’exportació). Si tornes a fer la mitjana de posicions ja agregades, dones el mateix pes a les files amb moltes impressions i a les que en tenen poques, i el resultat és incorrecte.

Pagina l’API sense confondre paginació i cobertura

L’endpoint de Search Analytics accepta un interval de dates, dimensions, filtres, tipus de cerca, tipus d’agregació i estat de les dades. Una resposta pot contenir com a màxim 25.000 files; startRow és el desplaçament amb base zero que s’utilitza per paginar (referència de la consulta Search Analytics). Una extracció robusta demana la mida màxima de pàgina, incrementa el desplaçament amb el nombre de files rebudes i s’atura quan la resposta és buida o més curta que la mida de pàgina.

Aquest bucle no converteix la font en completa. Google documenta un altre màxim: 50.000 files diàries per tipus de cerca, ordenades per clics, per a les dades de Search Analytics. L’agrupació detallada per pàgina o consulta pot perdre dades fins i tot dins d’aquest límit (guia per obtenir dades de rendiment). La paginació recupera les files principals disponibles. No pot recuperar les que el servei no exposa.

Un patró d’extracció raonable és aquest:

1. Consulta un dia i un tipus de cerca cada vegada quan la cobertura de files sigui important.
2. Desa amb el resultat el cos exacte de la petició, la propietat, l’hora d’extracció i dataState.
3. Pagina amb rowLimit: 25000 i incrementa startRow.
4. Atura’t davant d’una pàgina curta, però marca com a potencialment truncat qualsevol dia que arribi a 50.000 files.
5. Torna a obtenir les dates preliminars quan siguin definitives. Substitueix-les de manera idempotent.
6. Separa els totals de propietat del detall de pàgina i consulta.

Search Analytics aplica quotes de càrrega a curt termini i diàries, però Google no en publica la capacitat numèrica. Els intervals amplis i l’agrupació o filtratge simultani per pàgina i consulta consumeixen més càrrega. També hi ha quotes de peticions: 1.200 consultes per minut i lloc, 1.200 per minut i usuari, i 40.000 per minut més 30.000.000 al dia per projecte (límits de l’API de Search Console). No dissenyis el sistema al voltant de la quota nominal del projecte. Una sola consulta costosa pot topar amb un límit de càrrega molt abans que el recompte de peticions sigui el problema.

Segmenta dates, desa períodes definitius i evita recuperar mesos immutables. Aplica esperes exponencials limitades, registra fallades i separa horaris en projectes compartits. Mantén OAuth en només lectura si no cal més.

L’API permet recuperar dades històriques anteriors, mentre que l’exportació massiva només conserva dades a partir de l’activació. Google indica que la primera exportació conté les dades del dia d’inici i recomana l’API o els informes per a les dates anteriors (guia de configuració de l’exportació massiva). Desa les dades històriques de l’API amb la font i els indicadors de cobertura. No les barregis amb les files de l’exportació massiva com si totes dues fonts tinguessin la mateixa cobertura.

Decideix propietat i ubicació abans d’activar l’exportació

L’exportació massiva necessita un projecte de Google Cloud amb la facturació activa, l’API de BigQuery i l’API de BigQuery Storage. El compte de servei [email protected] ha de tenir els rols BigQuery Job User i BigQuery Data Editor en aquest projecte. La persona que inicia l’exportació ha de ser propietària de la propietat de Search Console (passos de configuració de Google).

L’abast d’aquests rols exigeix una persona responsable i una revisió periòdica d’IAM. Separa el compte de servei que escriu les dades de Search Console dels comptes dels analistes. Dona a aquests comptes accés al conjunt de dades o a les vistes aprovades que necessitin, en lloc de compartir accés de propietari del projecte. Per executar una consulta també cal bigquery.jobs.create al projecte que l’executa i bigquery.tables.getData a les taules i vistes consultades (jerarquia de recursos de BigQuery).

Tria la ubicació del conjunt de dades abans d’activar l’exportació. Search Console crea el conjunt durant la primera exportació i no permet canviar-ne la ubicació de manera nativa després (guia de configuració de l’exportació massiva). En una consulta ordinària, BigQuery retorna un error si la ubicació del treball no coincideix amb la de tots els conjunts de dades llegits o escrits. Una regió i una multiregió no coincideixen encara que la primera sigui dins de la segona; EU i europe-west1, per exemple, no són intercanviables (ubicacions de BigQuery).

Les consultes globals són l’excepció, però continuen en fase de vista prèvia. Per utilitzar-les, cal habilitar l’execució a la regió principal i l’accés a cada regió remota, a més de concedir bigquery.jobs.createGlobalQuery (documentació de consultes globals). BigQuery copia temporalment les dades remotes a la regió principal; el cost inclou el còmput remot i final, la transferència entre ubicacions i 24 hores d’emmagatzematge temporal. També tenen més latència i no funcionen amb endpoints regionals (límits i preus de les consultes globals).

Fora d’aquesta excepció, un treball només utilitza una reserva si la seva ubicació coincideix amb la de la reserva. Si no n’hi ha cap de compatible, s’executa sota demanda (ubicacions de BigQuery). La política de residència, els encreuaments previstos i les eines posteriors han de guiar la decisió sobre la ubicació abans d’activar l’exportació.

Abans d’activar-ho, comprova l’ID del projecte, no el número, i tria un nom de conjunt de dades que comenci per searchconsole i sigui únic si diverses propietats comparteixen projecte (guia de configuració de l’exportació massiva). Revisa també:

• qui assumeix la facturació i les alertes de pressupost;
• que les API de BigQuery i BigQuery Storage estiguin habilitades;
• el principal exportador de Search Console i els dos rols necessaris;
• una ubicació compatible amb la resta de dades analítiques de l’organització;
• accés de propietari de la propietat per a qui activi l’exportació;
• qui monitorarà el primer lliurament i les incidències.

La primera exportació pot trigar fins a 48 hores després d’una configuració correcta i no recupera dades anteriors. Quan les taules ja existeixen, Search Console desaconsella canviar-ne l’esquema i recomana un mínim de 14 dies si configures la caducitat de particions, perquè un termini més curt pot impedir noves escriptures (guia de configuració de l’exportació massiva). Si vols conservar l’històric, no apliquis una caducitat agressiva.

Entén el model de tres taules abans d’escriure SQL

El conjunt de dades predeterminat searchconsole conté tres taules (referència de les taules de l’exportació):

• searchdata_site_impression desa el rendiment agregat a escala de propietat;
• searchdata_url_impression desglossa el rendiment per URL de destinació;
• ExportLog registra les escriptures correctes a les dues taules de rendiment.

Les dues taules de rendiment estan particionades per data_date. Entre les dimensions hi ha la propietat, la consulta, el país, el tipus de cerca i el dispositiu; la taula d’URL també inclou url i els indicadors d’aparició a la cerca. ExportLog conté la data de les dades, l’espai de noms de destinació, l’hora de publicació i un epoch_version que augmenta si Search Console revisa una data més endavant (referència de les taules de l’exportació).

Les files no tenen garantida la consolidació per data ni per cap altra clau. Qualsevol consulta analítica ha d’agregar clics, impressions i sumes de posició, encara que les dimensions seleccionades semblin úniques. Google ho exigeix explícitament a les directrius de consulta de l’exportació massiva.

Aquest patró parametritzat calcula el rendiment per URL de les consultes web identificades i, alhora, poda la partició de data:

SELECT
  data_date,
  url,
  query,
  SUM(clicks) AS clicks,
  SUM(impressions) AS impressions,
  SAFE_DIVIDE(SUM(clicks), SUM(impressions)) AS ctr,
  SAFE_DIVIDE(SUM(sum_position), SUM(impressions)) + 1 AS avg_position
FROM `your-project.searchconsole.searchdata_url_impression`
WHERE data_date BETWEEN @start_date AND @end_date
  AND search_type = 'WEB'
  AND NOT is_anonymized_query
GROUP BY data_date, url, query;

El filtre de partició ha d’estar a la consulta base, no en una capa posterior del quadre de comandament que primer llegeixi la taula sencera. Selecciona només les columnes necessàries. BigQuery documenta que la poda de particions redueix les dades escanejades, mentre que SELECT * i les columnes innecessàries n’augmenten el processament (pràctiques de càlcul de BigQuery). LIMIT canvia el nombre de files retornades, però en una taula no agrupada no redueix els bytes llegits.

Crea una capa comuna: separa totals diaris del detall de consulta i URL, indica la cobertura i conserva les taules originals.

Aplica els controls de cost abans d’executar consultes

BigQuery ofereix anàlisi sota demanda, facturada pels bytes processats, i anàlisi per capacitat, facturada mitjançant capacitat reservada. L’emmagatzematge es cobra a part. El model i el preu adequats depenen de la ubicació, la càrrega i les condicions del compte; una estimació universal per consulta seria enganyosa. Contrasta la pàgina oficial de preus de BigQuery amb la regió i el model de facturació triats.

El control de costos comença abans d’executar res:

• previsualitza les taules sense llançar cap consulta quan n’exploris l’estructura;
• exigeix paràmetres data_date acotats a les consultes de producció;
• selecciona columnes pel nom en comptes d’utilitzar SELECT *;
• fes una execució de prova o utilitza el validador de consultes de la consola per estimar els bytes;
• fixa maximum bytes billed als treballs sota demanda perquè falli una consulta que processi més dades de les previstes;
• materialitza les vistes diàries o mensuals reutilitzades, en lloc de tornar a escanejar les dades brutes per a cada panell;
• etiqueta els treballs programats i revisa els bytes processats, les fallades i l’ús de slots per responsable.

La guia de costos de Google confirma que les execucions de prova estimen els bytes i que un límit màxim de bytes rebutja la consulta abans que generi una despesa quan l’estimació el supera. També adverteix que LIMIT no controla el cost en taules no agrupades (pràctiques de costos de BigQuery). Aquests controls són més fiables que un pressupost mensual estàtic perquè el volum de dades i la combinació de consultes canviaran.

Mantenir el sistema pesa tant com l’SQL. Cada consulta necessita responsable, destinació, horari i alerta. Mostra l’última actualització i la cobertura perquè un zero pot ser una exportació fallida.

Fes control de qualitat abans d’interpretar el SEO

Abans d’explicar una pujada o una baixada, comprova el conjunt de dades que l’ha produïda.

Primer, consulta ExportLog per confirmar que searchdata_site_impression i searchdata_url_impression s’han completat en totes les dates previstes. Poden arribar en moments diferents i el registre només recull escriptures correctes, no intents fallits (guia de monitoratge de l’exportació).

Search Console torna a provar una data omesa durant aproximadament una setmana. Els problemes persistents poden acabar aturant l’exportació, i els propietaris i usuaris amb accés complet reben missatges d’error (guia de monitoratge de l’exportació).

Després, compara els totals de propietat d’un dia amb dades definitives amb una referència estable. Una diferència no demostra de seguida que les dades estiguin malmeses: les files anonimitzades, el tipus d’agregació, el tipus de cerca, el fus horari i les correccions tardanes poden explicar-la. Registra aquestes decisions al costat de la mètrica. Quan canviï epoch_version, reconstrueix les files derivades d’aquella data en lloc d’afegir-ne una altra còpia.

Tracta aquests casos com a proves recomanades de qualitat, no com a invariants universals:

• cap valor futur de data_date;
• cap clic ni impressió negatius;
• els clics no superen les impressions a la granularitat d’agregació triada;
• el CTR es calcula a partir de la suma de clics i impressions (directrius de consulta);
• la posició mitjana es pondera amb les sumes de posició (referència de les taules);
• només s’accepten dispositius i tipus de cerca reconeguts, i els valors desconeguts es posen en quarantena en comptes de descartar-los;
• els informes de consultes identificades exclouen explícitament les files anonimitzades, mentre que els informes de totals les conserven (directrius de consulta);
• els encreuaments d’URL informen dels registres sense correspondència en lloc d’eliminar-los en silenci.

Prova els mapatges de negoci per separat i afegeix vigència a les classificacions variables. Consulta l’observabilitat SEO i CI/CD per a les comprovacions i la guia SEO amb GA4 per al comportament posterior al clic.

Anàlisis que justifiquen el magatzem

BigQuery compensa la càrrega quan permet decisions que la interfície o l’API no poden sostenir amb claredat.

Estabilitat entre consulta i URL

Compta les URL per consulta i setmana. Els canvis freqüents orienten la investigació, però no demostren canibalització.

Cohorts de llançament

Compara cohorts en finestres equivalents per país, dispositiu i tipus de pàgina, amb l’estacionalitat i els canvis del lloc visibles. La cohort no demostra atribució.

Tendències de marca i no marca

Versiona les grafies de marca, separa el rendiment anonimitzat i revisa falsos positius quan canviïn productes o mercats.

Llista d’oportunitats

Materialitza una vista amb impressions sostingudes, posició estable i CTR sota la línia base pròpia. Segmenta per país, dispositiu, intenció i SERP.

Diagnòstic internacional

Assigna cada URL al seu idioma previst i compara cohorts per país, dispositiu i consulta. La dimensió de país de Search Console agrupa les dades segons el país on s’ha originat la cerca; no demostra l’idioma ni la residència de l’usuari (dimensions de l’informe de rendiment). Utilitza el resultat per revisar hreflang, localització i demanda, i després comprova la implementació tècnica amb la guia de SEO internacional.

Context per atribuir canvis

Anota desplegaments, redireccions, edicions i incidències sobre el rendiment diari, sense confondre correlació i causalitat. El marc de previsió SEO separa impacte, confiança i esforç.

Marc de decisió per a la pròxima implementació

Respon aquestes quatre preguntes per ordre.

1. La tasca és exploratòria o recurrent? Explora a la interfície; automatitza quan coneguis la decisió.
2. Les files de poc volum canviarien la decisió? Si sí, activa l’exportació, perquè no és retroactiva.
3. Calen encreuaments, històric o regles compartides? Aleshores BigQuery té més sentit.
4. L’equip pot mantenir-ho? Assigna responsables o redueix l’abast.

Comença petit: activa l’exportació a la ubicació correcta, verifica taules i ExportLog, crea un model amb filtre de partició i reconcilia una setmana definitiva. Afegeix taxonomies i encreuaments després.

Exigeix dos registres correctes per data, estats separats, filtres de partició, límits de bytes, responsables, subtotals etiquetats i última data correcta visible. L’anàlisi ha de ser reproduïble.

Preguntes freqüents

L’API de Search Console és més completa que la interfície?

Pot retornar més files i permet repetir filtres, dimensions i paginació, però continua subjecta als límits interns de Search Console. L’API Search Analytics exposa com a màxim 50.000 files diàries per tipus de cerca i retorna les files principals, no pas un conjunt complet garantit de consultes. L’exportació massiva és una font més adequada quan necessites un conjunt de dades continu i més complet.

L’exportació massiva a BigQuery inclou les consultes anonimitzades?

No revela el text de les consultes protegides per privacitat. Les dades exportades poden contenir files anonimitzades, identificades amb un indicador i amb el valor de consulta buit. Els seus clics i impressions poden contribuir als totals sense convertir-se en termes de consulta utilitzables. No tractis la suma de consultes identificades com si fos tota la demanda de cerca.

Puc carregar dades antigues de Search Console a BigQuery?

L’exportació massiva nativa només conserva dades a partir del dia en què s’activa. Pots utilitzar l’API Search Analytics o exportacions que ja haguessis desat per recuperar dades històriques, dins de la disponibilitat i els límits de cada font. Conserva aquesta càrrega separada o normalitza-la amb cura, perquè la cobertura de l’API i la de l’exportació massiva poden ser diferents.

Com puc controlar el cost de les consultes de Search Console a BigQuery?

Filtra la columna de partició per data, selecciona només les columnes necessàries, previsualitza o executa la consulta en mode de prova, limita els bytes facturats en treballs sota demanda i materialitza les vistes que reutilitzis sovint. Una clàusula LIMIT, tota sola, no redueix els bytes llegits d’una taula no agrupada. Consulta els preus vigents de BigQuery per a la ubicació i el model de facturació, en comptes de confiar en una estimació fixa.

Quina taula de BigQuery he d’utilitzar per a l’anàlisi SEO?

Utilitza searchdata_site_impression per analitzar tendències de propietat i searchdata_url_impression quan la pregunta inclogui l’URL de destinació. Consulta ExportLog per comprovar que les dues taules de rendiment s’han escrit correctament en cada data. No sumis les taules de propietat i d’URL, perquè són vistes d’agregació alternatives del mateix rendiment de cerca.

Comença amb una setmana de dades definitives

No comencis pels quadres. Activa la font, espera una setmana definitiva, verifica ExportLog i modela fus horari, tipus de cerca, anonimització i agregació. Respon una pregunta i fes que una altra persona la reprodueixi. Després decideix si invertir en API, magatzem o vista desada.