Search Analytics: query

Requiere autorización

Consulta tus datos de tráfico de la Búsqueda con los filtros y parámetros que definas. El método devuelve cero o más filas agrupadas por las claves de fila (dimensiones) que definas. Debes definir un período de uno o más días.

Cuando la fecha es una de las dimensiones, los días sin datos se omiten de la lista de resultados. Para saber qué días tienen datos, emite una consulta sin filtros agrupados por fecha para el período de interés.

Los resultados se ordenan por cantidad de clics de forma descendente. Si dos filas tienen la misma cantidad de clics, se ordenan de forma arbitraria.

Consulta la muestra de Python para llamar a este método.

La API está sujeta a limitaciones internas de Search Console y no garantiza que se devuelvan todas las filas de datos, sino solo las principales.

Consulta los límites de la cantidad de datos disponibles.

Ejemplo de POST de JSON:
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
Pruébalo ahora.

Solicitud

Solicitud HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Parámetros

Nombre del parámetro Valor Descripción
Parámetros de ruta
siteUrl string Es la URL de la propiedad, como se define en Search Console. Ejemplos: http://www.example.com/ (para una propiedad de prefijo de URL) o sc-domain:example.com (para una propiedad de dominio)

Autorización

Esta solicitud requiere autorización con al menos uno de los siguientes alcances (obtén más información acerca de la autenticación y autorización).

Alcance
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporciona datos con la siguiente estructura:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            string
          ]
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Nombre de la propiedad Valor Descripción Notas
startDate string [Obligatorio] Es la fecha de inicio del período solicitado, en formato AAAA-MM-DD, en hora del Pacífico (UTC - 7:00/8:00). Debe ser menor o igual que la fecha de finalización. Este valor se incluye en el rango.
endDate string [Obligatorio] Es la fecha de finalización del período solicitado, en formato AAAA-MM-DD, en hora del Pacífico (UTC - 7:00/8:00). Debe ser mayor o igual que la fecha de inicio. Este valor se incluye en el rango.
dimensions[] list [Opcional] Cero o más dimensiones para agrupar los resultados. Los resultados se agrupan en el orden en que proporcionas estas dimensiones. Puedes usar cualquier nombre de dimensión en dimensionFilterGroups[].filters[].dimension, así como "date" y "hour". Los valores de las dimensiones de agrupación se combinan para crear una clave única para cada fila de resultados. Si no se especifican dimensiones, todos los valores se combinarán en una sola fila. No hay límite para la cantidad de dimensiones por las que puedes agrupar, pero no puedes agrupar por la misma dimensión dos veces. Ejemplo: [country, device]
searchType string Obsoleto, usa type en su lugar
type string [Opcional] Filtra los resultados según el siguiente tipo:
  • "discover": Indica resultados de Descubre.
  • "googleNews": Son los resultados de news.google.com y la app de Google Noticias en iOS y Android. No incluye los resultados de la pestaña "Noticias" de la Búsqueda de Google.
  • "news": Son los resultados de la búsqueda de la pestaña "Noticias" en la Búsqueda de Google.
  • "image": Son los resultados de la búsqueda de la pestaña "Imágenes" en la Búsqueda de Google.
  • "video": Resultados de la búsqueda de videos
  • "web": [Predeterminado] Filtra los resultados de la pestaña combinada ("Todo") en la Búsqueda de Google. No incluye los resultados de Descubre ni de Google Noticias.
  • "webMultimodal": Son los resultados de la búsqueda de Google Lens, Busca con un círculo en Android y las cargas de imágenes en la Búsqueda de Google.
dimensionFilterGroups[] list [Opcional] Cero o más grupos de filtros para aplicar a los valores de agrupación de dimensiones. Todos los grupos de filtros deben coincidir para que se devuelva una fila en la respuesta. En un solo grupo de filtros, puedes especificar si deben coincidir todos los filtros o al menos uno.
dimensionFilterGroups[].groupType string Indica si todos los filtros de este grupo deben mostrar un valor verdadero ("and") o si uno o más deben mostrar un valor verdadero (aún no se admite).

Los valores aceptables son los siguientes:
  • "and": Todos los filtros del grupo deben mostrar un valor verdadero para que el grupo de filtrossea verdadero.
dimensionFilterGroups[].filters[] list [Opcional] Cero o más filtros para probar con la fila. Cada filtro consta de un nombre de dimensión, un operador y un valor. La longitud máxima es de 4,096 caracteres. Ejemplos:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string Es la dimensión a la que se aplica este filtro. Puedes filtrar por cualquier dimensión que se indique aquí, incluso si no agrupas por esa dimensión.

Los valores aceptables son los siguientes:
  • "country": Filtra por el país especificado, según el código de país de 3 letras (ISO 3166-1 alfa-3).
  • "device": Filtra los resultados según el tipo de dispositivo especificado. Valores admitidos:
    • ESCRITORIO
    • DISPOSITIVOS MÓVILES
    • TABLET
  • "page": Filtra según la cadena de URI especificada.
  • "query": Filtra según la cadena de consulta especificada.
  • "searchAppearance": Filtra por una función específica de los resultados de la búsqueda. Para ver una lista de los valores disponibles, ejecuta una consulta con agrupación por "searchAppearance". La lista completa de valores y descripciones también está disponible en la documentación de ayuda.
  • "brandedClassification": Filtra los resultados según la clasificación de búsqueda asociada a una marca especificada (solo se admite el operador "equals"). El filtrado o la agrupación por "brandedClassification" no se puede combinar con un filtro "query" en la misma solicitud. Los datos están disponibles a partir del 21 de febrero de 2026 y solo para las propiedades de nivel superior con un volumen suficiente de búsquedas y de impresiones (consulta el anuncio sobre las búsquedas asociadas a una marca). Valores admitidos:
    • DE MARCA
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Opcional] Indica cómo debe coincidir (o no coincidir) el valor especificado con el valor de la dimensión de la fila.

Los valores aceptables son los siguientes:
  • "contains": El valor de la fila debe contener tu expresión o ser igual a ella (no distingue mayúsculas de minúsculas).
  • "equals": [Predeterminado] Tu expresión debe ser exactamente igual al valor de la fila (distingue mayúsculas de minúsculas para las dimensiones de página y consulta).
  • "notContains": El valor de la fila no debe contener tu expresión como una subcadena ni como una coincidencia completa (sin distinguir mayúsculas de minúsculas).
  • "notEquals": Tu expresión no debe ser exactamente igual al valor de la fila (distingue mayúsculas de minúsculas para las dimensiones de página y búsqueda).
  • "includingRegex": Es una expresión regular de sintaxis RE2 que debe coincidir.
  • "excludingRegex": Es una expresión regular de sintaxis RE2 que no debe coincidir.
dimensionFilterGroups[].filters[].expression string Es el valor que el filtro debe coincidir o excluir, según el operador.
dimensionFilterGroups[].filterLists[] list [Opcional] Cero o más filtros de dimensiones de varios valores para probar con la fila. A diferencia de filters[], que coincide con un solo valor por entrada, filterLists[] permite que coincidan varios valores de concordancia exacta para una sola dimensión en un filtro. Una fila coincide con una lista de filtros si su valor para el dimension especificado es igual a cualquiera de los expressions proporcionados. Ten en cuenta que una sola solicitud no puede filtrar la misma dimensión en filters y filterLists al mismo tiempo.
dimensionFilterGroups[].filterLists[].dimension string [Obligatorio] Es la dimensión a la que se aplica esta lista de filtros.

Los valores aceptables son los siguientes:
  • "country": Filtra por los países especificados con códigos de país de 3 letras (ISO 3166-1 alpha-3).
  • "device": Filtra según los tipos de dispositivos especificados (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Obligatorio] Es la lista de valores (string) con los que se filtrará.
aggregationType string

[Opcional] Cómo se agregan los datos. Si se agregan por propiedad, se agregan todos los datos de la misma propiedad. Si se agregan por página, todos los datos se agregan por URI canónico. Si filtras o agrupas por página, elige auto. De lo contrario, puedes agregar por propiedad o por página, según cómo quieras que se calculen tus datos. Consulta la documentación de ayuda para saber cómo se calculan los datos de manera diferente por sitio o por página.

Nota: Si agrupas o filtras por página, no puedes agregar por propiedad.

Si especificas cualquier valor que no sea auto, el tipo de agregación en el resultado coincidirá con el tipo solicitado o, si solicitas un tipo no válido, obtendrás un error. La API nunca cambiará tu tipo de agregación si el tipo solicitado no es válido.

Los valores aceptables son los siguientes:
  • "auto": [Predeterminado] Permite que el servicio decida el tipo de agregación adecuado.
  • "byNewsShowcasePanel": Agrega valores por panel de Showcase. Se debe usar en combinación con el filtro NEWS_SHOWCASE searchAppearance y type=discover o type=googleNews. Si agrupas por página, filtras por página o filtras por otra searchAppearance, no puedes agregar por byNewsShowcasePanel.
  • "byPage": Agrega valores por URI.
  • "byProperty": Agrega valores por propiedad. No se admite para type=discover ni type=googleNews
rowLimit integer [Opcional; el rango válido es de 1 a 25,000; el valor predeterminado es 1,000] Es la cantidad máxima de filas que se mostrarán. Para desplazarte por los resultados, usa el desplazamiento startRow.
startRow integer [Opcional; el valor predeterminado es 0] Índice basado en cero de la primera fila de la respuesta. Debe ser un número no negativo. Si startRow supera la cantidad de resultados de la consulta, la respuesta será correcta, pero tendrá cero filas.
dataState string [Opcional] Si es "all" (no distingue mayúsculas de minúsculas), los datos incluirán datos actualizados. Si es "final" (no distingue mayúsculas de minúsculas) o si se omite este parámetro, los datos devueltos solo incluirán los datos finalizados. Si es "hourly_all" (no distingue mayúsculas de minúsculas), los datos incluirán el desglose por hora. Esto indicará que los datos por hora incluyen datos parciales y se deben usar cuando se agrupan por la dimensión HOUR de la API.

Respuesta

Los resultados se agrupan según las dimensiones especificadas en la solicitud. Todos los valores con el mismo conjunto de valores de dimensión se agruparán en una sola fila. Por ejemplo, si agrupas por la dimensión de país, todos los resultados de "usa" se agruparán juntos, todos los resultados de "mdv" se agruparán juntos, y así sucesivamente. Si agrupaste por país y dispositivo, se agruparán todos los resultados de "EE.UU., tablet", todos los resultados de "EE.UU., dispositivo móvil", etcétera. Consulta la documentación del informe de estadísticas de búsqueda para conocer los detalles de cómo se calculan los clics, las impresiones, etcétera, y qué significan.

Los resultados se ordenan por recuento de clics, en orden descendente, a menos que los agrupes por fecha, en cuyo caso se ordenan por fecha, en orden ascendente (los más antiguos primero, los más recientes al final). Si hay un empate entre dos filas, el orden de clasificación es arbitrario.

Consulta la propiedad rowLimit en la solicitud para conocer la cantidad máxima de valores que se pueden devolver.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Nombre de la propiedad Valor Descripción Notas
rows[] list Es una lista de filas agrupadas por los valores de clave en el orden que se indica en la consulta.
rows[].keys[] list Es una lista de los valores de dimensión para esa fila, agrupados según las dimensiones de la solicitud, en el orden especificado en la solicitud.
rows[].clicks double Es la cantidad de clics de la fila.
rows[].impressions double Es el recuento de impresiones de la fila.
rows[].ctr double Es la tasa de clics (CTR) de la fila. Los valores varían de 0 a 1.0, inclusive.
rows[].position double Es la posición promedio en los resultados de la búsqueda.
responseAggregationType string Cómo se agregaron los resultados Consulta la documentación de ayuda para obtener información sobre cómo se calculan los datos de manera diferente por sitio y por página.

Los valores aceptables son los siguientes:
  • "auto"
  • "byPage": Los resultados se agregaron por página.
  • "byProperty": Los resultados se agregaron por propiedad.
metadata object

Es un objeto que se puede devolver con los resultados de la consulta y que proporciona contexto sobre el estado de los datos.

Cuando solicitas datos recientes (con all o hourly_all para dataState), algunas de las filas que se muestran pueden representar datos incompletos, lo que significa que aún se están recopilando y procesando. Este objeto de metadatos te ayuda a identificar exactamente cuándo comienza y termina.

Todas las fechas y horas proporcionadas en este objeto se encuentran en la zona horaria America/Los_Angeles.

El campo específico que se muestra dentro de este objeto depende de cómo hayas agrupado tus datos en la solicitud:

  • first_incomplete_date (string): Es la primera fecha para la que aún se recopilan y procesan los datos, que se presenta en formato YYYY-MM-DD (formato de fecha local extendido ISO-8601).

    Este campo solo se completa cuando el parámetro dataState de la solicitud es all y los datos se agrupan por date, y el período solicitado contiene datos incompletos.

    Todos los valores posteriores al first_incomplete_date aún pueden cambiar de forma notable.

  • first_incomplete_hour (string): Es la primera hora para la que aún se recopilan y procesan los datos, que se presenta en formato YYYY-MM-DDThh:mm:ss[+|-]hh:mm (formato de fecha y hora de compensación extendido ISO-8601).

    Este campo solo se completa cuando el dataState de la solicitud es hourly_all, los datos se agrupan por hour y el período solicitado contiene datos incompletos.

    Todos los valores posteriores al first_incomplete_hour aún pueden cambiar de forma notable.

Pruébalo

Usa el Explorador de APIs que aparece a continuación para llamar a este método con datos en vivo y ver la respuesta.