Visão geral

A API Google Search Console da V4MOS.AI entrega os registros brutos de desempenho na busca (cliques, impressões, CTR e posição média) das propriedades do Search Console conectadas à sua organização, por dia, país, dispositivo, página e consulta. As linhas vêm como foram sincronizadas, com os nomes de coluna do data warehouse (snake_case), prontas para levar ao seu BI. Todos os endpoints usam o prefixo /v1/google-search-console e seguem a mesma autenticação, paginação e formato de resposta.

Primeiros passosCopiar link da seção

URL base: https://data.v4mos.ai. Toda chamada exige suas credenciais de API e o organizationId — veja Autenticação.

1. Conecte o Google Search Console em app.v4mos.ai (Contas conectadas) e aguarde a primeira sincronização.
2. Chame qualquer endpoint abaixo com o seu organizationId, por exemplo GET /v1/google-search-console/daily?organizationId=….
3. Toda linha traz integration_id e integration_name: a propriedade conectada de onde ela veio. Para ler uma propriedade só, passe esse valor em integrationId.

Endpoints disponíveisCopiar link da seção

• getRelatório diário/v1/google-search-console/dailyOne row per property and day: clicks, impressions, CTR and average position.
• getRelatório por país/v1/google-search-console/countriesOne row per property, day and country: clicks, impressions, CTR and average position.
• getRelatório por dispositivo/v1/google-search-console/devicesOne row per property, day and device type: clicks, impressions, CTR and average position.
• getRelatório por página/v1/google-search-console/pagesOne row per property, day and page URL: clicks, impressions, CTR and average position.
• getRelatório por consulta/v1/google-search-console/queriesOne row per property, day and search query: clicks, impressions, CTR and average position.

RecursosCopiar link da seção

O Search Console entrega os dados com cerca de 3 dias de atraso. Ao agregar linhas, recalcule o CTR como cliques ÷ impressões em vez de tirar a média do CTR.

Paginação e filtrosCopiar link da seção

• page (padrão 1) e limit (padrão 500, máximo 5000). meta.hasNextPage diz se existe outra página; as linhas vêm sempre na mesma ordem, então avance as páginas até ele ser false.
• dateFrom / dateTo (YYYY-MM-DD, inclusivos) filtram pela coluna de data indicada na tabela acima.
• integrationId mantém só as linhas de uma propriedade conectada.
• As respostas ficam em cache por 30 minutos e os dados são sincronizados uma vez por dia — veja Sincronização de dados.

Formato da respostaCopiar link da seção

{
  "data": [{ "...": "um objeto por linha, com as colunas listadas em cada endpoint" }],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Valores decimais e contadores grandes (campos format: decimal e format: int64 no schema de cada endpoint) chegam como texto, por exemplo "125.50", para não perder precisão. Converta para um tipo numérico do seu lado.