Identidad y ubicación del negocio
Use el nombre del negocio, las categorías, la dirección con formato, las coordenadas y la URL de Maps para organizar un conjunto de datos de negocios locales.
POST /api/v1/search
Encuentre negocios por palabra clave y ubicación. Reciba hasta 20 registros de negocios estructurados en la misma respuesta JSON, listos para su aplicación o su flujo de trabajo de investigación.
Para el contrato completo, consulte la documentación de la API.
curl https://gmapscrawl.com/api/v1/search \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seattle-coffee-search-001" \
-d '{"q":"coffee shops in Seattle","page":1,"extra":false}'Respuesta vacía ilustrativa. Una búsqueda en vivo devuelve los negocios disponibles. Mantenga su clave de API en el lado del servidor; use una nueva clave de idempotencia para trabajo nuevo y consérvela para un reintento sin cambios.
{
"data": {
"total": 0,
"params": {
"q": "coffee shops in Seattle",
"page": 1,
"hl": "en",
"extra": false
},
"businesses": []
},
"request_id": "req_example",
"schema_version": "2026-09-22"
}La API devuelve JSON en la misma respuesta. Tras un timeout, reintente el cuerpo sin cambios con la misma Idempotency-Key. Las credenciales de prueba devuelven datos simulados sin usar su cuota en vivo.
Datos de negocios estructurados
Lea data.businesses de la respuesta. Cada negocio agrupa sus campos de ficha bajo place; la disponibilidad de los campos depende de la fuente.
Use el nombre del negocio, las categorías, la dirección con formato, las coordenadas y la URL de Maps para organizar un conjunto de datos de negocios locales.
Lea los números de teléfono, sitios web, calificaciones y recuentos de reseñas disponibles. Con extra activado, solicite el enriquecimiento de contacto por correo electrónico y redes sociales.
Conserve place.dataId para consultas de reseñas y fotos. Inspeccione place.observedAt y contactsCheckedAt para entender cuándo se observaron los datos.
Los campos no disponibles pueden ser null o estar vacíos, y el enriquecimiento puede reportar not_found o failed. Un registro no garantiza que exista una dirección de correo electrónico o un sitio web. Los detalles de Maps pueden reutilizarse hasta 730 días con sus marcas de tiempo de observación originales; evalúe la actualización antes de usar un registro.
Lea sobre la actualización de los datos →Una solicitud enfocada
Envíe un cuerpo JSON con su clave de API del lado del servidor en el encabezado de autorización. Solo q es obligatorio.
| Parámetro | Requisito | Propósito |
|---|---|---|
| q | Obligatorio | Una palabra clave de negocio y una ubicación, como cafeterías en Seattle. Use de 2 a 200 caracteres. |
| page | Predeterminado: 1 | Una página de búsqueda numerada del 1 al 10. Cada solicitud devuelve como máximo 20 negocios. |
| ll | Opcional | Un viewport de Maps en la forma @47.6062,-122.3321,12z para guiar la ubicación de la búsqueda. |
| hl | Predeterminado: en | El código de idioma usado para la búsqueda. |
| gl | Opcional | Un código de país de dos letras que califica la consulta. No es un filtro geográfico estricto. |
| extra | Predeterminado: false | Establézcalo en true para solicitar el enriquecimiento de contacto por correo electrónico y redes sociales disponible. Esto puede tardar más. |
La respuesta repite los parámetros normalizados en data.params. El valor data.total cuenta los negocios de esta respuesta, no el número total de negocios en Google Maps. Elija otra página explícitamente cuando su flujo de trabajo necesite más resultados.
Cree su primera integración
La API de Search es síncrona: lea el resultado directamente de la respuesta HTTP.
Use su espacio de trabajo de API para crear una clave con el permiso scrapes:write. Guarde la clave en el entorno de su servidor y envíe Authorization: Bearer con la solicitud.
Abrir claves de APIElija una categoría y una ubicación, solicite la página 1 e inspeccione los campos de ficha devueltos. Para una comparación de mercado, emita búsquedas separadas para las áreas que desee comparar.
Use place.dataId de un negocio coincidente como fid para recuperar una página de reseñas o una página de galería. Son solicitudes separadas con sus propios registros devueltos.
Explorar la API de ReviewsPlanifique para solicitudes reales
Cada página de búsqueda en vivo exitosa usa una unidad de solicitud de API, incluido un resultado vacío. REST y MCP comparten la cuota de API. Las suscripciones del scraper Online y de la Extensión tienen cuotas separadas. Siguen aplicándose límites de frecuencia, credenciales, capacidad del servicio y disponibilidad de la fuente.
Comparar planes de API →Permita hasta 180 segundos en su cliente HTTP. Un timeout puede dejar trabajo en proceso con una unidad de solicitud reservada. Reutilice el cuerpo idéntico y la Idempotency-Key para reintentar esa solicitud. Compruebe los detalles del error y la posibilidad de reintento antes de iniciar un nuevo intento.
Entender los reintentos →Continúe su flujo de trabajo
Recupere reseñas públicas o metadatos de fotos y vídeos de un lugar usando su feature ID.
Explorar datos de galeríaPermita que un cliente de IA compatible descubra las herramientas de búsqueda, reseñas y fotos con sus credenciales de API.
Configurar MCPProporcione a su agente instrucciones de flujo de trabajo, referencias de operaciones y un respaldo REST para la investigación en Google Maps.
Explorar la skillDevuelve un sobre JSON con data.businesses, data.total, data.params normalizados, request_id y schema_version. Los negocios incluyen los campos de ficha disponibles, como nombres, direcciones, categorías, información de contacto, calificaciones e identificadores de Maps.
Sí. El endpoint acepta solicitudes HTTP POST estándar con JSON y autenticación Bearer. Los ejemplos anteriores usan la biblioteca estándar de Python y fetch de JavaScript del lado del servidor. Cualquier cliente HTTP que pueda enviar esos encabezados y ese cuerpo puede integrarse.
Una página de búsqueda devuelve entre cero y 20 negocios. El parámetro page acepta valores del 1 al 10. Cada página en vivo exitosa, incluida una página vacía, usa una unidad de solicitud de API; una búsqueda no garantiza que cada página contenga 20 negocios.
Sí. Copie place.dataId de un negocio y páselo como fid a la API separada de Reviews o Photos. Esos endpoints devuelven una página delimitada por solicitud. La descripción general de la API enlaza a los campos, ejemplos y reglas de paginación de cada endpoint.
No. Establezca extra en true para solicitar el enriquecimiento de contacto disponible. Los sitios web, correos electrónicos y perfiles sociales pueden faltar. Inspeccione enrichmentState y fieldStates y mantenga los datos no disponibles explícitos en su aplicación.
Si tiene una credencial de prueba, sus respuestas son simuladas y no consumen cuota de API en vivo. Etiquete esos resultados como simulados. Las claves en vivo requieren un derecho de API activo y capacidad de servicio disponible, y las llamadas en vivo exitosas usan unidades de solicitud.
Dé el siguiente paso
Cree una clave de API, elija una consulta y una ubicación, y lea datos de negocios estructurados en la misma respuesta.