Bonnes pratiques d'utilisation des services Web de l'API Map Tiles

Les services Web Google Maps Platform sont un ensemble d'interfaces HTTP vers les services Google qui fournissent des données géographiques pour vos applications de cartographie.

Ce guide décrit certaines pratiques courantes utiles pour configurer vos requêtes de service Web et traiter les réponses du service. Consultez le guide du développeur pour obtenir la documentation complète sur l'API Map Tiles.

Qu'est-ce qu'un service Web ?

Les services Web Google Maps Platform sont une interface permettant de demander des données de l'API Google Maps à des services externes et de les utiliser dans vos applications Maps. Ces services sont conçus pour être utilisés avec une carte, conformément aux restrictions liées aux licences dans les conditions d'utilisation de Google Maps Platform.

Les services Web des API Google Maps utilisent des requêtes HTTP(S) vers des URL spécifiques, en transmettant des paramètres d'URL et/ou des données POST au format JSON en tant qu'arguments aux services. En général, ces services renvoient les données dans le corps de la réponse au format JSON pour qu'elles soient analysées et/ou traitées par votre application.

Voici un exemple de requête de service Web : une requête de métadonnées Street View, qui se présente sous la forme suivante :

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

Remarque : Toutes les applications de l'API Map Tiles nécessitent une authentification. Obtenez plus d'informations sur les identifiants d'authentification.

Accès SSL/TLS

HTTPS est requis pour toutes les requêtes Google Maps Platform qui utilisent des clés API ou contiennent des données utilisateur. Les requêtes effectuées via HTTP qui contiennent des données sensibles peuvent être rejetées.

Bon usage des Google API

Les clients d'API mal conçus peuvent imposer une charge plus importante que nécessaire sur Internet et sur les serveurs de Google. Cette section contient les bonnes pratiques pour les clients de ces API. En suivant ces bonnes pratiques, vous pouvez éviter que votre application ne soit bloquée pour utilisation abusive involontaire des API.

Intervalle exponentiel entre les tentatives

Dans de rares cas, un problème peut survenir lors du traitement de votre requête. Vous pouvez recevoir un code de réponse HTTP 4XX ou 5XX, ou la connexion TCP peut simplement échouer entre votre client et le serveur de Google. Il est souvent utile de relancer la requête, car la requête de suivi peut réussir alors que la requête d'origine a échoué. Toutefois, il est important de ne pas simplement envoyer des requêtes en boucle aux serveurs de Google. Ce comportement en boucle peut surcharger le réseau entre votre client et Google, ce qui peut entraîner des problèmes pour de nombreuses parties.

Il est préférable de réessayer en allongeant progressivement les délais entre deux tentatives. En général, le délai est augmenté d'un facteur multiplicatif à chaque tentative, une approche appelée intervalle exponentiel entre les tentatives.

Par exemple, prenons une application qui souhaite envoyer cette requête à l'API Time Zone :

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

L'exemple Python suivant montre comment effectuer la requête avec un intervalle exponentiel entre les tentatives :

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Vous devez également veiller à ce qu'il n'y ait pas de code de nouvelle tentative plus haut dans la chaîne d'appel de l'application, ce qui entraînerait des requêtes répétées à intervalles rapprochés.

Requêtes synchronisées

Un grand nombre de requêtes synchronisées vers les API de Google peut ressembler à une attaque par déni de service distribué (DDoS) sur l'infrastructure de Google et être traité en conséquence. Pour éviter cela, vous devez vous assurer que les requêtes API ne sont pas synchronisées entre les clients.

Prenons l'exemple d'une application qui affiche l'heure dans le fuseau horaire actuel. Cette application va probablement définir une alarme dans le système d'exploitation client pour le réveiller au début de la minute afin que l'heure affichée puisse être mise à jour. L'application ne doit pas effectuer d'appels d'API dans le cadre du traitement associé à cette alarme.

Effectuer des appels d'API en réponse à une alarme fixe n'est pas une bonne idée, car cela entraîne la synchronisation des appels d'API au début de la minute, même entre différents appareils, au lieu d'être répartis de manière uniforme dans le temps. Une application mal conçue qui procède ainsi produira un pic de trafic 60 fois supérieur aux niveaux normaux au début de chaque minute.

Il est recommandé d'avoir une seconde alerte définie sur une heure choisie de manière aléatoire. Lorsque cette deuxième alarme se déclenche, l'application appelle les API dont elle a besoin et stocke les résultats. Lorsque l'application souhaite mettre à jour son affichage au début de la minute, elle utilise les résultats précédemment stockés au lieu d'appeler à nouveau l'API. Avec cette approche, les appels d'API sont répartis de manière uniforme dans le temps. De plus, les appels d'API ne retardent pas l'affichage lorsque l'écran est mis à jour.

Outre le début de la minute, d'autres heures de synchronisation courantes que vous devez veiller à ne pas cibler sont le début d'une heure et le début de chaque jour à minuit.

Traitement des réponses

Cette section explique comment extraire ces valeurs de manière dynamique à partir des réponses d'un service Web.

Les services Web Google Maps fournissent des réponses faciles à comprendre, mais pas vraiment conviviales. Lorsque vous effectuez une requête, vous souhaitez probablement extraire quelques valeurs spécifiques plutôt que d'afficher un ensemble de données. En règle générale, vous devez analyser les réponses du service Web et n'extraire que les valeurs qui vous intéressent.

Le schéma d'analyse que vous utilisez dépend de la sortie que vous renvoyez au format JSON. Les réponses JSON, qui se présentent déjà sous la forme d'objets JavaScript, peuvent être traitées dans JavaScript lui-même sur le client.