Catégorie : Bing Maps

Categories
Bing Maps Microsoft

Utiliser les services REST Bing Maps avec jQuery pour construire une zone de saisie semi-automatique et trouver une localisation dynamiquement

Dans cet article nous allons découvrir comment construire une zone de saisie semi-automatique avec les services REST Bing Maps en utilisant uniquement HTML, JSON et jQuery.

Les services REST Bing Maps nous permettent d’effectuer des tâches telles que la création d’une carte avec des punaises, le géocodage d’une adresse, la récupération de métadonnées des images, ou la création d’un itinéraire.

Ici, nous allons apprendre à utiliser l’API Locations des services REST Bing Maps pour construire une zone de saisie semi-automatique avec jQuery. Pour utiliser les services REST Bing Maps, vous aurez besoin d’une clé Bing Maps. Il suffit d’aller sur le Bing Maps Account Center pour en obtenir une.

 

Création

Tout d’abord, nous allons créer une simple page HTML en ajoutant les références à jQuery et jQuery UI, une zone de saisie pour la localisation recherchée et une div dans laquelle les résultats seront affichés.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Use Bing Maps REST Services with jQuery to build an autocomplete box and find a location dynamically</title>
    <script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.5.1.js" type="text/javascript"></script>
    <script src="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.10/jquery-ui.js" type="text/javascript"></script>
    <link href="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.10/themes/redmond/jquery-ui.css" rel="stylesheet" type="text/css" />
    <style type="text/css">
        #searchBox
        {
            width: 25em;
        }
    </style>
</head>
<body>
    <div>
        <div class="ui-widget">
            <label for="searchBox">
                Search:
            </label>
            <input id="searchBox" />
        </div>
        <div id="searchResult" class="ui-widget" style="margin-top: 1em;">
        </div>
    </div>
</body>
</html>

 

Pour appeler l’API Locations, nous utilisons l’adresse suivante : http://dev.virtualearth.net/REST/v1/Locations

Les paramètres qui suivent sont nécessaires pour obtenir une réponse du service :

  • query (or q) : la localisation recherchée.
  • key : est la clé Bing Maps à utiliser pour la requête (voir Bing Maps Account Center).

Les services REST Bing Maps ont également d’autres paramètres optionnels tels que :

  • userLocation (or ul) : position actuelle de l’utilisateur.
  • culture (or c) : la culture à utiliser pour la requête.
  • output (or o) : format de sortie de la réponse (JSON ou XML). JSON est utilisé par défaut.
  • jsonp : nom de la fonction callback JSON qui est appelée quand la réponse à la requête est reçue. L’objet JSON fourni dans la réponse est passé à la fonction callback.

 

Pour créer une zone de saisie semi-automatique, nous utilisons jQuery UI. La source des suggestions fournies à l’utilisateur viendra des services REST Bing Maps.

Le fonctionnement est le suivant : lorsque l’utilisateur tape une localisation, une requête Ajax est déclenchée pour appeler l’API Locations des services REST Bing Maps et une réponse JSON est reçue. La réponse est traitée pour être affichée sous forme de suggestions à l’utilisateur. Voici le code JavaScript pour obtenir ce comportement :

<script type="text/javascript">
    $(document).ready(function () {
        $("#searchBox").autocomplete({
            source: function (request, response) {
                $.ajax({
                    url: "http://dev.virtualearth.net/REST/v1/Locations",
                    dataType: "jsonp",
                    data: {
                        key: "<yourbingmapskey>",
                        q: request.term
                    },
                    jsonp: "jsonp",
                    success: function (data) {
                        var result = data.resourceSets[0];
                        if (result) {
                            if (result.estimatedTotal > 0) {
                                response($.map(result.resources, function (item) {
                                    return {
                                        data: item,
                                        label: item.name + ' (' + item.address.countryRegion + ')',
                                        value: item.name
                                    }
                                }));
                            }
                        }
                    }
                });
            },
            minLength: 1
        });
    });
</script>

 

Il faut prêter attention à plusieurs choses ici :

  • Nous indiquons à jQuery que la source de la zone de saisie semi-automatique est une requête Ajax envoyée à l’API Locations des services REST Bing Maps. Une fois la réponse à la requête reçue, la zone de saisie semi-automatique obtient des suggestions grâce au callback qui s’appelle response.
  • La requête Ajax a plusieurs paramètres :
    • url : celle de l’API Locations.
    • dataType : jsonp.
    • jsonp : s’appelle jsonp pour remplacer le nom de la fonction de callback dans la requête jsonp. Ainsi jQuery rajoute « ?jsonp=? » à la fin de l’URL pour préciser le callback. Ceci est requis par les services REST Bing Maps.
  • On obtient le terme recherché à partir du paramètre nommé request.term.
  • On vérifie que la réponses des services REST Bing Maps contient un « resource sets » et également qu’il y a des localisations qui correspondent au terme recherché (result.estimatedTotal > 0). Pour plus de détails sur la réponse des services REST Bing Maps : Common Response Description on MSDN.
  • Dans le callback response, on indique que le label de la suggestion sera le nom de la localisation plus le nom du pays, et que la valeur sera égale au nom de la localisation. On utilise également la propriété nommée data pour sauver les informations de localisations complètes afin de les réutiliser lorsque l’utilisateur aura sélectionné une localisation.

 

Par exemple, lorsqu’un utilisateur cherche « San Francisco », l’URL de requête Ajax suivante est construite et appelée :

http://dev.virtualearth.net/REST/v1/Locations?jsonp=<callbackname>&key=<yourbingmapskey>&q=San+francisco&_=1298745707161

 

La source finale de la page est la suivante :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Use Bing Maps REST Services with jQuery to build an autocomplete box and find a location dynamically</title>
    <script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.5.1.js" type="text/javascript"></script>
    <script src="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.10/jquery-ui.js" type="text/javascript"></script>
    <link href="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.10/themes/redmond/jquery-ui.css" rel="stylesheet" type="text/css" />
    <style type="text/css">
        .ui-autocomplete-loading
        {
            background: white url('images/ui-anim_basic_16x16.gif') right center no-repeat;
        }
        #searchBox
        {
            width: 25em;
        }
    </style>

    <script type="text/javascript">
        $(document).ready(function () {
            $("#searchBox").autocomplete({
                source: function (request, response) {
                    $.ajax({
                        url: "http://dev.virtualearth.net/REST/v1/Locations",
                        dataType: "jsonp",
                        data: {
                            key: "<yourbingmapskey>",
                            q: request.term
                        },
                        jsonp: "jsonp",
                        success: function (data) {
                            var result = data.resourceSets[0];
                            if (result) {
                                if (result.estimatedTotal > 0) {
                                    response($.map(result.resources, function (item) {
                                        return {
                                            data: item,
                                            label: item.name + ' (' + item.address.countryRegion + ')',
                                            value: item.name
                                        }
                                    }));
                                }
                            }
                        }
                    });
                },
                minLength: 1,
                change: function (event, ui) {
                    if (!ui.item)
                        $("#searchBox").val('');
                },
                select: function (event, ui) {
                    displaySelectedItem(ui.item.data);
                }
            });
        });

        function displaySelectedItem(item) {
            $("#searchResult").empty().append('Result: ' + item.name).append(' (Latitude: ' + item.point.coordinates[0] + ' Longitude: ' + item.point.coordinates[1] + ')');
        }
    </script>
</head>
<body>
    <div>
        <div class="ui-widget">
            <label for="searchBox">
                Search:
            </label>
            <input id="searchBox" />
        </div>
        <div id="searchResult" class="ui-widget" style="margin-top: 1em;">
        </div>
    </div>
</body>
</html>

 

Vidéo de démonstration (En anglais) 

Liens

Plusieurs liens qui vous aideront à comprendre et aller plus loin sur le sujet :

 

En résumé

Nous avons vu comment utiliser les services REST Bing Maps avec jQuery, jQuery UI pour construire une zone de saisie semi-automatique afin de trouver une localisation dynamiquement. Comme nous utilisons HTML, JSON et jQuery, cela peut être intégré avec la technologie que vous préférez.

Si vous souhaitez aller plus loin sur le sujet, regardez les liens ci-dessus pour comprendre ce que vous pouvez faire avec les services REST Bing Maps. Par exemple, nous pourrions afficher la localisation sélectionnée sur une carte avec le contrôle Bing Maps AJAX ou le contrôle Bing Maps Silverlight. Ce sera certainement le sujet d’un de mes prochains articles, en complément de celui-ci.

Vous pouvez télécharger les sources complète ici :

Télécharger les sources complètes

 

N’hésitez pas à commenter ou à me contacter si vous avez des questions à propos de cet article.