Search Analytics: query

Requiere autorización.

Consulta tus datos de tráfico de búsqueda con los filtros y parámetros que definas. El método muestra cero o más filas agrupadas por las claves de fila (dimensiones) que definas. Debe 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, emita una consulta sin filtros agrupados por fecha para el período de interés.

Los resultados se ordenan de forma descendente según la cantidad de clics. Si dos filas tienen el mismo recuento de clics, se ordenan de forma arbitraria.

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

La API está limitada por limitaciones internas de Search Console y no garantiza que se muestren todas las filas de datos, sino las principales.

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

Ejemplo de JSON POST:
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 de acceso
siteUrl string Corresponde a la URL de la propiedad, tal 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
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Nombre de la propiedad Valor Descripción Notas
startDate string [Obligatorio] Fecha de inicio del período solicitado, en formato AAAA-MM-DD, en hora del Pacífico (UTC - 7:00/8:00) Debe ser igual o inferior a la fecha de finalización. Este valor se incluye en el rango.
endDate string [Obligatorio] 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 suministra estas dimensiones.Puede usar cualquier nombre de dimensión en dimensionFilterGroups[].filters[].dimension, así como "fecha".Los valores de las dimensiones de agrupación se combinan a fin de 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 que puede agrupar, pero no puede 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 al siguiente tipo:
  • "discover": Resultados de Descubre
  • "googleNews": Muestra 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": Resultados de la búsqueda de la pestaña "Noticias" en la Búsqueda de Google.
  • "image": Resultados de la búsqueda de la pestaña "Imagen" en la Búsqueda de Google.
  • "video": resultados de la búsqueda de videos
  • "web": [Predeterminado] Filtra los resultados en la pestaña combinada ("Todos") en la Búsqueda de Google. No incluye los resultados de Descubre ni Google Noticias.
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 muestre una fila en la respuesta. Dentro de un solo grupo de filtros, puede especificar si todos los filtros deben coincidir o, al menos, uno de ellos.
dimensionFilterGroups[].groupType string Indica si todos los filtros de este grupo deben ser verdaderos ("y"), o bien uno o más deben ser verdaderos (aún no se admiten).

Los valores aceptables son los siguientes:
  • "and": Todos los filtros del grupo deben mostrar un valor verdadero para el grupo de filtros puales.
dimensionFilterGroups[].filters[] list [Opcional] Cero o más filtros para probar en 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. Puede filtrar por cualquier dimensión que aparezca aquí, incluso si no está agrupando por esa dimensión.

Los valores aceptables son los siguientes:
  • "country": Filtra según el país especificado, según lo especificado por el código de país de 3 letras (ISO 3166-1 alpha-3).
  • "device": Filtra los resultados según el tipo de dispositivo especificado. Valores admitidos:
    • COMPUTADORAS DE ESCRITORIO
    • DISPOSITIVOS MÓVILES
    • TABLET
  • "page": Filtra según la string de URI especificada.
  • "query": Filtra según la string de consulta especificada.
  • "searchAppearance": Filtra según una función específica de los resultados de la búsqueda. Para ver una lista de los valores disponibles, ejecuta una consulta agrupada por "searchAppearance".
dimensionFilterGroups[].filters[].operator string [Opcional] Cómo debe coincidir (o no) el valor especificado con el valor de dimensión de la fila.

Los valores aceptables son los siguientes:
  • “contains”: El valor de la fila debe contener o igual la expresión (que no distingue entre mayúsculas y minúsculas).
  • "equals": [Predeterminado] La expresión debe ser exactamente igual al valor de la fila (distingue entre mayúsculas y minúsculas para las dimensiones de página y búsqueda).
  • "notContains": El valor de la fila no debe contener tu expresión como una substring o una coincidencia completa (que no distinga entre mayúsculas y 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 la página y la búsqueda).
  • "includingRegex": Una expresión regular de sintaxis RE2 que debe coincidir.
  • "excludingRegex": Una expresión regular de sintaxis RE2 que no debe coincidir.
dimensionFilterGroups[].filters[].expression string El valor del filtro que debe coincidir o excluirse, según el operador
aggregationType string

[Opcional] Cómo se agregan los datos. Si se agrupan 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 la opción automática; de lo contrario, puedes agregar los datos por propiedad o por página, según cómo desees que se calculen tus datos; consulta la documentación de ayuda para saber cómo se calculan los datos por sitio en comparación con página.

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

Si especificas cualquier valor que no sea automático, el tipo de agregación en el resultado coincidirá con el tipo solicitado o, si solicitas un tipo no válido, se mostrará 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.
  • "byPage": valores agregados por URI
  • "byProperty": valores agregados por propiedad. No se admite para type=discover o type=googleNews
rowLimit integer [Opcional: El rango válido es de 1 a 25,000; el valor predeterminado es 1,000] La cantidad máxima de filas que se mostrarán. Para desplazarse por los resultados, usa el desplazamiento de 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 excede la cantidad de resultados para la consulta, la respuesta será correcta y no tendrá filas.
dataState string [Opcional] Si los valores “todos” (que no distinguen entre mayúsculas y minúsculas), se incluirán los datos actualizados. Si es "final" (distingue entre mayúsculas y minúsculas) o si se omite este parámetro, los datos mostrados solo incluirán los datos finalizados.

Respuesta

Los resultados se agrupan según las dimensiones especificadas en la solicitud. Todos los valores que tengan el mismo conjunto de valores de dimensión se agruparán en una sola fila. Por ejemplo, si agrupa por dimensión del país, todos los resultados de "usa" se agruparán, todos los resultados de "mdv" se agruparán, y así sucesivamente. Si agrupa los datos por país y dispositivo, se agruparán todos los resultados de "usa, tablet", todos los resultados de "usa, móvil" y así sucesivamente. Consulta la documentación del informe de estadísticas de la Búsqueda para obtener información específica sobre cómo se calculan los clics, las impresiones, etc., y lo que significan.

Los resultados se ordenan por cantidad de clics, en orden descendente, a menos que agrupes por fecha, en cuyo caso los resultados se ordenan por fecha (de mayor a mayor o más reciente). 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 mostrar.

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

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

Pruébela.

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