Recherche à proximité (nouveau)

Sélectionnez une plate-forme : Android iOS JavaScript Services Web

Une requête Nearby Search (nouveau) spécifie un ou plusieurs types de lieux et renvoie une liste de lieux correspondants dans la zone spécifiée. Un masque de champ spécifiant un ou plusieurs types de données est obligatoire. La recherche à proximité (nouvelle version) n'accepte que les requêtes POST.

L'explorateur d'API vous permet d'envoyer des requêtes en direct afin de vous familiariser avec l'API et ses options:

Essayer

Essayez la démonstration interactive pour voir les résultats de la recherche à proximité (nouvelle) affichés sur une carte.

Requêtes Nearby Search (nouveau)

Une requête "Recherche à proximité (nouvelle)" est une requête HTTP POST envoyée à une URL sous la forme suivante:

https://places.googleapis.com/v1/places:searchNearby

Transmettez tous les paramètres dans le corps de la requête JSON ou dans les en-têtes de la requête POST. Exemple :

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Réponses Nearby Search (nouveau)

La recherche dans les environs (nouvelle) renvoie un objet JSON en réponse. Dans la réponse :

  • Le tableau places contient tous les lieux correspondants.
  • Chaque lieu du tableau est représenté par un objet Place. L'objet Place contient des informations détaillées sur un seul lieu.
  • Le FieldMask transmis dans la requête spécifie la liste des champs renvoyés dans l'objet Place.

L'objet JSON complet se présente sous la forme suivante:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Paramètres obligatoires

  • FieldMask

    Spécifiez la liste des champs à renvoyer dans la réponse en créant un masque de champ de réponse. Transmettez le masque de champ de réponse à la méthode à l'aide du paramètre d'URL $fields ou fields, ou à l'aide de l'en-tête HTTP X-Goog-FieldMask. Aucune liste par défaut des champs renvoyés n'est fournie dans la réponse. Si vous omettez le masque de champ, la méthode renvoie une erreur.

    Le masquage de champ est une bonne pratique à appliquer pour vous assurer de ne pas demander de données inutiles. Vous pourrez ainsi réduire le temps de traitement et les frais facturés.

    Spécifiez une liste de types de données de lieu à renvoyer, séparés par une virgule. Par exemple, pour récupérer le nom à afficher et l'adresse du lieu.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Utilisez * pour récupérer tous les champs.

    X-Goog-FieldMask: *

    Spécifiez un ou plusieurs des champs suivants:

    • Les champs suivants déclenchent le SKU Nearby Search (Basic):

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * Le champ places.googleMapsLinks est en phase de prévisualisation avant disponibilité générale. Aucuns frais ne sont facturés, ce qui signifie que la facturation est de 0 $pour l'utilisation pendant la phase de prévisualisation.

      ** Le champ places.name inclut le nom de ressource du lieu dans le formulaire: places/PLACE_ID. Utilisez places.displayName pour accéder au nom textuel du lieu.

    • Les champs suivants déclenchent le SKU Nearby Search (Advanced):

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

    • Les champs suivants déclenchent le SKU Nearby Search (Preferred):

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.routingSummaries,* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

      * Recherche textuelle et Recherche à proximité uniquement

  • locationRestriction

    Région à rechercher spécifiée sous la forme d'un cercle, défini par un point central et un rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000, inclus. Le rayon par défaut est de 0,0. Vous devez définir une valeur supérieure à 0,0 dans votre requête.

    Par exemple :

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

Paramètres facultatifs

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Permet de spécifier une liste de types à partir des types de la table A utilisés pour filtrer les résultats de recherche. Vous pouvez spécifier jusqu'à 50 types dans chaque catégorie de restriction de type.

    Un lieu ne peut être associé qu'à un seul type principal parmi les types de la table A. Par exemple, le type principal peut être "mexican_restaurant" ou "steak_house". Utilisez includedPrimaryTypes et excludedPrimaryTypes pour filtrer les résultats en fonction du type principal d'un lieu.

    Un lieu peut également être associé à plusieurs types du tableau A. Par exemple, un restaurant peut avoir les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest" et "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats dans la liste des types associés à un lieu.

    Lorsque vous spécifiez un type principal général, tel que "restaurant" ou "hotel", la réponse peut contenir des lieux avec un type principal plus spécifique que celui spécifié. Par exemple, vous spécifiez d'inclure un type principal de "restaurant". La réponse peut alors contenir des lieux dont le type principal est "restaurant", mais elle peut également contenir des lieux dont le type principal est plus spécifique, comme "chinese_restaurant" ou "seafood_restaurant".

    Si une recherche est spécifiée avec plusieurs restrictions de type, seules les zones géographiques qui répondent à toutes les restrictions sont renvoyées. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, les lieux renvoyés fournissent des services liés à "restaurant", mais n'opèrent pas principalement en tant que "steak_house".

    includedTypes

    Liste des types de lieux du tableau A à rechercher, séparés par une virgule. Si ce paramètre est omis, tous les types de lieux sont renvoyés.

    excludedTypes

    Liste des types de lieu du tableau A à exclure d'une recherche, séparés par une virgule.

    Si vous spécifiez à la fois includedTypes ( par exemple, "school") et excludedTypes (par exemple, "primary_school") dans la requête, la réponse inclut les lieux classés comme "school", mais pas comme "primary_school". La réponse inclut les lieux correspondant à au moins un des includedTypes et à aucun des excludedTypes.

    En cas de types contradictoires, par exemple si un type apparaît à la fois dans includedTypes et excludedTypes, une erreur INVALID_REQUEST est renvoyée.

    includedPrimaryTypes

    Liste des types de lieux principaux du tableau A, séparés par une virgule, à inclure dans une recherche.

    excludedPrimaryTypes

    Liste des types de lieux principaux du tableau A, séparés par une virgule, à exclure d'une recherche.

    Si des types principaux contradictoires existent, par exemple un type qui apparaît à la fois dans includedPrimaryTypes et excludedPrimaryTypes, une erreur INVALID_ARGUMENT est renvoyée.

  • languageCode

    Langue dans laquelle les résultats doivent être renvoyés.

    • Consultez la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
    • Si languageCode n'est pas fourni, la valeur par défaut de l'API est en. Si vous spécifiez un code de langue non valide, l'API renvoie une erreur INVALID_ARGUMENT.
    • L'API met tout en œuvre pour fournir une adresse postale lisible à la fois pour l'utilisateur et les habitants. Pour ce faire, il renvoie les adresses dans la langue locale, translitérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont affichées dans la langue préférée. Les composants de l'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
    • Si un nom n'est pas disponible dans la langue préférée, l'API utilise le nom correspondant le plus proche.
    • La langue préférée a une faible influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, par exemple les abréviations des types de rues ou les synonymes pouvant être valides dans une langue, mais pas dans une autre.

  • maxResultCount

    Spécifie le nombre maximal de résultats de lieux à renvoyer. Doit être compris entre 1 et 20 (par défaut), inclus.

  • rankPreference

    Type de classement à utiliser. Si ce paramètre est omis, les résultats sont classés par popularité. Peut être l'un des éléments suivants:

    • POPULARITY (par défaut) : trie les résultats en fonction de leur popularité.
    • DISTANCE : trie les résultats par ordre croissant selon leur distance par rapport à l'emplacement spécifié.

  • regionCode

    Code de région utilisé pour mettre en forme la réponse, spécifié sous la forme d'une valeur de code CLDR à deux caractères. Il n'existe pas de valeur par défaut.

    Si le nom du pays du champ formattedAddress de la réponse correspond à regionCode, le code pays est omis de formattedAddress. Ce paramètre n'a aucun effet sur adrFormatAddress, qui inclut toujours le nom du pays, ni sur shortFormattedAddress, qui ne l'inclut jamais.

    La plupart des codes CLDR sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord"). Le paramètre peut avoir une incidence sur les résultats en fonction de la législation applicable.

Exemples de Nearby Search (nouveau)

Rechercher des lieux d'un type spécifique

L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les restaurants dans un rayon de 500 mètres, définis par circle: 

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Notez que l'en-tête X-Goog-FieldMask spécifie que la réponse contient les champs de données suivants: places.displayName. La réponse est alors au format suivant:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Ajoutez d'autres types de données au masque de champ pour renvoyer des informations supplémentaires. Par exemple, ajoutez places.formattedAddress,places.types,places.websiteUri pour inclure l'adresse, le type et l'adresse Web du restaurant dans la réponse:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

La réponse est désormais au format suivant:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Rechercher des lieux de plusieurs types

L'exemple suivant montre une requête de recherche à proximité (nouvelle) pour les noms à afficher de tous les magasins de proximité et les magasins d'alcool dans un rayon de 1 000 mètres du circle spécifié:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
Cet exemple ajoute places.primaryType et places.types au masque de champ afin que la réponse inclue des informations de type sur chaque lieu, ce qui facilite la sélection du lieu approprié parmi les résultats.

L'exemple suivant montre une requête de recherche à proximité (nouvelle) pour tous les lieux de type "school", en excluant tous les lieux de type "primary_school", en classant les résultats par distance:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Rechercher tous les lieux à proximité d'une zone, classés par distance

L'exemple suivant montre une requête de recherche à proximité (nouvelle) pour les lieux à proximité d'un point situé dans le centre-ville de San Francisco. Dans cet exemple, vous incluez le paramètre rankPreference pour classer les résultats par distance:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Essayer

API Explorer vous permet d'envoyer des exemples de requêtes afin de vous familiariser avec l'API et ses options.

  1. Sélectionnez l'icône API Développez l'explorateur d'API. sur le côté droit de la page.
  2. Vous pouvez également développer Afficher les paramètres standards et définir le paramètre fields sur le masque de champ.
  3. Modifiez éventuellement le corps de la requête.
  4. Sélectionnez le bouton Execute (Exécuter). Dans le pop-up, sélectionnez le compte que vous souhaitez utiliser pour effectuer la demande.

  5. Dans le panneau API Explorer, sélectionnez l'icône de développement, Développez l'explorateur d'API., pour développer la fenêtre API Explorer.