v1Recursos/Listados publicados/getObtener Share of Voice
Obtener Share of Voice
Su cuota de Grid Rank frente a competidores designados, sus palabras clave con mejor rendimiento clasificadas por cuota top-3 actual, y una tendencia mensual de posición promedio en la ventana — para una ubicación.
get
seo:read/api/v1/seo/share-of-voiceParámetros de consulta
locationIdstringobligatorio
La ubicación a consultar. Búsquelo con GET /api/v1/locations.
clientIdstringopcional
El cliente de la ubicación. Solo necesario para desambiguar cuando su clave está limitada a clientes específicos.
fromstringopcional
Inicio de la ventana (fecha ISO). Por defecto, hace 30 días.
tostringopcional
Fin de la ventana (fecha ISO). Por defecto, ahora.
keywordIdstringopcional
Un id de palabra clave rastreada de maps.keywords para leer su Top 3 en Google Maps. Omítalo para usar la palabra clave más reciente con un escaneo medido.
Respuesta
dataobjectopcional
comparisonobjectopcional
Tú frente a competidores designados por cuota top-3 de grid.
availablebooleanopcional
Si esta ubicación tiene datos de grid-rank para calcular el Share of Voice.
rowsarray of objectopcional
Una fila por cada negocio en la comparación — tú y tus competidores nombrados.
namestringopcional
El nombre del negocio, o el nombre de su propio cliente en su propia fila.
top3Pctnumberopcional
Porcentaje de palabras clave rastreadas en las que este negocio se posiciona entre los 3 primeros (0–100), o null si no hay datos suficientes.
isYoubooleanopcional
True en la fila de su propia ubicación. Se omite (nunca false) en las filas de la competencia.
keywordsobjectopcional
Las palabras clave de esta ubicación, clasificadas por cuota top-3 más reciente.
availablebooleanopcional
Si esta ubicación tiene datos de grid-rank para calcular el Share of Voice.
rowsarray of objectopcional
Una fila por cada palabra clave rastreada.
keywordstringopcional
La palabra clave rastreada.
top3Pctnumberopcional
Porcentaje de palabras clave rastreadas en las que este negocio se posiciona entre los 3 primeros (0–100), o null si no hay datos suficientes.
avgRanknumberopcional
Posición promedio durante la ventana, o null si no hay datos suficientes.
performanceobjectopcional
Tendencia mensual de posición promedio por palabra clave, acotada por from/to.
availablebooleanopcional
Si esta ubicación tiene datos de grid-rank para calcular el Share of Voice.
seriesarray of objectopcional
Una serie por cada palabra clave rastreada.
keywordstringopcional
La palabra clave rastreada.
pointsarray of objectopcional
Puntos de datos de posición promedio mensual para esta palabra clave.
mapsobjectopcional
Top 3 en Google Maps para una palabra clave, a partir de un escaneo de cuadrícula guardado.
availablebooleanobligatorio
False cuando su clave no puede leer esta ubicación.
keywordsarray of objectobligatorio
Las palabras clave rastreadas activas de la ubicación, de la más reciente a la más antigua.
idstringobligatorio
El id de la palabra clave rastreada.
keywordstringobligatorio
La palabra clave rastreada.
measuredbooleanobligatorio
True cuando existe un escaneo guardado con al menos un punto medido para esta palabra clave.
selectedKeywordIdstringobligatorio
La palabra clave a la que corresponden todas las cifras de maps. Null cuando la ubicación no rastrea palabras clave.
selectionstring (requested | default)obligatorio
requested: indicó la palabra clave con keywordId. default: la palabra clave más reciente con un escaneo medido o, si no hay, la más reciente.
reportobjectobligatorio
El escaneo más reciente de la palabra clave seleccionada con un punto medido. Null significa que no hay escaneo medido, nunca 0 %.
idstringobligatorio
El id del informe guardado.
keywordIdstringobligatorio
El id de la palabra clave rastreada.
keywordstringobligatorio
La palabra clave rastreada.
yearMonthstringobligatorio
El mes que cubre este punto, como "YYYY-MM".
gridSizeintegerobligatorio
La longitud de lado configurada de la cuadrícula cuando se escaneó. points contiene los puntos reales.
completedAtstringobligatorio
Cuándo se completó la recopilación de cuadrícula completa que respalda exactamente estos resultados. Null salvo que esté demostrado.
generatedAtstringobligatorio
La fecha registrada del informe, fijada cuando se finalizó por primera vez. No es una hora de recopilación, de última actualización ni una comprobación en directo.
evidencestring (proven | unverified)obligatorio
proven: cada punto contado coincide con la palabra clave y la cuadrícula actuales. unverified: un escaneo heredado cuya palabra clave y cuadrícula no se pueden confirmar.
pointsarray of objectobligatorio
Cada punto de cuadrícula guardado, en orden de fila y columna, con su estado.
missingPointsintegerobligatorio
Puntos de la cuadrícula sin ningún resultado guardado.
withheldPointsintegerobligatorio
Puntos guardados de una configuración anterior de palabra clave o cuadrícula. Se muestran como withheld y no se cuentan.
countedintegerobligatorio
Puntos guardados que cuenta esta ubicación, sin incluir los puntos water y excluded.
measuredintegerobligatorio
Puntos contados con una respuesta medida (ranked u outside). El denominador de top3.
noDataintegerobligatorio
Puntos contados cuya comprobación falló. No es una posición.
top3integerobligatorio
Puntos medidos en los que usted quedó entre los 3 primeros.
outsideintegerobligatorio
Puntos medidos en los que usted no estaba en el top 20 rastreado.
top3Pctnumberobligatorio
Porcentaje de palabras clave rastreadas en las que este negocio se posiciona entre los 3 primeros (0–100), o null si no hay datos suficientes.
avgRanknumberobligatorio
Posición promedio en los puntos medidos, contando outside como 21. Null cuando no se midió nada.
bestRankintegerobligatorio
Mejor posición medida, de 1 a 20. Null cuando todos los puntos medidos son outside.
businessPointobjectobligatorio
El punto muestreado más cercano a las coordenadas de la propia ubicación. Un punto de búsqueda, no la dirección en sí. Null cuando la ubicación no tiene coordenadas.
newerUnmeasuredobjectobligatorio
Un escaneo más reciente de la palabra clave que no midió nada contabilizable, indicado junto a report y no en su lugar. Null si no hay ninguno.
yearMonthstringobligatorio
El mes que cubre este punto, como "YYYY-MM".
generatedAtstringobligatorio
La fecha registrada del informe, fijada cuando se finalizó por primera vez. No es una hora de recopilación, de última actualización ni una comprobación en directo.
competitorsarray of objectobligatorio
Usted y los principales competidores, contados sobre los puntos medidos del informe. Vacío si no hay informe.
idstringobligatorio
Un id estable del negocio: id: seguido de su id de lugar de Google o, si no hay, su nombre más la dirección. "you" en su propia fila.
namestringobligatorio
El nombre del negocio tal como se registró. Puede estar vacío y lo está en su propia fila.
addressstringobligatorio
La dirección tal como se registró, si el escaneo la capturó. Distingue sucursales con el mismo nombre.
isYoubooleanobligatorio
True en la fila de su propia ubicación. Se omite (nunca false) en las filas de la competencia.
top3Spotsintegerobligatorio
Puntos medidos en los que este negocio quedó entre los 3 primeros. Los negocios comparten puntos, así que las filas no suman el total.
scanInProgressbooleanobligatorio
True mientras se ejecuta un escaneo de cuadrícula para esta ubicación. Afecta a toda la ubicación: no indica qué palabras clave cubre el escaneo.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
get/api/v1/seo/share-of-voice
Su clave de API
locationId *
clientId
from
to
keywordId
{
"data": {
"comparison": {
"available": true,
"rows": [
{
"name": "Acme Dental — Downtown",
"top3Pct": 62,
"isYou": true
},
{
"name": "Bright Smiles Dental",
"top3Pct": 74
}
]
},
"keywords": {
"available": true,
"rows": [
{
"keyword": "dentist near me",
"top3Pct": 62,
"avgRank": 3.2
}
]
},
"performance": {
"available": true,
"series": [
{
"keyword": "dentist near me",
"points": [
{
"yearMonth": "2026-01",
"avgRank": 3.6
},
{
"yearMonth": "2026-02",
"avgRank": 3.2
}
]
}
]
}
}
}Guías que usan este endpoint
- What Is an AEO API?An AEO API measures how AI answer engines like ChatGPT, Gemini and Perplexity describe and recommend a business, and tracks that visibility over time.
- How to Track Local Rankings with an APITrack local search rankings on a geo grid through an API, add keywords, read the grid and trend, and compare against competitors and citation coverage.