Les API Web statiques de Google Maps Platform sont un ensemble d'interfaces HTTP qui génèrent des images à intégrer directement sur votre page Web.
Les services Web Google Maps Platform sont un ensemble d'interfaces HTTP 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 d'images et de services Web, et traiter les réponses des services. Pour en savoir plus sur l'API Street View Static, consultez le guide du développeur.
L'API Street View Static agit comme une API Web statique, tandis que le service de métadonnées agit comme un service Web. Pour en savoir plus sur le service de métadonnées, consultez Métadonnées d'image Street View.
Qu'est-ce qu'une API Web statique ?
Les API Web statiques de Google Maps Platform vous permettent d'intégrer une image Google Maps à votre page Web sans avoir besoin de JavaScript ni de chargement de page dynamique. Les API Web statiques créent une image basée sur les paramètres d'URL envoyés à l'aide d'une requête HTTPS standard.
Une requête API Street View Static standard se présente sous la forme suivante :
https://www.googleapis.com/streetview/z/x/y?parameters
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 ou HTTPS vers des URL spécifiques, en transmettant des paramètres d'URL ou des données POST au format JSON en tant qu'arguments aux services. En règle générale, ces services renvoient des données dans le corps de la réponse au format JSON pour l'analyse ou le traitement par votre application.
Une requête de métadonnées de l'API Street View Static se présente sous la forme suivante :
https://maps.googleapis.com/maps/api/streetview/parameters
Accès SSL et 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 :
| Jeu de | caractères | Utilisation de l'URL |
|---|---|---|
| Alphanumérique | 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 4 5 6 7 8 9 | Chaînes de texte, utilisation du schéma (http), port (8080), etc. |
| Non réservé | - _ . ~ | Chaînes de texte |
| Réservé | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | 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. 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 à 16 384 caractères pour tous les services Web Google Maps Platform et les API Web statiques. Pour la plupart des services, ce nombre maximal de caractères est rarement atteint. Notez toutefois que certains services incluent plusieurs paramètres pouvant accroître la longueur des URL.
Utilisation polie des API Google
Les clients API mal conçus peuvent imposer des charges importantes sur Internet et sur les serveurs. Cette section contient les bonnes pratiques pour les clients API. Ces bonnes pratiques peuvent vous aider à é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 avec votre requête. Vous pouvez recevoir un code de réponse HTTP 4xx ou 5xx, ou la connexion TCP peut é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 envoyer de requêtes répétées 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. Le délai augmente généralement d'un facteur multiplicatif à chaque tentative, une approche appelée intervalle exponentiel entre les tentatives.
Prenons l'exemple d'une application qui envoie 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_KEYL'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 in the following code 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 the request didn't produce an IOError, parse the result. result = json.load(response) if result["status"] == "OK": return result["timeZoneId"] elif result["status"] != "UNKNOWN_ERROR": # Many API errors can't be fixed by a retry, such as # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry. if __name__ == "__main__": tz = timezone(39.6034810, -119.6822510, 1331161200) print(f"Timezone: {tz}")
Assurez-vous qu'il n'y a pas de code de nouvelle tentative plus haut dans la chaîne d'appel de l'application qui entraîne 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 ce problème, 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éfinit probablement une alarme dans le système d'exploitation client pour le réactiver au début de la minute afin que l'heure affichée puisse être mise à jour. N'effectuez aucun appel d'API dans l'application 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, plutôt que leur répartition uniforme dans le temps. Une application mal conçue qui procède de cette manière génère un pic de trafic 60 fois supérieur aux niveaux normaux au début de chaque minute.
Vous pouvez plutôt concevoir l'application de sorte qu'une deuxième alarme soit définie à 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 met à 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.
En dehors du début de la minute, ne ciblez pas d'autres heures de synchronisation courantes, telles que le début d'une heure et le début de chaque jour à minuit.
Traiter les réponses
Étant donné que le format exact des réponses individuelles à une requête de service Web n'est pas garanti (certains éléments peuvent être manquants ou se trouver à plusieurs emplacements), ne partez pas du principe que le format renvoyé pour une réponse donnée est le même pour différentes requêtes. Traitez plutôt la réponse et sélectionnez les valeurs appropriées à l'aide d'expressions.
Cette section explique comment extraire ces valeurs de manière dynamique à partir des réponses des services Web.
Les services Web Google Maps fournissent des réponses compréhensibles, mais pas 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, analysez les réponses du service Web et n'extrayez que les valeurs qui vous intéressent.
Le schéma d'analyse que vous utilisez dépend de la façon dont vous renvoyez la sortie 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.