Bonnes pratiques d'utilisation de l'API Maps Static

Les API Web statiques de Google Maps Platform sont un ensemble d'interfaces HTTP vers les services Google qui génèrent des images que vous pouvez intégrer directement sur votre page Web.

Ce guide décrit certaines pratiques courantes utiles pour configurer vos requêtes d'image et traiter les réponses du service. Pour obtenir la documentation complète de l'API Maps Static, consultez le guide du développeur.

Qu'est-ce qu'une API Static Web ?

Une requête API Maps Static typique se présente généralement sous la forme suivante:

  https://www.googleapis.com/staticmap/z/x/y?parameters

Remarque: Toutes les applications de l'API Maps Static 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 contenant 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 :

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 :

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.