Requiere autorización
Consulta los datos de tu 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. Debes definir un período de uno o más días.
Cuando la fecha es una de las dimensiones, se omiten de la lista de resultados los días sin datos. Para saber qué días tienen datos, emite una consulta sin filtros agrupada 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 la misma cantidad de clics, se ordenan de forma arbitraria.
Consulta el ejemplo de Python para llamar a este método.
La API está limitada por las limitaciones internas de Search Console y no garantiza que se muestren todas las filas de datos, sino solo las principales.
Consulta los límites de la cantidad de datos disponibles.
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"]
}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 con 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] 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 anterior o igual a la fecha de finalización. Este valor se incluye en el período. | |
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 posterior o igual a la fecha de inicio. Este valor se incluye en el período. | |
dimensions[] |
list |
[Opcional] Son 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 la dimensión 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 al siguiente tipo:
|
|
dimensionFilterGroups[] |
list |
[Opcional] Son cero o más grupos de filtros que se aplicarán 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, puedes especificar si todos los filtros deben coincidir o si al menos uno debe coincidir. | |
dimensionFilterGroups[].groupType |
string |
Indica si todos los filtros de este grupo deben mostrar el valor verdadero ("and") o si uno o más deben mostrar el valor verdadero (aún no se admite).
Los valores aceptables son los siguientes:
|
|
dimensionFilterGroups[].filters[] |
list |
[Opcional] Son 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. Puedes filtrar por cualquier dimensión que se indique aquí, incluso si no agrupas por esa dimensión.
Los valores aceptables son los siguientes:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Opcional] Indica cómo el valor especificado debe coincidir (o no coincidir) con el valor de la dimensión de la fila.
Los valores aceptables son los siguientes:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Es el valor que el filtro debe hacer coincidir o excluir, según el operador. | |
aggregationType |
string |
[Opcional] Indica 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, se agregan todos los datos 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 obtener información sobre cómo se calculan los datos de forma diferente por sitio en comparación con 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 del resultado coincidirá con el tipo solicitado. Si solicitas un tipo no válido, recibirá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:
|
|
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] Es el í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 con cero filas. |
|
dataState |
string |
[Opcional] Si es "all" (no distingue mayúsculas de minúsculas), los datos incluirán datos recientes. Si es "final" (no distingue mayúsculas de minúsculas) o si se omite este parámetro, los datos que se muestran incluirán solo 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 deben usarse cuando se agrupa por la dimensión de la API de HOUR. |
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, todos los resultados de "mdv" se agruparán, y así sucesivamente. Si agrupas por país y dispositivo, se agruparán todos los resultados de "usa, tablet", todos los resultados de "usa, mobile", y así sucesivamente. Consulta la documentación del informe de estadísticas de la Búsqueda para conocer los detalles de cómo se calculan los clics, las impresiones, etcétera, y qué significan.
Los resultados se ordenan de forma descendente según la cantidad de clics, a menos que agrupes por fecha, en cuyo caso los resultados se ordenan por fecha, en orden ascendente (primero los más antiguos y, luego, los más recientes). 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 |
Es una lista de filas agrupadas por los valores clave en el orden que se indica en la consulta. | |
rows[].keys[] |
list |
Es 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 |
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 |
Indica cómo se agregaron los resultados.Consulta la documentación de ayuda para obtener información sobre cómo se calculan los datos de forma diferente por sitio en comparación con por página.
Los valores aceptables son los siguientes:
|
|
metadata |
object |
Es un objeto que se puede mostrar con los resultados de la consulta y que proporciona contexto sobre el estado de los datos. Cuando solicitas datos recientes (con Todas las fechas y horas que se proporcionan en este objeto están en la El campo específico que se muestra dentro de este objeto depende de cómo hayas agrupado tus datos en la solicitud:
|
Pruébalo
Usa el Explorador de APIs que aparece a continuación para llamar a este método en datos reales y ver la respuesta.