Method: geocode.destinations.searchDestinations

Cette méthode effectue une recherche de destination et renvoie une liste de destinations.

Requête HTTP

POST https://geocode.googleapis.com/v4beta/geocode/destinations

L'URL utilise la syntaxe de transcodage gRPC.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
Champs
travelModes[]

enum (NavigationPoint.TravelMode)

Facultatif. Modes de transport pour lesquels filtrer les points de navigation. Cela a une incidence sur le champ navigationPoints renvoyé dans la réponse. Si ce champ est vide, les points de navigation de tous les modes de transport sont renvoyés.
languageCode

string

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

string

Facultatif. Code régional. Code régional, spécifié sous la forme d'une valeur ccTLD (domaine de premier niveau) à deux caractères. Le paramètre affecte les résultats en fonction de la législation applicable. Ce paramètre influence également les résultats du service, mais ne les limite pas complètement.

Requête pour la destination principale. Il peut s'agir d'un lieu, d'une adresse complète ou d'un emplacement LatLng. Certains lieux et adresses ne pourront pas être transformés en destination, car les informations les concernant sont insuffisantes.

Les destinations sont créées autour de la requête primaire spécifiée.

Remarque : Seuls les lieux et les adresses pouvant avoir une destination de navigation sont acceptés. Par exemple, un lieu représentant une maison ou un complexe d'appartements peut être utilisé comme requête principale, mais pas les lieux représentant une localité ou une région administrative. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
place

string

Nom de ressource d'un lieu, au format places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Adresse postale.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Une position exacte.
Fin des champs mutuellement exclusifs.

Corps de la réponse

Message de réponse pour DestinationService.SearchDestinations.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Champs
destinations[]

object (Destination)

Liste de destinations.

Le service renvoie un résultat si une destination principale peut être identifiée sans ambiguïté à partir de la requête principale. Sinon, le service peut renvoyer plusieurs résultats pour la désambiguïsation ou aucun résultat.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

Adresse postale que vous souhaitez rechercher. Lorsque vous spécifiez les adresses, respectez le format utilisé par les services postaux nationaux du pays concerné.

Représentation JSON 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
Champs
Requête d'adresse. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
address

object (PostalAddress)

Une adresse postale au format d'adresse postale.
addressQuery

string

Adresse postale mise en forme sur une seule ligne.
Fin des champs mutuellement exclusifs.

SearchDestinationsRequest.LocationQuery

Une requête de localisation pour identifier une destination principale à proximité.

Remarque : Si la requête de lieu se trouve dans un bâtiment contenant des sous-locaux, il est possible que le lieu principal renvoyé soit un sous-local. Dans ce cas, le champ containingPlaces inclut le bâtiment.

Représentation JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
Champs
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Facultatif. Filtres à appliquer aux destinations candidates.
La requête de localisation. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
location

object (LatLng)

Un emplacement LatLng précis.
Fin des champs mutuellement exclusifs.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Filtres à appliquer aux destinations candidates.

Représentation JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Champs
structureType

enum (PlaceView.StructureType)

Facultatif. Si cette option est spécifiée, toutes les destinations sont garanties d'avoir un lieu principal avec ce type de structure. Cela peut entraîner le filtrage de certaines destinations, ou l'élargissement/l'affinement des destinations renvoyées.

Par exemple, si GROUNDS est spécifié, toutes les destinations renvoyées auront un lieu principal avec le type de structure GROUNDS. Cela peut entraîner le filtrage de certaines destinations qui ne font pas partie d'un terrain, ou l'approximation des destinations renvoyées au niveau du terrain.

Ce champ permet également d'extraire plus facilement les polygones d'affichage des bâtiments. Par exemple, si BUILDING est spécifié, le polygone d'affichage du lieu principal correspondra au bâtiment situé à l'emplacement spécifié.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Facultatif. Si cette option est spécifiée, seules les destinations qui répondent aux critères d'adressabilité correspondants sont renvoyées.

PlaceView.StructureType

Type de structure que ce lieu représente.

Enums
STRUCTURE_TYPE_UNSPECIFIED Non utilisé.
POINT Un point géographique.
SECTION Sous-section d'un bâtiment.
BUILDING Un bâtiment.
GROUNDS Une grande zone qui contient généralement plusieurs bâtiments, comme un campus universitaire, un complexe d'appartements ou un centre commercial.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Définit les options de filtrage de l'adressabilité. De nouvelles valeurs pourront être ajoutées à l'avenir.

Enums
ADDRESSABILITY_UNSPECIFIED Si aucune valeur n'est spécifiée, le service choisit une valeur par défaut appropriée.
ANY L'adressabilité n'est pas un critère de filtrage. Les destinations sont renvoyées, qu'elles soient adressables ou non.
PRIMARY Toutes les destinations renvoyées auront un lieu principal avec une adresse ou un nom au niveau de la rue.
WEAK Toutes les destinations renvoyées auront un lieu principal ou une sous-destination avec une adresse ou un nom au niveau de la rue.

Destination

Une destination. Cela inclut le lieu principal, les lieux associés, les entrées et les points de navigation.

Représentation JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
Champs
primary

object (PlaceView)

Le lieu principal identifié par le primary_query dans la requête.
containingPlaces[]

object (PlaceView)

Lieux moins précis dans lesquels se trouve le lieu principal. Par exemple, la résidence dans laquelle se trouve ce bâtiment.
subDestinations[]

object (PlaceView)

Sous-destinations plus précises du lieu principal. Par exemple, les unités contenues dans un bâtiment.

Remarque : Par rapport à l'objet SubDestination renvoyé par l'API Places, cette liste de sous-destinations est plus exhaustive, et chaque sous-destination contient plus d'informations.
landmarks[]

object (Landmark)

Points de repère permettant d'indiquer où se trouve la destination ou d'aider à l'arrivée.
entrances[]

object (Entrance)

Entrées pour cette destination.
navigationPoints[]

object (NavigationPoint)

Points de navigation pour cette destination.

PlaceView

Représente une vue d'un lieu dans l'API Places. Il fournit également des informations supplémentaires spécifiques aux destinations, telles que le type de structure et le polygone d'affichage.

Dans certains cas, un PlaceView avec le même ID de lieu peut différer de ce qui est renvoyé par l'API Places pour les champs types et displayName.

Représentation JSON 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
Champs
place

string

Nom de la ressource de ce lieu, au format places/{placeId}. Peut être utilisé pour rechercher le lieu.
placeId

string

Identifiant unique d'un lieu.
displayName

object (LocalizedText)

Description du lieu lisible par l'humain. Par exemple, "Porte B", "McDonald's"
primaryType

string

Type de lieu principal de ce lieu. Consultez https://developers.google.com/maps/documentation/places/web-service/place-types pour obtenir la liste des valeurs possibles.

Remarque : Ce champ n'est pas toujours renseigné. Dans ce cas, préparez-vous à utiliser le champ types.
types[]

string

Tous les types de lieux associés à ce lieu. Consultez https://developers.google.com/maps/documentation/places/web-service/place-types pour obtenir la liste des valeurs possibles.
formattedAddress

string

Adresse sur une seule ligne.
postalAddress

object (PostalAddress)

Adresse structurée.
structureType

enum (PlaceView.StructureType)

Type de structure correspondant à ce lieu.
location

object (LatLng)

L'emplacement de ce lieu. Pour les lieux avec des polygones d'affichage, cela peut représenter un bon endroit pour placer un repère sur la carte.
displayPolygon

object (Struct format)

Contour du polygone du lieu au format GeoJSON, en utilisant le format RFC 7946 : https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Remarque : Le format RFC 7946 est compatible avec les MultiPolygons. Un objet displayPolygon peut donc représenter plusieurs polygones.
addressComponents[]

object (PlaceView.AddressComponent)

Composants répétés pour chaque niveau de localité.

PlaceView.AddressComponent

Composants structurés qui forment l'adresse formatée, si ces informations sont disponibles.

Représentation JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Champs
longText

string

Description complète ou nom du composant d'adresse. Par exemple, un composant d'adresse pour l'Australie peut avoir "Australie" comme nom complet.
shortText

string

Nom textuel abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'Australie peut avoir le nom court "AU".
types[]

string

Tableau indiquant le ou les types du composant d'adresse.

Ces valeurs sont extraites du tableau des types d'adresses et de composants d'adresse utilisé par l'API Places : https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
languageCode

string

Langue utilisée pour formater ce composant, en notation CLDR.

Point de repère

Les points de repère sont utilisés pour indiquer où se trouve la destination ou pour aider à l'atteindre.

Représentation JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
Champs
relationalDescription

object (LocalizedText)

Description lisible par l'humain de la relation entre la destination et le point de repère. Par exemple : "Près de l'Empire State Building" ou "En face de la Maison-Blanche".
tags[]

enum (Landmark.Tag)

Tags décrivant comment le point de repère peut être utilisé dans le contexte de la destination.
straightLineDistanceMeters

number

Uniquement en sortie. Distance en ligne droite entre ce repère et la destination, en mètres.
travelDistanceMeters

number

Uniquement en sortie. Distance à pied entre ce point de repère et la destination, en mètres.
Le repère. Voici une liste de champs mutuellement exclusifs. Au maximum, un des champs sera défini dans une réponse :
place

object (PlaceView)

Lieu qui représente ce repère.
Fin des champs mutuellement exclusifs.

Landmark.Tag

Liste de tous les tags possibles décrivant comment un point de repère peut être utilisé dans le contexte d'une destination.

Si une adresse comporte à la fois les tags ADDRESS et ARRIVAL, cela signifie que le point de repère est à la fois important localement et proche de la destination.

Enums
TAG_UNSPECIFIED Non utilisé.
ADDRESS Lieu connu localement qui peut être utilisé pour identifier la position générale de la destination. En général, à quelques centaines de mètres de la destination. Ils sont semblables aux repères renvoyés par la fonctionnalité de descripteurs d'adresse de l'API Geocoding : https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Lieu pouvant être utilisé pour aider à arriver à destination. Utile pour la navigation lorsque vous êtes proche de la destination. Par exemple, il peut s'agir d'un lieu situé de l'autre côté de la rue par rapport à la destination. Un point de repère associé à ce tag est généralement plus proche de la destination que les points de repère associés au tag ADDRESS.

Entrée

Une entrée est une paire de coordonnées de latitude/longitude unique qui définit l'emplacement d'un point d'entrée et de sortie pour un lieu.

Représentation JSON 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Champs
displayName

object (LocalizedText)

Nom lisible par l'humain, par exemple "Porte B", "Entrée sud", "Entrée 5e avenue".
location

object (LatLng)

Emplacement de l'entrée.
tags[]

enum (Entrance.Tag)

Liste de tags décrivant l'entrée.
place

string

Structure sur laquelle cette entrée est physiquement située, au format places/{placeId}.

Entrance.Tag

Caractéristiques décrivant une entrée.

Enums
TAG_UNSPECIFIED Non utilisé.
PREFERRED

L'entrée fournit probablement un accès physique au lieu principal de la destination renvoyée. Un lieu peut avoir plusieurs entrées préférées. Si une entrée ne comporte pas ce tag, cela signifie qu'elle se trouve physiquement dans le même bâtiment que le lieu principal, mais qu'elle ne permet pas nécessairement d'accéder à ce lieu.

Par exemple, si le lieu principal est un restaurant dans un centre commercial, les entrées "PREFERRED" seront celles qui mènent probablement au restaurant lui-même, tandis que les autres entrées renvoyées seront d'autres entrées du bâtiment, comme les entrées d'autres restaurants du centre commercial.

Si le lieu principal est un bâtiment, les entrées PREFERRED seront celles qui mènent à la partie "principale" du bâtiment. Par exemple, dans un centre commercial, les entrées PREFERRED seront celles qui permettent d'accéder au hall principal. En revanche, si une entrée ne permet d'accéder qu'à un magasin situé sur le côté du bâtiment, il ne s'agira pas d'une entrée PREFERRED.

Remarque : Une entrée PREFERRED peut ne pas donner accès au lieu principal, et une entrée non PREFERRED peut donner accès au lieu principal.