Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Static Maps API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Static Maps API
  3. Créer les clés appropriées
Continuer

Guide du développeur Google Static Maps

Google Static Maps API vous permet d'intégrer une image Google Maps à votre page Web sans JavaScript ni chargement de page dynamique. Le service Google Static Maps API crée votre carte en fonction de paramètres URL envoyés via une requête HTTP standard et retourne une carte sous forme d'image que vous pouvez afficher sur votre page Web.

Remarque : Les limites d'utilisation de Google Static Maps API ont changé. La création d'une clé d'API et son inclusion dans votre requête vous permettent de suivre l'utilisation dans Google API Console et d'acheter un quota supplémentaire si nécessaire.

Le présent document détaille Google Static Maps API version 2. Pour mettre à jour vos URL version 1, veuillez consulter le guide de mise à niveau.

Un bref exemple

L'exemple suivant contient l'URL d'une image Google Static Maps API du centre-ville de New York, affichée ci-dessous :

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

Points d'intérêt à Lower Manhattan

Notez que vous ne devez rien faire de « spécial » pour afficher cette image sur la page. JavaScript n'est pas nécessaire. Il suffit de créer une URL et de la placer à l'intérieur d'une balise <img>. Vous pouvez insérer Google Google Static Maps API à n'importe quel endroit de votre page Web où vous pouvez insérer une image.

Public ciblé

Le présent document est destiné aux développeurs de sites Web et d'applications mobiles qui souhaitent inclure des images Google Static Maps API dans une page Web ou une application mobile. Il contient une introduction à l'utilisation de cette API et des références sur les paramètres disponibles.

Présentation

Google Static Maps API renvoie une image (GIF, PNG ou JPEG) en réponse à une requête HTTP via une URL. Pour chaque requête, vous pouvez spécifier l'emplacement de la carte, la taille de l'image, le niveau de zoom, le type de carte et l'inclusion de marqueurs facultatifs sur certains points de la carte. Vous pouvez également libeller vos marqueurs en utilisant des caractères alphanumériques.

Une image Google Static Maps API est intégrée dans l'attribut src d'une balise <img> ou son équivalent dans d'autres langages de programmation. Si une image Google Static Maps API est utilisée en dehors d'une application Web (comme un navigateur), il est nécessaire d'inclure un lien pointant vers le lieu affiché dans un navigateur Web ou une application Google Maps native (ceci n'est pas obligatoire pour les utilisateurs de Google Maps APIs Premium Plan). Reportez-vous aux Conditions de service de Google Maps/Google Earth, section 10.1.1(h), pour consulter le langage complet et actuel concernant cette obligation.

Ce document décrit le format requis pour les URL de Google Static Maps API et les paramètres disponibles. Il contient également des trucs et astuces pour la spécification d'URL.

Paramètres d'URL

Les URL de Google Static Maps API doivent respecter le format suivant :

https://maps.googleapis.com/maps/api/staticmap?parameters

Si l'on accède à votre site Web via HTTPS, vous devez charger les images Google Static Maps API via HTTPS également afin d'éviter les alertes de sécurité du navigateur. HTTPS est également recommandé si vos requêtes incluent des informations sur l'utilisateur, comme sa position géographique :

https://maps.googleapis.com/maps/api/staticmap?parameters

Que vous utilisiez HTTP ou HTTPS, certains paramètres d'URL sont obligatoires alors que d'autres sont facultatifs. Comme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&). Vous trouverez ci-dessous la liste des paramètres et leurs différentes valeurs possibles.

Important : Dans un souci de clarté, la description des paramètres d'URL ci-dessous contient des exemples donnés avant l'utilisation de caractères d'échappement. Avant d'envoyer une requête à l'API, ses paramètres doivent être correctement codés en URL. Par exemple, de nombreux paramètres utilisent la barre verticale (|) comme séparateur. Celle-ci doit être encodée en %7C dans l'URL finale, comme dans le bref exemple en haut de ce document. Pour plus d'informations, voir Création d'une URL valide.

Google Static Maps API définit les images de carte à l'aide des paramètres d'URL suivants :

Paramètres de point géographique

  • center (obligatoire en l'absence de marqueurs) définit le centre de la carte, équidistant de tous les bords de celle-ci. Ce paramètre nécessite un point géographique, sous la forme d'une paire {latitude,longitude} séparée par une virgule (par exemple, « 40.714728,-73.998672 ») ou d'une chaîne d'adresse (par ex., « city hall, new york, ny ») identifiant un point géographique unique sur la surface de la Terre. Pour plus d'informations, voir Points géographiques ci-dessous.
  • zoom (obligatoire en l'absence de marqueurs) définit le niveau de zoom de la carte, qui détermine son degré de grossissement. Ce paramètre nécessite une valeur numérique correspondant au niveau de zoom sur la région souhaitée. Pour plus d'informations, voir les niveaux de zoom ci-dessous.

Paramètres de carte

  • size (obligatoire) définit les dimensions rectangulaires de l'image de la carte. Ce paramètre nécessite une chaîne de type {horizontal_value}x{vertical_value}. Par exemple, 500x400 définit une carte de 500 pixels de largeur sur 400 pixels de hauteur. Les cartes dont la largeur est inférieure à 180 pixels affichent un logo Google de taille réduite. Ce paramètre est sensible au paramètre scale, décrit ci-dessous. La taille du résultat final est le produit des valeurs de taille et d'échelle.
  • scale (facultatif) a un impact sur le nombre de pixels renvoyés. scale=2 renvoie deux fois plus de pixels que scale=1 tout en conservant la même zone de couverture et le même niveau de détail (le contenu de la carte reste inchangé). Cela est utile pour le développement destiné aux écrans haute résolution ou pour la création d'une carte destinée à l'impression. La valeur par défaut est 1. Les valeurs acceptées sont 2 et 4 (4 est uniquement disponible pour les clients Google Maps APIs Premium Plan). Pour plus d'informations, voir Valeurs d'échelle.
  • format (facultatif) définit le format de l'image obtenue. Par défaut, Google Static Maps API crée des images PNG. Plusieurs formats sont possibles, dont les types GIF, JPEG et PNG. Le format à utiliser dépend de la manière dont vous voulez présenter l'image. JPEG offre généralement une meilleure compression, alors que GIF et PNG fournissent plus de détails. Pour plus d'informations, voir Formats d'image.
  • maptype (facultatif) définit le type de carte à créer. Plusieurs valeurs de type de carte sont possibles, dont roadmap, satellite, hybrid et terrain. Pour plus d'informations, voir Types de carte Google Static Maps API ci-dessous.
  • language (facultatif) définit la langue à utiliser pour l'affichage de libellés sur les tuiles de carte. Notez que ce paramètre est uniquement pris en charge pour certaines tuiles de pays. Si la langue demandée n'est pas prise en charge pour l'ensemble des tuiles, c'est la langue par défaut de cet ensemble de tuiles qui est utilisée.
  • region (facultatif) définit les frontières à afficher, en fonction des sensibilités géopolitiques. Accepte un code de région spécifié sous forme de valeur ccTLD (domaine de premier niveau) à deux caractères.

Paramètres de composant

  • markers (facultatif) définit un ou plusieurs marqueurs devant apparaître sur l'image à des points géographiques spécifiques. Ce paramètre nécessite une définition de marqueur unique avec des paramètres séparés par une barre verticale (|). Plusieurs marqueurs peuvent être placés au sein du même paramètre markers à condition de présenter le même style. Vous pouvez ajouter des marqueurs de styles différents en ajoutant des paramètres markers supplémentaires. Notez que si vous fournissez des marqueurs pour une carte, il n'est pas nécessaire de spécifier les paramètres center et zoom (normalement obligatoires). Pour plus d'informations, voir Marqueurs de Google Static Maps API ci-dessous.
  • path (facultatif) définit un tracé unique reliant plusieurs points connectés à superposer sur l'image aux points géographiques spécifiés. Ce paramètre nécessite une chaîne de définitions de points séparées par une barre verticale (|). Vous pouvez définir des tracés supplémentaires en ajoutant d'autres paramètres path. Notez que si vous définissez un tracé pour une carte, il n'est pas nécessaire de spécifier les paramètres center et zoom (normalement obligatoires). Pour plus d'informations, voir Tracés de Google Static Maps API ci-dessous.
  • visible (facultatif) spécifie un ou plusieurs points géographiques devant rester visibles sur la carte, même si aucun marqueur ni indicateur n'est affiché. Utilisez ce paramètre pour vous assurer que certains éléments ou certains points géographiques soient affichés sur Google Static Maps API.
  • style (facultatif) définit un style personnalisé pour modifier la présentation d'un composant spécifique (route ou parc, par exemple) sur la carte. Ce paramètre nécessite des arguments feature et element identifiant les composants à styliser, ainsi qu'un ensemble d'opérations de style à appliquer aux composants sélectionnés. Vous pouvez définir plusieurs styles en ajoutant des paramètres style supplémentaires. Pour plus d'informations, voir le guide sur les cartes stylisées.

Paramètres de clé et de signature

  • key (obligatoire) vous permet de surveiller l'utilisation de l'API par votre application dans la Google API Console et d'accéder à un généreux quota journalier gratuit. Ce paramètre permet également à Google de vous contacter à propos de votre application, le cas échéant. Pour plus d'informations, voir Obtenir une clé et une signature.
  • signature (recommandé) est une signature numérique utilisée pour vérifier que tous les sites qui génèrent des requêtes à l'aide de votre clé d'API sont autorisés à le faire. Remarque : Si vous activez la facturation, la signature numérique est obligatoire. Si vous dépassez la limite journalière gratuite de chargements de cartes, les chargements supplémentaires seront facturables pour le reste de la journée. Les chargements de cartes n'incluant aucune signature numérique ne seront pas exécutés. Pour plus d'informations, voir Obtenir une clé et une signature.

Remarque : les clients Google Maps APIs Premium Plan peuvent utiliser soit une clé d'API avec signature numérique, soit un ID client valide avec signature numérique dans leurs requêtes Static Maps. En savoir plus sur les paramètres d'authentification des clients Premium Plan.

Les clients ayant une licence Google Maps APIs for Work antérieure doivent inclure des paramètres client et signature valides plutôt qu'un paramètre key dans leurs requêtes. Pour plus d'informations, voir la section ID client et signatures de la page Obtenir une clé et une signature.

Restriction de taille d'URL

Les URL de Google Static Maps API sont limitées à 8 192 caractères. Dans la pratique, vous n'avez pas besoin d'URL plus longues, à moins de créer des cartes compliquées comprenant un grand nombre de marqueurs et de tracés. Notez cependant que certains caractères peuvent être codés en URL par des navigateurs et/ou des services avant leur envoi à l'API, ce qui entraîne une plus grande utilisation de caractères. Pour plus d'informations, reportez-vous à la section Création d'une URL valide.

Utilisation des paramètres

Google Static Maps API est relativement simple à utiliser, car elle se compose simplement d'une URL paramétrée. Cette section vous explique comment utiliser ces paramètres afin de créer vos URL.

Spécification des points géographiques

Google Static Maps API doit pouvoir identifier précisément des points géographiques sur la carte, pour centrer la carte sur le point géographique correct (à l'aide du paramètre center) et/ou pour placer des repères facultatif (à l'aide du paramètre markers) sur certains points de la carte. Google Static Maps API utilise des nombres (valeurs de latitude et de longitude) ou des chaînes (adresses) pour spécifier ces points géographiques. Ces valeurs identifient un point géographique géocodé.

Plusieurs paramètres (comme les paramètres markers et path) nécessitent plusieurs points géographiques. Dans ce cas, les points géographiques sont séparés par une barre verticale (|).

Latitudes et longitudes

Les latitudes et les longitudes sont définies à l'aide de chiffres au sein d'une chaîne de texte séparée par des virgules, avec une précision de 6 décimales. Par exemple, « 40.714728,-73.998672 » est une valeur géocodée valide. La précision au-delà de 6 décimales est ignorée.

Les valeurs de longitude se basent sur la distance à partir du méridien de Greenwich en Angleterre. Greenwich étant situé à une latitude de 51.477222, nous pouvons entrer une valeur center de 51.477222,0 afin de centrer la carte sur Greenwich :

Greenwich, Angleterre

Les valeurs de latitude et de longitude doivent correspondre à un point géographique valide sur la surface de la Terre. Les latitudes doivent être comprises entre les valeurs -90 et 90 ; les longitudes entre les valeurs -180 et 180. Si vous spécifiez une valeur de latitude ou de longitude non valide, votre requête est rejetée.

Adresses

La plupart des personnes ne parlent pas en termes de latitudes et de longitudes. Elles indiquent des points géographiques grâce à des adresses. Le processus de conversion d'une adresse en point géographique est appelé géocodage et le service Google Static Maps API peut se charger de géocoder les adresses valides que vous lui fournissez.

Dans tout paramètre où vous pouvez fournir une latitude/longitude, il est possible de spécifier une chaîne indiquant une adresse. Google géocode l'adresse et fournit au service Google Static Maps API une valeur de latitude/longitude à utiliser pour le placement de marqueurs ou la spécification de points géographiques. La chaîne doit utiliser des caractères d'échappement d'URL afin qu'une adresse comme « City Hall, New York, NY » soit convertie en « City+Hall,New+York,NY », par exemple.

Notez que les adresses peuvent représenter des points géographiques précis, comme des adresses postales, des polylignes comme des routes dotées d'un nom ou des zones polygonales comme des villes, des pays ou des parcs nationaux. Pour fournir des résultats polylinéaires et polygonaux, le serveur Google Static Maps API utilise le point central de la ligne/zone comme centre de l'adresse. En cas de doute sur le résultat du géocodage d'une adresse, vous pouvez tester l'adresse à l'aide de cet Utilitaire de géocodage.

L'exemple suivant génère une Google Static Maps API pour Berkeley (Californie) :

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

Berkeley (Californie)

Niveaux de zoom

Les cartes de Google Maps ont un « niveau de zoom » entier qui définit leur résolution dans la vue actuelle. Les niveaux de zoom compris entre 0 (niveau de zoom le plus faible permettant d'afficher le monde entier sur une même carte) et 21+ (précision des rues et bâtiments individuels) sont possibles dans la vue roadmap par défaut. Lorsqu'ils sont disponibles, les contours des bâtiments apparaissent sur la carte vers le niveau de zoom 17. Cette valeur diffère selon la zone et peut être modifiée à mesure de l'évolution des données.

Google Maps définit le niveau de zoom à 0 pour englober la Terre entière. Chaque niveau de zoom successif double la précision des dimensions horizontales et verticales. D'autres informations sur le fonctionnement des niveaux de zoom sont disponibles dans la documentation de Google Maps JavaScript API.

Remarque : les niveaux de zoom ne sont pas tous disponibles pour tous les points géographiques sur Terre. Les niveaux de zoom varient selon le point géographique, car les données dans certaines parties du globe sont moins précises.

Si vous envoyez une requête de niveau de zoom pour lequel aucune tuile de carte n'est disponible, Google Static Maps API renvoie une carte affichant le niveau de zoom maximum disponible pour ce point géographique.

La liste suivante indique le niveau de détail approximatif que vous pouvez vous attendre à voir à chaque niveau de zoom :

  • 1 : Le monde
  • 5 : La masse continentale/le continent
  • 10 : Ville
  • 15 : Rues
  • 20 : Immeubles

L'exemple ci-dessous est une requête de deux cartes de Manhattan avec la même valeur center mais un niveau de zoom de 12 et de 14, respectivement :

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

Manhattan éloigné  Manhattan rapproché

Tailles des images

Le paramètre size, combiné à center, définit la zone de couverture d'une carte. Il définit également la taille de sortie de la carte en pixels, lorsqu'elle est multipliée par la valeur scale (1 par défaut).

Le tableau ci-dessous présente les valeurs maximales autorisées du paramètre size pour chaque valeur scale.

API scale=1 scale=2 scale=4
Gratuite 640x640 640x640 (renvoie 1280x1280 pixels) Non disponible.
Google Maps APIs Premium Plan 2048x2048 1024x1024 (renvoie 2048x2048 pixels) 512x512 (renvoie 2048x2048 pixels)

L'exemple ci-dessous est la requête d'une « tranche » de la Terre au niveau de l'équateur, avec un niveau de zoom 1 :

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

Équateur

L'exemple ci-dessous est la requête d'une petite carte, d'une taille de 100 x 100 pixels, centrée sur la même région. Remarquez le logo Google de plus petite taille :

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

Petite carte de l'équateur

Valeurs d'échelle

Le paramètre size de Google Static Maps API définit la taille d'une carte en pixels, de sorte qu'une carte de size=200x200 soit affichée sur 200 pixels par 200 pixels. Sur un moniteur d'ordinateur LCD, qui affiche généralement 100 pixels par pouce (ppp), une carte de 200x200 mesure environ 2 pouces sur 2.

Cependant, les appareils mobiles sont de plus en plus équipés d'écrans haute résolution avec des densités de pixels supérieures à 300 ppp, ce qui :

  • Réduit la taille d'une image de 200x200 pixels à 0,7 pouce seulement, rendant les libellés et les icônes trop petits pour être lisibles ; ou
  • Met votre image à l'échelle (effectue un zoom) pour amélioré la lisibilité, ce qui crée une image floue ou pixellisée.
Trop petite Trop floue

Lorsque vous développez pour des appareils mobiles, utilisez le paramètre scale de l'API pour renvoyer des images de carte à plus haute résolution afin d'éviter les problèmes ci-dessus. La valeur scale est multipliée par size pour déterminer la taille de sortie réelle de l'image en pixels, sans modifier la zone de couverture de la carte. (La valeur scale par défaut est 1 ; les valeurs acceptées sont 1, 2 et, pour les clients Google Maps APIs Premium Plan uniquement, 4.)

Par exemple, une valeur d'échelle de 2 affiche la même couverture de carte qu'une requête sans échelle spécifiée, mais avec deux fois plus de pixels en hauteur et en largeur. Cela concerne également les routes et les libellés afin qu'ils soient lisibles en haute résolution sur des écrans de petite taille, et lorsqu'ils sont mis à l'échelle par le navigateur.

150x150 150x150&scale=2

Cette même image donne également un bon résultat dans les navigateurs d'ordinateurs de bureau, lorsqu'elle est insérée dans une balise img ou div et que sa hauteur et sa largeur sont définies à l'aide de CSS. Le navigateur réduit l'image à la bonne taille, sans perte de qualité.

Le tableau ci-dessous montre trois requêtes d'image différentes.

  • La première est une image 100x100, sans valeur d'échelle spécifiée. Elle s'affiche correctement sur un ordinateur de bureau, mais s'avère trop petite pour être lisible sur un appareil mobile.
  • La deuxième requête double la taille de la carte. Sur l'ordinateur de bureau, le CSS place l'image dans l'élément img 100x100 spécifié, mais en la réduisant, les routes et les libellés deviennent trop petits. Sur l'appareil mobile, l'image est de la bonne taille, mais ici aussi les routes et les libellés sont illisibles.
  • La troisième requête correspond à une carte de 100x100 avec scale=2. L'image est affichée avec 200 pixels de détails. L'ordinateur de bureau la réduit parfaitement et la rend identique à la requête 100x100 d'origine, alors que le navigateur mobile bénéficie de la résolution supplémentaire renvoyée par l'API.
Appareil 100x100 200x200 100x100&scale=2
Ordinateur de bureau
(avec height="100px" et
width="100px" dans
la balise img)
Haute résolution
(simulée)

Astuce : Les plateformes mobiles, comme Android et iOS, permettent aux applications de prendre en charge des écrans haute résolution en spécifiant des images séparées pour chaque résolution. Le paramètre d'échelle facilite la requête d'une image de carte pour un écran de résolution standard et la carte correspondante pour un écran haute résolution, simplement en définissant scale=1 et scale=2, respectivement.

Pour plus d'informations sur le développement pour les écrans d'appareils mobiles et haute résolution, nous vous recommandons de lire les ressources suivantes :

Formats d'image

Les images peuvent être renvoyées dans plusieurs formats graphiques Web courants : GIF, JPEG et PNG. Le paramètre format nécessite l'une des valeurs suivantes :

  • png8 ou png (par défaut) spécifie le format PNG 8 bits.
  • png32 spécifie le format PNG 32 bits.
  • gif spécifie le format GIF.
  • jpg spécifie le format de compression JPEG.
  • jpg-baseline spécifie un format de compression JPEG non progressif.

jpg et jpg-baseline permettent généralement d'obtenir la plus petite taille d'image, mais leur compression entraîne des pertes qui peuvent dégrader sa qualité. gif, png8 et png32 fournissent une compression sans perte.

La plupart des images JPEG sont progressives, ce qui signifie qu'une image grossière est d'abord chargée, et qu'ensuite la résolution de l'image est affinée à mesure que d'autres données arrivent. Cela permet de charger rapidement des images sur des pages Web et il s'agit de l'utilisation la plus étendue du format JPEG actuellement. Cependant, certaines utilisations de JPEG (notamment l'impression) nécessitent des images non progressives (de base). Dans ce cas, il est recommandé d'utiliser le format jpg-baseline, qui est non progressif.

Types de carte

Google Static Maps API crée des cartes dans les différents formats ci-dessous :

  • roadmap (par défaut) spécifie une image de carte routière standard, telle qu'affichée normalement sur le site Web de Google Maps. Si aucune valeur maptype n'est spécifiée, Google Static Maps API retourne des tuiles roadmap par défaut.
  • satellite spécifie une image de satellite.
  • terrain spécifie une image de carte de relief physique, affichant l'orographie et la végétation.
  • hybrid spécifie un hybride de l'image de carte routière et satellite, affichant une couche transparente des principales rues et des principaux noms de lieu sur l'image satellite.

Vous pouvez voir la différence entre les types « roadmap  » et « terrain » dans l'exemple de code ci-dessous.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

Carte normale de Manhattan  Carte physique de Manhattan

Les cartes hybrides utilisent des images satellite et les principaux composants des cartes routières afin de créer une carte combinée. Les exemples suivants montrent des types de carte « satellite » et « hybrid » :

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

Carte satellite de Manhattan  Carte physique de Manhattan

Cartes stylisées

Voir le guide sur les cartes stylisées.

Marqueurs

Le paramètre markers définit un ensemble d'un ou de plusieurs marqueurs situés sur un ensemble de points géographiques. Chaque marqueur défini dans une déclaration markers unique doit présenter le même style visuel ; si vous souhaitez afficher des marqueurs avec différents styles, vous devez fournir plusieurs paramètres markers associés à des informations de style séparées.

Le paramètre markers nécessite un ensemble d'affectations de valeur (descripteurs de marqueur) au format suivant :

markers=markerStyles|markerLocation1| markerLocation2|... etc.

L'ensemble de markerStyles est spécifié au début de la déclaration de markers et se compose d'aucun ou d'un certain nombre de descripteurs de style séparés par une barre verticale (|), suivis d'un ensemble d'un ou de plusieurs points géographiques également séparés par une barre verticale (|).

Les informations de style et les informations de point géographique étant délimitées par des barres verticales, les informations de style doivent apparaître en premier dans tout descripteur de marqueur. Dès que le serveur Google Static Maps API trouve un point géographique dans le descripteur de marqueur, il considère que tous les autres paramètres de marqueur sont également des points géographiques.

Styles de marqueur

L'ensemble des descripteurs de style de marqueur correspond à une série d'affectations de valeurs séparées par une barre verticale (|). Ce descripteur de style définit les attributs visuels à utiliser pour l'affichage des marqueurs de ce descripteur de marqueur. Ces descripteurs de style contiennent les affectations de clé/valeur suivantes :

  • size: (facultatif) spécifie la taille du marqueur à partir de l'ensemble {tiny, mid, small}. Si aucun paramètre size n'est défini, le marqueur apparaît dans sa taille par défaut (normale).
  • color: (facultatif) spécifie une couleur 24 bits (exemple : color=0xFFFFCC) ou une couleur prédéfinie à partir de l'ensemble {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Notez que les transparences (spécifiées à l'aide de valeurs de couleur hexadécimales 32 bits) ne sont pas prises en charge dans les marqueurs, bien qu'elles soient prises en charge pour les tracés.

  • label: (facultatif) spécifie un seul caractère alphanumérique en majuscule à partir de l'ensemble {A-Z, 0-9}. (L'obligation de caractères en majuscules est une nouveauté de cette version de l'API.) Notez que les marqueurs par défaut et de taille mid (moyenne) sont les seuls marqueurs capables d'afficher un paramètre alphanumeric-character. Les marqueurs tiny et small ne sont pas capables d'afficher de caractères alphanumériques.

Remarque : au lieu d'utiliser ces marqueurs, vous pouvez utiliser votre propre icône personnalisée. (Pour plus d'informations, voir Icônes personnalisées ci-dessous.)

Points géographiques de marqueur

Chaque descripteur de marqueur doit contenir un ensemble d'un ou de plusieurs points géographiques définissant l'emplacement du marqueur sur la carte. Ces points géographiques peuvent être spécifiés sous forme de valeurs de latitude/longitude ou en tant qu'adresses. Ces points géographiques sont séparés par une barre verticale (|).

Les paramètres de point géographique définissent l'emplacement du marqueur sur la carte. Si le point géographique se trouve hors de la carte et que les paramètres center et zoom sont fournis, ce marqueur n'apparaît pas dans l'image créée. En revanche, si ces paramètres ne sont pas précisés, le serveur Google Static Maps API crée automatiquement une image contenant les marqueurs fournis. (Voir Positionnement implicite ci-dessous.)

Un exemple de déclaration de marqueur est illustré ci-dessous. Notez qu'un ensemble de style et trois points géographiques sont définis :

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

Trois codes postaux de Brooklyn

Pour définir des marqueurs avec différents styles, il est nécessaire de fournir plusieurs paramètres markers. L'ensemble de paramètres markers définit trois marqueurs : un marqueur bleu libellé « S » à 62.107733, -145.5419, un très petit marqueur vert à « Delta Junction, Alaska » et un marqueur moyen jaune libellé « C » à « Tok, Alaska ». Ces marqueurs sont présentés dans l'exemple ci-dessous :

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

Trois villes d'Alaska, différents marqueurs

Icônes personnalisées

Vous êtes libre d'utiliser vos icônes personnalisées au lieu des icônes de marqueur de Google. Les icônes personnalisées sont spécifiées à l'aide du descripteur suivant pour le paramètre markers :

  • icon spécifie une URL à utiliser comme icône personnalisée de marqueur. Les images peuvent être au format PNG, JPEG ou GIF ; le format PNG est recommandé.

Le paramètre icon doit être spécifié à l'aide d'une URL (qui doit être codée en URL). Vous pouvez utiliser les URL créées par des services de raccourcissement d'URL, comme https://goo.gl. La plupart des services de raccourcissement d'URL présentent l'avantage d'encoder automatiquement les URL. Les icônes sont limitées à une taille de 4 096 pixels (64x64 pour les images carrées) et le service Google Static Maps API autorise jusqu'à cinq icônes personnalisées uniques par requête. Notez que chacune de ces icônes uniques peut être utilisée à plusieurs reprises dans Google Static Maps API.

Le point d'ancrage d'une icône personnalisée est défini comme centre inférieur de l'image.

L'exemple suivant utilise Google Chart API pour créer des marqueurs personnalisés, indiquant plusieurs cafés à New York :

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Cafés à Manhattan

Remarque : Les différents niveaux d'échappement ci-dessus peuvent prêter à confusion. Google Chart API utilise la barre verticale (|) pour délimiter les chaînes dans ses paramètres d'URL. Comme ce caractère n'est pas permis dans une URL (voir la remarque ci-dessus), lorsque vous créez une URL de graphique complètement valide, elle est échappée en %7C. Le résultat est une chaîne dans une spécification icon, mais il contient un caractère % (du %7C cité ci-avant), qui ne peut pas être inclus directement sous forme de données dans une URL et doit être échappé en %25. Il en résulte que l'URL contient %257C, ce qui représente deux couches d'encodage. De même, l'URL de graphique contient un caractère &, qui ne peut pas être inclus directement sans être confondu avec un séparateur pour les paramètres d'URL de Google Static Maps API. Il doit donc lui aussi être encodé.

Voici les étapes de la création de l'URL Google Static Maps API :

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Tracés Google Static Maps API

Le paramètre path définit un ensemble d'un ou de plusieurs points géographiques reliés par un tracé à superposer sur l'image de la carte. Le paramètre path nécessite un ensemble d'affectations de valeur (descripteurs de tracé) au format suivant :

path=pathStyles|pathLocation1|pathLocation2|... etc.

Notez que ces points de tracé sont séparés par une barre verticale (|). Les informations de style et les informations de point étant délimitées par des barres verticales, les informations de style doivent apparaître en premier dans tout descripteur de tracé. Dès que le serveur Google Static Maps API trouve un point géographique dans le descripteur de tracé, il considère que tous les autres paramètres de tracé sont également des points géographiques.

Styles de tracé

L'ensemble des descripteurs de style de tracé est une série d'affectations de valeurs séparées par une barre verticale (|). Ce descripteur de style définit les attributs visuels à utiliser pour l'affichage du tracé. Ces descripteurs de style contiennent les affectations de clé/valeur suivantes :

  • weight: (facultatif) spécifie l'épaisseur du tracé en pixels. Si aucun paramètre weight n'est défini, le marqueur est affiché avec son épaisseur par défaut (5 pixels).
  • color: (facultatif) spécifie une couleur sous forme de valeur hexadécimale 24 bits (exemple : color=0xFFFFCC) ou 32 bits (exemple : color=0xFFFFCCFF), ou encore à partir de l'ensemble {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Lorsqu'une valeur hexadécimale est spécifiée, les deux derniers caractères spécifient la valeur de transparence alpha 8 bits. Cette valeur varie entre 00 (complètement transparent) et FF (complètement opaque). Notez que les transparences sont prises en charge dans les tracés, bien qu'elles ne soient pas prises en charge pour les marqueurs.

  • fillcolor: (facultatif) indique que le tracé délimite une zone polygonale et spécifie la couleur de remplissage à superposer dans cette zone. L'ensemble de points géographiques qui suivent ne doit pas former une boucle « fermée » ; le serveur Google Static Maps API relie automatiquement le premier et le dernier point. Notez, cependant, que tout trait situé à l'extérieur de la zone remplie ne sera pas fermé, à moins que vous fournissiez spécifiquement le même emplacement de début et de fin.
  • geodesic: (facultatif) indique que le tracé demandé doit être interprété comme une ligne géodésique qui suit la courbure de la Terre. Si cette valeur est « false », le tracé est affiché sous forme de ligne droite dans l'espace de l'écran. Par défaut, cette valeur est « false ».

Des exemples de définitions de tracés sont affichés ci-dessous :

  • Ligne bleue fine, opacité de 50 % : path=color:0x0000ff80|weight:1
  • Ligne rouge opaque : path=color:0xff0000ff|weight:5
  • Ligne blanche épaisse opaque : path=color:0xffffffff|weight:10

Ces styles de tracé sont facultatifs. Si vous souhaitez les attributs par défaut, vous pouvez ignorer la définition des attributs de tracé ; dans ce cas, le premier « argument » du descripteur de tracé est le premier point déclaré (point géographique).

Points de tracé

Pour dessiner un tracé, deux points ou plus doivent être associés au paramètre path. Google Static Maps API relie alors ces points dans l'ordre spécifié pour former le tracé. Chaque pathPoint est indiqué dans le pathDescriptor séparé par une barre verticale (|).

L'exemple suivant définit un tracé bleu avec une opacité de 50 % par défaut, allant d'Union Square (New York) à Times Square (New York).

Tracé d'Union Square à Times Square

Les détails du paramètre path apparaissent ci-dessous :

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

L'exemple suivant établit le même tracé mais en définissant une ligne rouge d'une opacité de 100 % :

Tracé d'Union Square à Times Square

Les détails de ce paramètre path apparaissent ci-dessous :

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

L'exemple ci-dessous définit une zone polygonale à Manhattan, où une série d'intersections ont été définies comme des points géographiques :

Tracé d'Union Square à Times Square

Les détails de ce paramètre path apparaissent ci-dessous :

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Notez que le tracé est paramétré de manière à le rendre invisible et que la zone polygonale a une opacité de 15 %.

Polylignes encodées

Au lieu d'utiliser une série de points géographiques, vous pouvez déclarer un tracé sous forme de polyligne encodée en utilisant le préfixe enc: dans la déclaration de point géographique de path. Notez que si vous fournissez un tracé de polyligne encodée pour une carte, il n'est pas nécessaire de spécifier les paramètres center et zoom (normalement obligatoires).

L'exemple ci-dessous suit le tracé de la route de l'Alaska entre Dawson Creek (Colombie-Britannique) et Delta Junction (Alaska) avec une polyligne encodée :

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

Route de l'Alaska

Comme pour les tracés standard, les tracés de polyligne encodée peuvent également délimiter des zones polygonales si un argument fillcolor est transmis au paramètre path.

L'exemple suivant trace une zone polygonale délimitant Brooklyn (New York) :

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Polyligne encodée de Brooklyn

Fenêtres d'affichage

Les images peuvent spécifier une fenêtre d'affichage en fonction de points géographiques visibles définis avec le paramètre visible. Le paramètre visible demande au service Google Static Maps API de créer une carte de manière à ce que les points géographiques existants restent visibles. (Ce paramètre peut être combiné aux marqueurs ou aux tracés existants pour définir également une région visible.) Lorsque vous définissez une fenêtre d'affichage, il est inutile de spécifier un niveau de zoom exact.

L'exemple ci-dessous est une requête de carte centrée sur Boston (Massachusetts) contenant le MIT et Harvard Square à Cambridge (Massachusetts) :

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

Carte de Cambridge

Positionnement implicite de la carte

Vous devez normalement spécifier des paramètres d'URL center et zoom pour définir l'emplacement et le niveau de zoom de la carte générée. Cependant, si vous fournissez des paramètres markers, path ou visible, vous pouvez laisser Google Static Maps API déterminer de manière implicite le centre et le niveau de zoom corrects, sur la base de l'évaluation de la position de ces éléments.

Si vous fournissez plusieurs éléments, Google Static Maps API détermine un centre et un niveau de zoom corrects, en fournissant des marges importantes autour des éléments contenus dans la carte. L'exemple ci-dessous affiche une carte contenant San Francisco, Oakland et San Jose (Californie) :

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

Résolution des problèmes et support

Pour plus d'informations sur l'utilisation de Google Static Maps API, consultez la page de support.

Google Static Maps API peut afficher une erreur ou un avertissement en cas de problème. Il est recommandé de vérifier les avertissements, notamment si vous remarquez qu'il manque un élément sur la carte. Il est également préférable de vérifier les avertissements avant de lancer une nouvelle application. Notez que les avertissements peuvent ne pas apparaître immédiatement, car ils se trouvent dans l'en-tête HTTP. Pour plus d'informations, voir le guide des erreurs et avertissements.

Google Static Maps API exigeait auparavant l'insertion du paramètre sensor pour savoir si votre application utilisait un capteur afin de déterminer la position géographique de l'utilisateur. Désormais, ce paramètre n'est plus obligatoire.

Envoyer des commentaires concernant…

Google Static Maps API
Besoin d'aide ? Consultez notre page d'assistance.