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 des requêtes de service Web et traiter des réponses de service. Reportez-vous au guide du développeur pour obtenir la documentation complète de l'API Roads.
Qu'est-ce qu'un service Web ?
Les services Web Google Maps Platform permettent de demander des données d'API Google Maps à des services externes et d'utiliser les données dans vos applications Google Maps. Ces services sont conçus pour être utilisés avec une carte, comme indiqué dans les Restrictions relatives aux licences des 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 des services. En règle générale, ces services renvoient des données au format JSON dans la requête HTTP(S) pour que votre application les analyse et/ou les traite.
Une requête de service Web de l'API Roads se présente généralement sous la forme suivante:
https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY
où snapToRoads indique le service demandé. Les autres services Roads incluent nearestRoads et speedLimits.
Remarque: Toutes les applications de l'API Roads nécessitent une authentification. En savoir plus 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 refusées.
Créer une URL valide
Vous pensez peut-être qu'une URL "valide" va de soi, mais ce n'est pas toujours le cas. Une URL saisie dans une barre d'adresse d'un navigateur, par exemple, peut contenir des caractères spéciaux (comme "上海+中國"). Le navigateur doit alors convertir en interne ces caractères en un autre code avant de les transmettre.
De même, tout code qui génère ou accepte le format d'entrée UTF-8 peut considérer comme "valides" les URL contenant des caractères UTF-8, mais il doit convertir ces caractères avant de les envoyer à un serveur Web.
Ce processus est appelé encodage d'URL ou encodage-pourcent.
Caractères spéciaux
Nous devons convertir les caractères spéciaux, car toutes les URL doivent respecter la syntaxe de la spécification Uniform Resource Identifier (URI). En fait, les URL doivent contenir un sous-ensemble spécifique de caractères ASCII (symboles alphanumériques courants), ainsi que des caractères réservés et utilisés comme caractères de commande dans les URL. Le tableau ci-dessous récapitule ces caractères :
| Ensemble | Caractères | Utilisation de l'URL |
|---|---|---|
| Alphanumériques | a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 5 6 7 8 9 | Chaînes de texte, utilisation du schéma (http), port (8080), etc. |
| Non réservés | - _ . ~ | Chaînes de texte |
| Réservés | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Caractères de commande et/ou chaînes de texte |
Lorsque vous créez une URL valide, vous devez vous assurer qu'elle ne contient que des caractères affichés dans le tableau "Récapitulatif des caractères d'URL valides". Vérifier qu'une URL utilise ce jeu de caractères permet généralement d'identifier deux problèmes (une omission et un remplacement) :
- Les caractères que vous souhaitez utiliser ne figurent pas dans le tableau ci-dessus. Par exemple, les caractères de certaines langues étrangères (
上海+中國, par exemple) doivent être encodés à l'aide des caractères ci-dessus. Selon une pratique courante, les espaces (qui ne sont pas autorisés dans les URL) sont également souvent représentés par le caractère'+'. - Des caractères figurent dans le tableau ci-dessus comme des caractères réservés, mais doivent être utilisés littéralement.
Par exemple,
?est utilisé dans les URL pour indiquer le début de la chaîne de requête. Si vous souhaitez utiliser la chaîne "? et les Mysterions", vous devez encoder le caractère'?'.
Tous les caractères à encoder en URL le sont à l'aide du caractère '%' et d'une valeur hexadécimale à deux caractères correspondant à leur équivalent UTF-8. Par exemple, 上海+中國 au format UTF-8 serait encodé en URL sous la forme %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La chaîne ? and the Mysterians serait encodée en URL sous la forme %3F+and+the+Mysterians ou %3F%20and%20the%20Mysterians.
Caractères courants qui doivent être encodés
Voici quelques caractères courants à encoder :
| Caractère non fiable | Valeur encodée |
|---|---|
| Espace | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Convertir une URL envoyée par un utilisateur peut être difficile. Par exemple, un utilisateur peut saisir une adresse sous la forme "5&rue Longue". Généralement, vous devez créer votre URL à partir des éléments de cette adresse saisie, en traitant chaque entrée utilisateur comme des caractères littéraux.
En outre, les URL sont limitées à 8 192 caractères pour tous les services Web Google Maps Platform et les API Web statiques. Pour la plupart des services, cette limite de caractères est rarement atteinte. Notez toutefois que certains services incluent plusieurs paramètres pouvant accroître la longueur des URL.
Bon usage des Google API
Les clients API mal conçus peuvent placer plus de charge que nécessaire sur Internet et sur les serveurs de Google. Cette section contient les bonnes pratiques pour les clients de ces API. Le respect de ces bonnes pratiques peut vous aider à éviter que votre application soit bloquée par utilisation abusive des API.
Retrait exponentiel
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 celle-ci peut aboutir lorsque la requête d'origine a échoué. Cependant, il est important de ne pas simplement faire une boucle sur les requêtes envoyées aux serveurs de Google. Ce comportement en boucle peut surcharger le réseau entre votre client et Google, ce qui peut poser des problèmes à de nombreuses parties.
Il est préférable de réessayer en allongeant progressivement les délais entre deux tentatives. Généralement, le délai est augmenté d'un facteur multiplicatif à chaque tentative, ce qui correspond à un intervalle exponentiel entre les tentatives.
Prenons l'exemple d'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×tamp=1331161200&key=YOUR_API_KEY
L'exemple Python suivant illustre comment effectuer la requête avec le retrait exponentiel :
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}")
Assurez-vous également qu'il n'y a pas de nouvelle tentative de code plus haut dans la chaîne d'appel d'application qui entraîne des requêtes répétées successives et rapides.
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, assurez-vous 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 définira probablement une alarme dans le système d'exploitation client pour la 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 est déconseillé, car les appels d'API sont synchronisés au début de la minute, même entre différents appareils, au lieu d'être distribués uniformément au fil du temps. Ainsi, une application mal conçue génère un pic de trafic à 60 fois le niveau normal 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 stockés précédemment plutôt que d'appeler à nouveau l'API. Avec cette approche, les appels d'API sont répartis uniformément dans le temps. De plus, les appels d'API ne retardent pas l'affichage lorsque l'affichage est mis à jour.
Hormis le début de la minute, les autres heures de synchronisation que vous devez veiller à ne pas cibler sont celles du début d'une heure et du début de chaque journée à 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 qui ne sont pas exactement conviviales. Lorsque vous exécutez une requête, plutôt que d'afficher un ensemble de données, vous souhaiterez probablement extraire quelques valeurs spécifiques. En règle générale, vous souhaitez analyser les réponses du service Web et extraire uniquement les valeurs qui vous intéressent.
Le schéma d'analyse que vous utilisez varie selon que vous renvoyez une sortie au format JSON ou non. Les réponses JSON, étant déjà sous forme d'objets JavaScript, peuvent être traitées directement dans JavaScript sur le client.