Découvrir des lieux avec l'élément de recherche de lieu et l'API Maps JavaScript

La carte peut être centrée sur un lieu autour duquel vous souhaitez que l'utilisateur effectue une recherche, comme un hôtel, ou initialisée pour demander la position actuelle de l'utilisateur afin de centrer la carte. Pour les besoins de ce document, nous utiliserons un lieu fixe pour ancrer la recherche.

Si vous visualisez des lieux à proximité d'un lieu fixe, comme un hôtel, placez un repère sur la carte pour représenter ce lieu. Exemple :

La carte est centrée sur San Francisco, avec un repère bleu représentant le lieu que nous recherchons à proximité. La couleur du repère a été personnalisée à l'aide de PinElement. Le contrôle du type de carte a été masqué dans l'interface utilisateur.

Configurer l'élément Place Search

Nous pouvons maintenant configurer le code HTML et CSS pour afficher l'élément Place Search. Dans cet exemple, nous allons faire flotter l'élément sur le côté gauche de la carte, mais il est recommandé d'essayer différentes mises en page pour l'adapter à votre application.

L'élément Place Search utilise une approche déclarative. Au lieu de le configurer entièrement en JavaScript, vous définissez le type de recherche directement dans votre code HTML en imbriquant un élément de requête, tel que <gmp-place-nearby-search-request>, dans le composant <gmp-place-search> principal.

Dans votre code HTML, initialisez un élément <gmp-place-search>. Utilisez l'attribut selectable pour activer les événements de clic sur les résultats. À l'intérieur, ajoutez un <gmp-place-nearby-search-request> pour spécifier que cet élément sera utilisé pour la recherche à proximité.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Pour effectuer une recherche initiale et afficher les résultats, nous allons utiliser JavaScript pour obtenir une référence à l'élément de requête imbriqué et définir ses propriétés. Initialisez un cercle à utiliser comme locationRestriction, en utilisant la position du repère de l'étape précédente comme point central. Ensuite, définissez les propriétés locationRestriction et includedPrimaryTypes sur l'élément de requête pour déclencher la recherche.

L'extrait de code correspondant est le suivant :

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

Voici un exemple de l'apparence de l'application à ce stade :

Autoriser l'utilisateur à effectuer une recherche

L'élément Place Search propose deux options de recherche :

• <gmp-place-nearby-search-request> : affiche les résultats de recherche d'une recherche à proximité de Places, à l'aide des types de lieux.
• <gmp-place-text-search-request> : affiche les résultats de recherche d'une recherche textuelle de Places, à l'aide d'une entrée de texte libre telle que "Sushi à San Francisco".

Il s'agit d'éléments imbriqués dans <gmp-place-search>. Vous déclenchez ensuite des recherches en définissant des propriétés sur cet élément de requête imbriqué à l'aide de JavaScript.

Cette section décrit l'implémentation des deux méthodes.

Recherche à proximité

Pour permettre aux utilisateurs d'effectuer une recherche à proximité, vous devez d'abord disposer d'un élément d'interface utilisateur leur permettant de sélectionner un type de lieu. Choisissez la méthode de sélection la plus adaptée à votre application, par exemple une liste déroulante contenant une sélection de types de lieux.

Il est recommandé de choisir un sous-ensemble de types pertinents pour votre cas d'utilisation. Par exemple, si vous développez une application pour montrer aux touristes ce qui se trouve à proximité d'un hôtel, vous pouvez choisir : bakery, coffee_shop, museum, restaurant et tourist_attraction.

Votre code HTML doit contenir l'élément <gmp-place-search> avec un <gmp-place-nearby-search-request> imbriqué.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Ensuite, créez un écouteur JavaScript pour l'événement change sur votre sélecteur de type de lieu. Cet écouteur appellera une fonction qui met à jour les propriétés de l'élément <gmp-place-nearby-search-request>, ce qui déclenchera automatiquement une nouvelle recherche et mettra à jour la liste.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

Le même searchCircle que celui de l'étape de configuration est utilisé pour locationRestriction. La propriété includedPrimaryTypes est définie sur la valeur de la sélection de l'utilisateur. Un maxResultCount facultatif est également défini pour limiter le nombre de résultats.

Recherche textuelle

Pour activer la recherche textuelle, vous devez modifier votre configuration HTML. Au lieu de la requête de recherche à proximité, vous imbriquez un élément <gmp-place-text-search-request>.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

Ajoutez une entrée de texte et un bouton de recherche à votre interface utilisateur. Créez un écouteur JavaScript pour l'événement click du bouton. Le gestionnaire d'événements prendra l'entrée de l'utilisateur et mettra à jour les propriétés de l'élément <gmp-place-text-search-request> pour effectuer la recherche.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

Ici, nous définissons la propriété textQuery avec l'entrée de l'utilisateur. Nous fournissons également un locationBias à l'aide des limites actuelles de la carte, ce qui indique à l'API de privilégier les résultats dans cette zone sans les limiter strictement. Un maxResultCount facultatif limite le nombre de résultats renvoyés.

Afficher les repères et les détails des lieux

L'application peut désormais effectuer une recherche de lieu et remplir l'élément. À l'étape suivante, nous allons améliorer ses fonctionnalités en procédant comme suit :

• Afficher des repères sur la carte pour chaque lieu renseigné dans l'élément Place Search.
• Permettre à un utilisateur de cliquer sur un repère ou sur le lieu dans l'élément Place Search pour afficher plus d'informations sur ce lieu spécifique.

Le principe de cette étape est le même, que l'application utilise une recherche à proximité ou une recherche textuelle.

Tout d'abord, ajoutez une variable globale à votre code JavaScript pour stocker les repères de lieu. Cela vous permettra de les supprimer lorsque la recherche change et de gérer les événements de clic.

let markers = {};

Créez une fonction pour ajouter des repères à la carte. Cette fonction sera appelée chaque fois que de nouveaux résultats de recherche seront chargés. Elle effectuera les opérations suivantes :

• Supprimer tous les repères de lieu existants de la carte.
• Parcourir les résultats de l'élément Place Search et ajouter un repère pour chacun d'eux.
• Ajuster les limites de la carte afin que tous les nouveaux repères soient visibles.

Pour écouter le moment où les résultats de recherche sont disponibles, ajoutez un gmp-load écouteur d'événements à l'élément <gmp-place-search>. Cet événement se déclenche une fois la recherche terminée et les résultats affichés.

Nous allons ajouter l'écouteur dans notre fonction de recherche (par exemple, updatePlaceList) et utiliser l'option { once: true } pour nous assurer qu'il ne se déclenche que pour les résultats de la recherche actuelle.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

La fonction addMarkers se présente comme suit :

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

Une fois cette étape terminée, l'application se présentera comme suit, avec la possibilité d'afficher des repères pour chaque lieu renvoyé par l'élément Place Search :

Maintenant que nous avons des repères sur la carte, la dernière étape consiste à gérer les événements de clic sur les repères et les éléments pour afficher une fenêtre d'informations contenant les détails du lieu, fournis par l' élément Place Details. Dans cet exemple, nous allons utiliser l'élément Place Details Compact.

Ajoutez le code HTML de l'élément Place Details Compact à votre code, par exemple :

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

Le style est défini sur display: none ; il ne sera visible que lorsqu'il sera requis. gmp-place-all-content est transmis pour afficher tout le contenu de l'élément. Pour choisir le contenu à afficher, consultez la documentation sur l'élément Place Details Compact Element documentation.

Créez une variable globale en JavaScript pour contenir une référence à l'élément Place Details Compact, et remplissez-la dans votre code d'initialisation, par exemple :

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

Dans la fonction addMarkers, ajoutez un écouteur d'événements gmp-click à chaque repère, et configurez l'élément Place Details Compact pour afficher les détails du lieu en transmettant l'identifiant de lieu du repère actuel.

Une fois cette opération effectuée, une fenêtre d'informations s'ouvre pour afficher l'élément Place Details Compact, ancré sur le repère.

Enfin, la carte est positionnée sur la fenêtre d'affichage du lieu sélectionné, ce qui la rend visible.

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

Pour permettre à l'utilisateur de cliquer sur un lieu dans l'élément Place List afin d'afficher l'élément Place Details Compact, ajoutez le code suivant au code JavaScript après l'appel à configureFromSearchNearbyRequest.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

Une fois cette étape terminée, l'application pourra utiliser une recherche à proximité ou une recherche textuelle pour remplir l'élément Place List. Les résultats afficheront des repères sur la carte, et en cliquant sur un repère ou sur un lieu dans l'élément Place List, une fenêtre d'informations contenant les détails du lieu s'affichera, fournie par l'élément Place Details Compact.

L'application se présentera comme suit :

Conclusion

L'élément Place Search combiné à l'élément Place Details Compact offre un moyen simplifié d'ajouter des fonctionnalités de découverte de lieux enrichies à vos applications Google Maps Platform.

Essayez le Kit UI pour Places dès aujourd'hui pour permettre à vos utilisateurs de trouver et d'explorer des lieux à l'aide de recherches à proximité et textuelles, et d'afficher des détails enrichis sur les lieux, ce qui améliore leur interaction avec vos cas d'utilisation de découverte de lieux.

Contributeurs

Henrik Valve | DevX Ingénieur