POST /api/v1/search

API de scraping de Google Maps

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.

Ejemplos de solicitud

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.

Respuesta

JSON ilustrativo
{
  "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

De una búsqueda en Maps a registros que puede usar.

Lea data.businesses de la respuesta. Cada negocio agrupa sus campos de ficha bajo place; la disponibilidad de los campos depende de la fuente.

01

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.

02

Contacto y reputación

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.

03

Identificadores y fechas de observación

Conserve place.dataId para consultas de reseñas y fotos. Inspeccione place.observedAt y contactsCheckedAt para entender cuándo se observaron los datos.

Mantenga visibles los datos faltantes y más antiguos

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

Elija la consulta, la página y el enriquecimiento.

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ámetros de la Google Maps Search API
ParámetroRequisitoPropósito
qObligatorioUna palabra clave de negocio y una ubicación, como cafeterías en Seattle. Use de 2 a 200 caracteres.
pagePredeterminado: 1Una página de búsqueda numerada del 1 al 10. Cada solicitud devuelve como máximo 20 negocios.
llOpcionalUn viewport de Maps en la forma @47.6062,-122.3321,12z para guiar la ubicación de la búsqueda.
hlPredeterminado: enEl código de idioma usado para la búsqueda.
glOpcionalUn código de país de dos letras que califica la consulta. No es un filtro geográfico estricto.
extraPredeterminado: falseEstablé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

Una solicitud. Un siguiente paso útil.

La API de Search es síncrona: lea el resultado directamente de la respuesta HTTP.

01

Cree su clave de API

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 API
02

Busque en un área delimitada

Elija 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.

03

Siga un identificador de lugar

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 Reviews

Planifique para solicitudes reales

Páginas predecibles, límites explícitos.

Uso y disponibilidad

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 →

Timeouts y reintentos

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

Más formas de usar los mismos datos de negocios.

01

Datos de reseñas y galería

Recupere reseñas públicas o metadatos de fotos y vídeos de un lugar usando su feature ID.

Explorar datos de galería
02

Conecte un cliente MCP

Permita que un cliente de IA compatible descubra las herramientas de búsqueda, reseñas y fotos con sus credenciales de API.

Configurar MCP
03

Instale el Agent Skill

Proporcione a su agente instrucciones de flujo de trabajo, referencias de operaciones y un respaldo REST para la investigación en Google Maps.

Explorar la skill

Preguntas frecuentes

¿Qué devuelve la API de scraping de Google Maps?

Devuelve 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.

¿Puedo usar la API desde Python o JavaScript?

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.

¿Cuántos negocios puede devolver una solicitud?

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.

¿Puedo recuperar reseñas y fotos individuales?

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.

¿Se incluyen direcciones de correo electrónico para cada negocio?

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.

¿Cómo debo probar una integració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 su primera búsqueda en Google Maps.

Cree una clave de API, elija una consulta y una ubicación, y lea datos de negocios estructurados en la misma respuesta.