Method: geocode.destinations.searchDestinations

Cette méthode effectue une recherche de destinations 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,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
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 de région. 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.

Champ d'union primary_query. Requête pour la destination principale. Il peut s'agir d'un lieu, d'une adresse complète ou d'une position 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 un lieu représentant une localité ou une région administrative. primary_query ne peut être qu'un des éléments suivants :
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.

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 des 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 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
Champs
Champ d'union kind. Requête d'adresse. kind ne peut être qu'un des éléments suivants :
address

object (PostalAddress)

Une adresse postale au format d'adresse postale.
addressQuery

string

Adresse postale mise en forme sur une seule ligne.

SearchDestinationsRequest.LocationQuery

Requête de localisation permettant d'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)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
Champs
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Facultatif. Filtres à appliquer aux candidats de destination.
Champ d'union kind. La requête de localisation. kind ne peut être qu'un des éléments suivants :
location

object (LatLng)

Emplacement LatLng précis.

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'affinage/l'élargissement 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 représente ce lieu.

Enums
STRUCTURE_TYPE_UNSPECIFIED Non utilisé.
POINT Un point géographique.
SECTION Sous-section d'un bâtiment.
BUILDING Un bâtiment.
GROUNDS Vaste zone comprenant 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 comporteront un lieu principal ou une sous-destination avec une adresse ou un nom de 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 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", "McDonalds"
primaryType

string

Type de lieu principal de cet endroit. 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 le pays Australie peut avoir le nom long "Australie".
shortText

string

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

string

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

Pour en savoir plus, consultez https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types.
languageCode

string

Langue utilisée pour mettre en forme 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,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
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 point de 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.
Champ d'union landmark. Le repère. landmark ne peut être qu'un des éléments suivants :
place

object (PlaceView)

Lieu représentant ce point de repère.

Landmark.Tag

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

Si une adresse contient à la fois les balises ADDRESS et ARRIVAL, cela signifie que le point de repère est à la fois important au niveau local et proche de la destination.

Enums
TAG_UNSPECIFIED Non utilisé.
ADDRESS Un lieu important au niveau local qui peut être utilisé pour identifier la zone géographique générale de la destination. En général, à quelques centaines de mètres de la destination. Ils sont semblables aux points de repère 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 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Champs
location

object (LatLng)

Emplacement de l'entrée.
tags[]

enum (Entrance.Tag)

Liste des tags qui décrivent l'entrée.
place

string

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

Entrance.Tag

Caractéristiques décrivant une entrée.

Enums
TAG_UNSPECIFIED Non utilisé.
PREFERRED

L'entrée permet probablement d'accéder physiquement 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.