Utiliser des jetons de session avec l'API Map Tiles

Un jeton de session est une donnée (un UUID) utilisée dans les appels REST pour identifier une session, c'est-à-dire une série d'échanges de messages associés. Vous devez inclure un jeton de session dans toutes les demandes de tuiles 2D et d'images Street View. Vous l'incluez en tant que valeur d'un paramètre session ajouté à toutes les URL de requête.

Dans l'API Map Tiles, un jeton de session représente un ensemble défini d'options d'affichage. Cela signifie que vous n'avez pas besoin de transmettre un ensemble d'options d'affichage avec chaque requête de carte. Vous pouvez utiliser le même jeton de session pour plusieurs clients. Un jeton de session est actuellement valide pendant deux semaines à compter de son heure d'émission, mais cela peut changer. Vous pouvez toujours vérifier l'heure d'expiration d'un jeton de session en consultant le champ expiry dans le message de réponse.

Demande de jeton de session

Pour demander un jeton de session, envoyez une requête HTTPS POST au point de terminaison createSession, comme illustré dans l'exemple suivant. Vous devez envoyer la requête avec un en-tête Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Champs obligatoires

mapType

Type de la carte de base. Cette valeur peut être l'une des suivantes :

roadmap
Tuiles de carte peintes Google Maps standards.
satellite
Images satellite.
terrain
Images du relief. Lorsque vous sélectionnez terrain comme type de carte, vous devez également inclure le type de calque layerRoadmap (décrit dans la section Champs facultatifs).
streetview
Panoramas Street View Pour en savoir plus, consultez la section Tuiles Street View.
language

Une balise de langue IETF qui spécifie la langue utilisée pour afficher les informations sur les tuiles. Par exemple, en-US spécifie la langue anglaise parlée aux États-Unis.

region

Identifiant de région (deux lettres majuscules) représentant la position physique de l'utilisateur dans le dépôt de données de paramètres régionaux communs. Exemple :US

Champs facultatifs

imageFormat
Spécifie le format de fichier à afficher. Les valeurs valides sont jpeg ou png. Les fichiers JPEG ne sont pas compatibles avec la transparence. Ils ne sont donc pas recommandés pour les tuiles de superposition. Si vous ne spécifiez pas de imageFormat, le meilleur format pour la carte est choisi automatiquement.
scale

Augmente la taille des éléments de la carte (tels que les libellés de route), tout en conservant la taille de la tuile et la zone de couverture de la tuile par défaut. En augmentant l'échelle, vous réduisez également le nombre de libellés sur la carte, ce qui réduit l'encombrement. Les valeurs suivantes sont des valeurs scale valides:

  • scaleFactor1x: valeur par défaut.
  • scaleFactor2x: double la taille des libellés et supprime ceux des éléments géographiques mineurs.
  • scaleFactor4x: quadruple la taille des libellés et supprime ceux des éléments géographiques mineurs.

Les exemples suivants illustrent l'effet de la mise à l'échelle des éléments de la carte.

Facteur d'échelle 1x Facteur d'échelle 2x
Carte affichant le facteur d'échelle x1 Carte montrant un facteur d'échelle x2
highDpi
Spécifie si des tuiles haute résolution doivent être affichées. Si le facteur de scaling est augmenté, highDpi permet d'augmenter la taille de la carte. Normalement, l'augmentation du facteur d'échelle agrandit la tuile obtenue dans une image de même taille, ce qui diminue la qualité. Avec highDpi, la taille obtenue est également augmentée, ce qui préserve la qualité. DPI signifie "Dots per Inch" (points par pouce) et "High DPI" signifie que la carte s'affiche en utilisant plus de points par pouce qu'en temps normal. Si la valeur est true, le nombre de pixels dans chacune des dimensions x et y est multiplié par le facteur d'échelle (c'est-à-dire x2 ou x4). La zone de couverture de la tuile reste inchangée. Ce paramètre ne fonctionne qu'avec les valeurs scale de 2x ou 4x. Cela n'a aucun effet sur les tuiles à l'échelle 1.
Facteur d'échelle 1x Facteur d'échelle 2 x PPP élevé
Carte affichée avec une résolution normale Carte affichée en haute résolution x2
layerTypes

Tableau de valeurs qui spécifie les types de calques ajoutés à la carte. Les valeurs valides sont les suivantes:

layerRoadmap
Obligatoire si vous spécifiez terrain comme type de carte. Peut également être superposée au type de carte satellite si vous le souhaitez. Cela n'a aucun effet sur les tuiles de la feuille de route.
layerStreetview
Affiche les rues et les lieux pour lesquels Street View est activé sur la carte sous forme de contours bleus.
layerTraffic
Affiche les conditions de circulation actuelles.
styles

Tableau d'objets de style JSON qui spécifient l'apparence et le niveau de détail des éléments cartographiques tels que les routes, les parcs et les zones construites. Les styles permettent de personnaliser la carte de base Google standard. Le paramètre styles n'est valide que si le type de carte est roadmap. Pour connaître la syntaxe complète, consultez la documentation de référence sur le style.

overlay

Valeur booléenne indiquant si layerTypes doit être affiché en tant que superposition distincte ou combinée aux images de base. Lorsque la valeur est true, la carte de base n'est pas affichée. Si vous n'avez pas défini de layerTypes, cette valeur est ignorée.

Par exemple, si vous demandez un type de carte satellite avec un calque layerRoadmap et que overlay est défini sur false, vous obtenez des tuiles équivalentes au type de carte hybrid utilisé dans l'API Maps JavaScript (image de gauche). Les mêmes types de carte et de calque avec overlay défini sur true génèrent une tuile transparente avec une superposition de carte, stylisée de manière appropriée pour la superposition sur des images satellite (image de droite).

overlay: faux overlay: vrai
Superposition définie sur "false" Superposition définie sur "True"

Le code JSON suivant est un exemple de corps de requête classique contenant des champs obligatoires et facultatifs.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Cet exemple fournit une superposition pouvant être combinée avec l'imagerie satellite. Cet exemple contient à la fois une feuille de route et une superposition Street View. La carte obtenue est affichée avec les noms et les données en anglais, comme c'est le cas aux États-Unis.

apiOptions: tableau de valeurs spécifiant les options supplémentaires à appliquer. Les options suivantes sont acceptées :

  • MCYJ5E517XR2JC : activation du nouveau style de carte. Pendant la période d'activation, vos requêtes utiliseront le style existant, sauf si cette valeur est spécifiée.

Réponse du jeton de session

Le code JSON suivant est un exemple de corps de réponse.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

La liste suivante contient les définitions des champs présents dans le corps de la réponse.

session
Valeur de jeton de session que vous devez inclure dans toutes vos requêtes API Map Tiles.
expiry
Chaîne contenant l'heure d'expiration du jeton (en secondes depuis l'epoch). Un jeton de session est valide pendant deux semaines à compter de sa date de création, mais cette règle peut être modifiée sans préavis.
tileWidth
La largeur des tuiles, mesurée en pixels.
tileHeight
La hauteur des tuiles est mesurée en pixels.
imageFormat
Format d'image, qui peut être png ou jpeg.