Nearby Search (nouveau)

Sélectionnez une plate-forme : Android iOS JavaScript Services Web
Développeurs de l'Espace économique européen (EEE)

Introduction

Une requête Nearby Search (nouveau) accepte 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 nouvelle recherche à proximité n'accepte que les requêtes POST.

APIs Explorer vous permet d'envoyer des requêtes en direct pour vous familiariser avec l'API et ses options :

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

Requêtes Nearby Search (nouveau)

Une requête Nearby Search (New) est une requête HTTP POST envoyée à une URL au format suivant :

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 dans le cadre 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 nouvelle recherche à proximité 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. Il n'existe pas de liste par défaut des champs renvoyés 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 Pro :

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      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.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Les descripteurs d'adresse sont généralement disponibles pour les clients en Inde et sont expérimentaux ailleurs.

      ** 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 Enterprise :

      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 Enterprise + Atmosphere :

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      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,0 (inclus). Le rayon par défaut est de 0.0. Vous devez définir une valeur supérieure à 0,0 dans votre demande.

    Exemple : 

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

Paramètres facultatifs

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Vous permet de spécifier une liste de types à partir des types du tableau 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 du Tableau 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 valeurs de type du Tableau A. Par exemple, un restaurant peut avoir les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats de 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 "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, seuls les lieux qui répondent à toutes les restrictions sont renvoyés. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, les lieux renvoyés proposent des services liés à "restaurant", mais ne fonctionnent pas principalement comme "steak_house".

    includedTypes

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

    excludedTypes

    Liste de types de lieux 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 dans la catégorie "school", mais pas dans la catégorie "primary_school". La réponse inclut les lieux qui correspondent à au moins un des includedTypes et à aucun des excludedTypes.

    En cas de types conflictuels (par exemple, un type apparaissant à la fois dans includedTypes et excludedTypes), une erreur INVALID_REQUEST est renvoyée.

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

    En cas de types principaux conflictuels (par exemple, un type apparaissant à la fois dans includedPrimaryTypes et excludedPrimaryTypes), une erreur INVALID_ARGUMENT est renvoyée.

  • languageCode

    Langue dans laquelle renvoyer les résultats.

    • Consultez la liste des langues disponibles. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
    • Si languageCode n'est pas fourni, l'API utilise en par défaut. 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 pour l'utilisateur et les habitants. Pour atteindre cet objectif, il renvoie les adresses postales dans la langue locale, translitté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 d'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, ainsi que sur l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, comme les abréviations des types de rues ou les synonymes qui peuvent ê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 (valeur 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'une des valeurs suivantes :

    • 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"). Ce paramètre peut avoir une incidence sur les résultats en fonction de la loi applicable.

Exemples de Nearby Search (nouveau)

Trouver des lieux d'un type donné

L'exemple suivant montre une requête Nearby Search (nouveau) pour les noms à afficher de tous les restaurants situés dans un rayon de 500 mètres, défini 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 se présente ensuite sous la forme suivante :

{
  "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 se présente désormais sous la forme suivante :

{
  "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"
      }
    },
...
}

Trouver des lieux de plusieurs types

L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les magasins de proximité et débits de boissons situés dans un rayon de 1 000 mètres autour 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 sur le type de chaque lieu, ce qui facilite la sélection du lieu approprié dans les résultats.

L'exemple suivant montre une requête Nearby Search (New) pour tous les lieux de type "school", à l'exclusion de 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 Nearby Search (New) pour des lieux situés à proximité d'un point du 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

Obtenir des descripteurs d'adresse

Les descripteurs d'adresse fournissent des informations relationnelles sur l'emplacement d'un lieu, y compris les points de repère à proximité et les zones qu'il contient.

L'exemple suivant montre une requête Nearby Search (New) pour des lieux à proximité d'un centre commercial à San José. Dans cet exemple, vous incluez addressDescriptors dans le masque de champ :

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

La réponse inclut le lieu spécifié dans la requête, une liste des points de repère à proximité et leur distance par rapport au lieu, ainsi qu'une liste des zones et de leur relation de confinement avec le lieu :

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Essayer

APIs Explorer vous permet d'effectuer des exemples de requêtes pour vous familiariser avec l'API et ses options.

  1. Sélectionnez l'icône API api à droite de la page.

  2. Vous pouvez également modifier les paramètres de la requête.

  3. Sélectionnez le bouton Exécuter. Dans la boîte de dialogue, sélectionnez le compte que vous souhaitez utiliser pour envoyer la demande.

  4. Dans le panneau APIs Explorer, sélectionnez l'icône plein écran fullscreen pour développer la fenêtre APIs Explorer.