Google Maps Search
Google Maps Search convierte una consulta de negocio, categoría o lugar, junto con una ubicación obligatoria, en registros estructurados de lugares públicos. Cada resultado almacenado usa el esquema PlaceItem, independiente del proveedor, de modo que los campos disponibles de identidad, dirección, contacto, calificación, cantidad de reseñas y coordenadas pueden fluir hacia sistemas de investigación y enriquecimiento sin atar a los clientes a las claves de respuesta propias de la fuente.
Funcionalidades de la Google Maps Search API
- Descubrimiento por consulta y ubicaciónCombine una query obligatoria y no vacía, como coffee, con una location obligatoria, como New York, NY, para descubrir lugares públicos coincidentes.
- Controles geográficos opcionalesAgregue country, un par de latitud y longitud, y zoom_level cuando la búsqueda necesite un contexto geográfico más explícito; los campos opcionales que se omiten no se inventan.
- Identidad del lugar y datos de contacto normalizadosReciba campos estables de PlaceItem para ID, URL de origen, nombres, categorías, direcciones, teléfonos públicos, sitios web y momento de recopilación cuando están disponibles.
- Calificaciones y coordenadas geográficasConserve con cada lugar las calificaciones, las cantidades de reseñas, la ciudad, la región, el país, la latitud y la longitud disponibles, y maneje de forma segura los campos de la fuente que no estén presentes.
Parámetros de la Google Maps Search API
| Parámetros | Obligatorio | Descripción |
|---|---|---|
query | Obligatorio | Término de búsqueda obligatorio y no vacío de un lugar, negocio o categoría. |
location | Obligatorio | Área de búsqueda obligatoria, no vacía y legible, como una ciudad, una región o una dirección. Cuando se omiten ambas coordenadas, se combina con la consulta para el descubrimiento. |
country | Opcional | Nombre o código de país opcional y no vacío que se reenvía como contexto geográfico. |
latitude | Opcional | Latitud opcional de -90 a 90. Debe enviarse junto con longitude. |
longitude | Opcional | Longitud opcional de -180 a 180. Debe enviarse junto con latitude. |
zoom_level | Opcional | Nivel de zoom del mapa opcional, entero de 0 a 21. |
results_limit | Opcional | Máximo de registros de lugares que se almacenan; su valor predeterminado es 100 y acepta enteros de 1 a 2,000. |
Cómo usar la Google Maps Search API
Envíe una consulta y una ubicación, siga la tarea asíncrona y lea los registros de lugares normalizados con paginación por cursor.
- Prepare una query y una location no vacías; opcionalmente, agregue country, coordenadas, zoom_level y un results_limit de 1 a 2,000.
- Envíe la solicitud por POST a /v1/google-maps/search y guarde el task_id devuelto.
- Consulte /v1/tasks/{task_id} hasta que la tarea se complete con éxito o informe un error.
- Lea data.results.items y pase next_cursor al endpoint de la tarea mientras has_more siga siendo true.
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueCasos de uso de la Google Maps Search API
- Descubrimiento de negocios locales: Arme una lista acotada de negocios públicos que coincidan con una categoría o un servicio en una ciudad, un distrito o un área de direcciones específicos.
- Enriquecimiento de datos de ubicación: Agregue los nombres, categorías, direcciones, teléfonos, sitios web y coordenadas disponibles a lugares candidatos que ya están en un CRM o en una cola de investigación.
- Investigación de mercado y cobertura: Compare las cantidades de lugares recopilados, las categorías, las calificaciones y los volúmenes de reseñas entre búsquedas geográficas enviadas de forma independiente.
- Preparación de listas cortas de lugares: Use las URL públicas, los campos de contacto, el contexto de calificación y las coordenadas para seleccionar lugares para un flujo de verificación o de detalle aparte.
Consejos de expertos para la Google Maps Search API
- Use una categoría o un término de negocio específicos y una ciudad, un distrito o una dirección claros en location; las combinaciones vagas pueden producir coincidencias amplias o ambiguas.
- Envíe country, coordenadas o zoom_level solo cuando aporten contexto geográfico verificado. Indique latitude y longitude juntas y mantenga ambos valores dentro de los rangos documentados.
- Mantenga results_limit cerca de la cantidad de registros que necesita. Controla el tope de la recopilación, mientras que el limit del GET de la tarea controla cuántos registros almacenados se devuelven en cada página de respuesta.
- Continúe con next_cursor hasta que has_more sea false cuando los resultados almacenados superen la primera página de respuesta de la tarea.
- Trate las descripciones, los campos de contacto, las calificaciones, las cantidades de reseñas y las coordenadas como datos públicos opcionales, y conserve collected_at para comparaciones en momentos concretos.
APIs relacionadas
Además de la Google Maps Search API, use estas APIs cuando necesite otro tipo de datos públicos de Google Maps.