Google Maps Search
Google Maps Search transforme une requête portant sur une entreprise, une catégorie ou un lieu, associée à une localisation obligatoire, en enregistrements de lieux publics structurés. Chaque résultat enregistré suit le schéma PlaceItem, indépendant du fournisseur : les champs disponibles d’identité, d’adresse, de contact, de note, de nombre d’avis et de coordonnées alimentent ainsi vos systèmes de recherche et d’enrichissement sans lier les clients aux clés de réponse d’une source.
Fonctionnalités de la Google Maps Search API
- Découverte par requête et localisationCombinez une requête obligatoire non vide, comme coffee, avec une localisation obligatoire, comme New York, NY, pour découvrir les lieux publics correspondants.
- Contrôles géographiques facultatifsAjoutez country, un couple latitude-longitude et zoom_level lorsque la recherche exige un contexte géographique plus explicite ; les champs facultatifs omis ne sont jamais inventés.
- Identité et contact normalisésRecevez des champs PlaceItem stables pour les ID, URL sources, noms, catégories, adresses, numéros de téléphone publics, sites web et date de collecte, lorsqu’ils sont disponibles.
- Notes et coordonnées géographiquesConservez, pour chaque lieu, les notes, nombres d’avis, ville, région, pays, latitude et longitude disponibles, avec une gestion sûre des champs absents de la source.
Paramètres de la Google Maps Search API
| Paramètres | Obligatoire | Description |
|---|---|---|
query | Obligatoire | Terme de recherche obligatoire et non vide pour un lieu, une entreprise ou une catégorie. |
location | Obligatoire | Zone de recherche obligatoire, non vide et lisible, comme une ville, une région ou une adresse. Si les deux coordonnées sont omises, elle est combinée à la requête pour la découverte. |
country | Facultatif | Nom ou code de pays facultatif et non vide, transmis comme contexte géographique. |
latitude | Facultatif | Latitude facultative, de -90 à 90. Elle doit être fournie avec longitude. |
longitude | Facultatif | Longitude facultative, de -180 à 180. Elle doit être fournie avec latitude. |
zoom_level | Facultatif | Niveau de zoom de la carte facultatif, entier de 0 à 21. |
results_limit | Facultatif | Nombre maximal de fiches de lieu à enregistrer ; 100 par défaut, entiers de 1 à 2 000 acceptés. |
Comment utiliser la Google Maps Search API
Envoyez une requête et une localisation, suivez la tâche asynchrone, puis lisez les fiches de lieu normalisées avec la pagination par curseur.
- Préparez une requête et une localisation non vides ; ajoutez au besoin country, des coordonnées, zoom_level et un results_limit de 1 à 2 000.
- Envoyez la requête en POST à /v1/google-maps/search et conservez le task_id renvoyé.
- Interrogez /v1/tasks/{task_id} jusqu’à ce que la tâche réussisse ou signale un échec.
- Lisez data.results.items et transmettez next_cursor à l’endpoint de la tâche tant que has_more reste 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 trueCas d’usage de la Google Maps Search API
- Découverte d’entreprises locales : Constituez une liste bornée d’entreprises publiques correspondant à une catégorie ou à un service dans une ville, un quartier ou une zone d’adresse donnés.
- Enrichissement de données de localisation : Ajoutez noms, catégories, adresses, téléphones, sites web et coordonnées disponibles aux lieux candidats déjà présents dans un CRM ou une file de recherche.
- Étude de marché et de couverture : Comparez le nombre de lieux collectés, les catégories, les notes et les volumes d’avis entre des recherches géographiques soumises indépendamment.
- Préparation d’une présélection de lieux : Servez-vous des URL publiques, des champs de contact, du contexte de notation et des coordonnées pour choisir les lieux à traiter dans un workflow distinct de vérification ou de détail.
Conseils d’expert pour la Google Maps Search API
- Utilisez un terme de catégorie ou d’entreprise précis, et une ville, un quartier ou une adresse clairs dans location ; des combinaisons vagues peuvent produire des correspondances larges ou ambiguës.
- N’envoyez country, des coordonnées ou zoom_level que s’ils apportent un contexte géographique vérifié. Fournissez latitude et longitude ensemble et gardez les deux valeurs dans les plages documentées.
- Gardez results_limit proche du nombre d’enregistrements dont vous avez besoin. Il fixe le plafond de collecte, alors que le limit du GET de la tâche détermine combien d’enregistrements stockés sont renvoyés par page de réponse.
- Poursuivez avec next_cursor jusqu’à ce que has_more soit false lorsque les résultats enregistrés dépassent la première page de réponse de la tâche.
- Considérez les descriptions, champs de contact, notes, nombres d’avis et coordonnées comme des données publiques facultatives, et conservez collected_at pour les comparaisons à un instant donné.
API associées
En complément de la Google Maps Search API, utilisez ces API lorsque vous avez besoin d’un autre type de données publiques Google Maps.