Intégrer une carte

Ce guide explique comment intégrer une carte interactive à votre page Web.

Créer l'URL de l'API Maps Embed

Voici un exemple d'URL qui charge l'API Maps Embed :

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Remplacez :

  • MAP_MODE avec votre mode Plan.
  • YOUR_API_KEY par votre clé API. Pour en savoir plus, consultez Obtenir une clé API.
  • PARAMETERS par les paramètres obligatoires et facultatifs de votre mode Carte.

Ajouter l'URL dans un iFrame

Pour utiliser l'API Maps Embed sur votre page Web, définissez l'URL que vous avez créée comme valeur de l'attribut src d'un iframe. Contrôlez la taille de la carte à l'aide des attributs height et width de l'iframe, par exemple :

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

L'exemple d'iframe ci-dessus utilise les propriétés supplémentaires suivantes :

  • La propriété allowfullscreen pour permettre à certaines parties de la carte de passer en plein écran.
  • Les propriétés frameborder="0" et style="border:0" pour supprimer la bordure d'iFrame standard autour de la carte.
  • La propriété referrerpolicy="strict-origin-when-cross-origin" garantit que le navigateur envoie le domaine de votre site Web à Google en tant qu'en-tête Referer. Cela permet aux restrictions de clé API de valider la requête, tout en préservant la confidentialité des chemins d'accès à vos pages.

Vous pouvez redimensionner l'iframe pour l'adapter à la structure et à la conception de votre site Web, mais nous constatons que les visiteurs trouvent généralement plus facile d'interagir avec des cartes plus grandes. Notez que les cartes intégrées ne sont pas acceptées si leur taille est inférieure à 200 px dans l'une ou l'autre des dimensions.

Informations sur l'URL de provenance et restrictions de clé API

Si la balise Meta referrer du site Web d'hébergement est définie sur no-referrer ou same-origin, le navigateur n'envoie pas l'en-tête Referer à Google. Cela peut entraîner le rejet des requêtes par votre restriction de clé API. Pour que la restriction fonctionne correctement, ajoutez une propriété referrerpolicy à l'iframe, comme dans l'exemple ci-dessus, afin d'autoriser explicitement l'envoi des en-têtes Referer à Google.

  • strict-origin-when-cross-origin (recommandé) : envoie uniquement votre domaine de base (par exemple, https://example.com/) à Google. Cela permet de garder vos chemins de page spécifiques privés tout en permettant aux restrictions de clé API de fonctionner.
  • no-referrer-when-downgrade (ancienne version) : envoie l'URL complète, y compris les chemins de la page et les paramètres de requête spécifiques (par exemple, https://example.com/contact?user=123).

En savoir plus sur l'en-tête Referrer-Policy

Choisir les modes de carte

Vous pouvez spécifier l'un des modes Plan suivants à utiliser dans l'URL de votre requête :

  • place : affiche un repère sur la carte à un endroit ou une adresse spécifiques, comme un point de repère, un établissement, un élément géographique ou une ville.
  • view : renvoie une carte sans repères ni itinéraires.
  • directions : affiche le trajet entre au moins deux points spécifiés sur la carte, ainsi que la distance et le temps de trajet.
  • streetview : affiche des vues panoramiques interactives à partir d' emplacements désignés.
  • search : affiche les résultats d'une recherche dans la région visible de la carte.

Mode place

L'URL suivante utilise le mode Plan place pour afficher un repère sur la carte au niveau de la tour Eiffel :

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Vous pouvez utiliser les paramètres suivants :

Paramètre Type Description Valeurs acceptées
q Obligatoire Définit l'emplacement du repère sur la carte. Nom du lieu, adresse, Plus Code ou ID de lieu avec échappement d'URL. L'API Maps Embed accepte à la fois + et %20 pour l'échappement des espaces. Par exemple, convertissez "City Hall, New York, NY" en City+Hall,New+York,NY ou le Plus Code "849VCWC8+R9" en 849VCWC8%2BR9.
center Facultatif Définit le centre de la vue de la carte. Accepte les valeurs de latitude et de longitude séparées par une virgule, par exemple : 37.4218,-122.0840.
zoom Facultatif Définit le niveau de zoom initial de la carte. Les valeurs sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.
maptype Facultatif Définit le type de tuiles de carte à charger. roadmap (par défaut) ou satellite
language Facultatif Définit la langue à utiliser pour les éléments d'interface utilisateur et pour l'affichage des libellés sur les tuiles de carte. Par défaut, les visiteurs verront une carte dans leur propre langue. Ce paramètre n'est compatible qu'avec certaines tuiles de pays. Si la langue spécifique demandée n'est pas compatible avec l'ensemble de tuiles, la langue par défaut de cet ensemble de tuiles sera utilisée.
region Facultatif Définit les frontières et les libellés appropriés à afficher, en fonction des sensibilités géopolitiques. Accepte un code régional spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques) mappé avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Consultez Détails de la couverture Google Maps Platform pour obtenir une liste des régions prises en charge.

Mode view

L'exemple suivant utilise le mode view et le paramètre facultatif maptype pour afficher une vue satellite de la carte :

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Vous pouvez utiliser les paramètres suivants :

Paramètre Type Description Valeurs acceptées
center Obligatoire Définit le centre de la vue de la carte. Accepte les valeurs de latitude et de longitude séparées par une virgule, par exemple : 37.4218,-122.0840.
zoom Facultatif Définit le niveau de zoom initial de la carte. Les valeurs sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.
maptype Facultatif Définit le type de tuiles de carte à charger. roadmap (par défaut) ou satellite
language Facultatif Définit la langue à utiliser pour les éléments d'interface utilisateur et pour l'affichage des libellés sur les tuiles de carte. Par défaut, les visiteurs verront une carte dans leur propre langue. Ce paramètre n'est compatible qu'avec certaines tuiles de pays. Si la langue spécifique demandée n'est pas compatible avec l'ensemble de tuiles, la langue par défaut de cet ensemble de tuiles sera utilisée.
region Facultatif Définit les frontières et les libellés appropriés à afficher, en fonction des sensibilités géopolitiques. Accepte un code régional spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques) mappé avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Consultez Détails de la couverture Google Maps Platform pour obtenir une liste des régions prises en charge.

Mode directions

L'exemple suivant utilise le mode directions pour afficher l'itinéraire entre Oslo et Telemark, en Norvège, la distance et le temps de trajet en évitant les péages et les autoroutes.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Vous pouvez utiliser les paramètres suivants :

Paramètre Type Description Valeurs acceptées
origin Obligatoire Définit le point de départ à partir duquel afficher l'itinéraire. Nom du lieu, adresse, Plus Code, coordonnées de latitude/longitude ou ID de lieu avec échappement d'URL. L'API Maps Embed accepte à la fois + et %20 pour l'échappement des espaces. Par exemple, convertissez "City Hall, New York, NY" en City+Hall,New+York,NY ou le Plus Code "849VCWC8+R9" en 849VCWC8%2BR9.
destination Obligatoire Définit le point de terminaison de l'itinéraire. Nom du lieu, adresse, Plus Code, coordonnées de latitude/longitude ou ID de lieu échappés au format URL. L'API Maps Embed accepte à la fois + et %20 pour l'échappement des espaces. Par exemple, convertissez "City Hall, New York, NY" en City+Hall,New+York,NY ou le Plus Code "849VCWC8+R9" en 849VCWC8%2BR9.
waypoints Facultatif Spécifie un ou plusieurs lieux intermédiaires pour l'itinéraire entre le point de départ et la destination. Nom du lieu, adresse ou ID de lieu. Vous pouvez spécifier plusieurs points de cheminement en utilisant une barre verticale (|) pour séparer les lieux (par exemple, Berlin,Germany|Paris,France). Vous pouvez spécifier jusqu'à 20 points de cheminement.
mode Facultatif Définit le mode de transport. Si aucun mode n'est spécifié, l'API Maps Embed affiche un ou plusieurs des modes les plus pertinents pour l'itinéraire spécifié. driving, walking (qui privilégie les chemins piétons et les trottoirs, si disponibles), bicycling (qui privilégie les itinéraires utilisant des pistes cyclables et les rues préférées, si disponibles), transit ou flying.
avoid Facultatif Spécifie les éléments à éviter dans l'itinéraire. Notez que cela n'exclut pas les itinéraires qui incluent les caractéristiques restreintes, mais que cela oriente le résultat vers des itinéraires plus favorables. tolls, ferries et/ou highways. Séparez les différentes valeurs par une barre verticale (par exemple, avoid=tolls|highways).
units Facultatif Spécifie la méthode de mesure, métrique ou impériale, lors de l'affichage des distances dans les résultats. Si units n'est pas spécifié, le pays origin de la requête détermine les unités à utiliser. metric ou imperial
center Facultatif Définit le centre de la vue de la carte. Accepte les valeurs de latitude et de longitude séparées par une virgule, par exemple : 37.4218,-122.0840.
zoom Facultatif Définit le niveau de zoom initial de la carte. Les valeurs sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.
maptype Facultatif Définit le type de tuiles de carte à charger. roadmap (par défaut) ou satellite
language Facultatif Définit la langue à utiliser pour les éléments d'interface utilisateur et pour l'affichage des libellés sur les tuiles de carte. Par défaut, les visiteurs verront une carte dans leur propre langue. Ce paramètre n'est compatible qu'avec certaines tuiles de pays. Si la langue spécifique demandée n'est pas compatible avec l'ensemble de tuiles, la langue par défaut de cet ensemble de tuiles sera utilisée.
region Facultatif Définit les frontières et les libellés appropriés à afficher, en fonction des sensibilités géopolitiques. Accepte un code régional spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques) mappé avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Consultez Détails de la couverture Google Maps Platform pour obtenir une liste des régions prises en charge.

Mode streetview

L'API Maps Embed vous permet d'afficher des images Street View sous forme de panoramas interactifs à partir de lieux désignés dans sa zone de couverture. Les photosphères ajoutées par les utilisateurs et les collections spéciales Street View sont également disponibles.

Chaque panorama Street View offre une vue complète à 360 degrés d'un même lieu. Les images contiennent une vue horizontale à 360 degrés (tour d'horizon complet) et une vue verticale à 180 degrés (du zénith au nadir). Le mode streetview fournit une visionneuse qui affiche le panorama sous la forme d'une sphère avec une caméra au centre. Vous pouvez manipuler la caméra pour contrôler le zoom et l'orientation de la caméra.

Consultez le panorama en mode streetview suivant :

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

L'un des paramètres d'URL suivants est obligatoire :

  • location accepte une latitude et une longitude sous forme de valeurs séparées par une virgule (46.414382,10.013988). L'API affiche le panorama photographié le plus proche de cet emplacement. Étant donné que les images Street View sont régulièrement actualisées et que les photos peuvent être prises à partir de positions légèrement différentes à chaque fois, il est possible que votre position soit associée à un autre panorama lors de la mise à jour des images.

  • pano est un ID de panorama spécifique. Si vous spécifiez un pano, vous pouvez également spécifier un location. location n'est utilisé que si l'API ne trouve pas l'ID du panorama.

Les paramètres d'URL suivants sont facultatifs :

Paramètre Type Description Valeurs acceptées
heading Facultatif Indique l'orientation de la boussole de la caméra en degrés dans le sens des aiguilles d'une montre à partir du nord. Valeur en degrés comprise entre -180° et 360°
pitch Facultatif spécifie l'angle de la caméra, vers le haut ou vers le bas. Les valeurs positives inclinent la caméra vers le haut, tandis que les valeurs négatives l'inclinent vers le bas. L'inclinaison par défaut de 0° est définie en fonction de la position de la caméra au moment de la capture de l'image. Par conséquent, une inclinaison de 0° est souvent, mais pas toujours, horizontale. Par exemple, une image prise sur une colline présentera probablement une inclinaison par défaut qui n'est pas horizontale. Valeur en degrés comprise entre -90° et 90°
fov Facultatif détermine le champ de vision horizontal de l'image. La valeur par défaut est de 90°. Lorsque vous utilisez une fenêtre d'affichage de taille fixe, le champ de vision peut être considéré comme le niveau de zoom, les valeurs plus petites indiquant un niveau de zoom plus élevé. Valeur en degrés, comprise entre 10° et 100°
center Facultatif Définit le centre de la vue de la carte. Accepte les valeurs de latitude et de longitude séparées par une virgule, par exemple : 37.4218,-122.0840.
zoom Facultatif Définit le niveau de zoom initial de la carte. Les valeurs sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.
maptype Facultatif Définit le type de tuiles de carte à charger. roadmap (par défaut) ou satellite
language Facultatif Définit la langue à utiliser pour les éléments d'interface utilisateur et pour l'affichage des libellés sur les tuiles de carte. Par défaut, les visiteurs verront une carte dans leur propre langue. Ce paramètre n'est compatible qu'avec certaines tuiles de pays. Si la langue spécifique demandée n'est pas compatible avec l'ensemble de tuiles, la langue par défaut de cet ensemble de tuiles sera utilisée.
region Facultatif Définit les frontières et les libellés appropriés à afficher, en fonction des sensibilités géopolitiques. Accepte un code régional spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques) mappé avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Consultez Détails de la couverture Google Maps Platform pour obtenir une liste des régions prises en charge.

Mode search

Le mode Search affiche les résultats d'une recherche dans la région visible de la carte. Il est recommandé de définir un lieu pour la recherche, soit en incluant un lieu dans le terme de recherche (record+stores+in+Seattle), soit en incluant les paramètres center et zoom pour limiter la recherche.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Vous pouvez utiliser les paramètres suivants :

Paramètre Type Description Valeurs acceptées
q Obligatoire Définit le terme de recherche. Il peut inclure une restriction géographique, telle que in+Seattle ou near+98033.
center Facultatif Définit le centre de la vue de la carte. Accepte les valeurs de latitude et de longitude séparées par une virgule, par exemple : 37.4218,-122.0840.
zoom Facultatif Définit le niveau de zoom initial de la carte. Les valeurs sont comprises entre 0 (le monde entier) et 21 (bâtiments individuels). La limite supérieure peut varier en fonction des données cartographiques disponibles à l'emplacement sélectionné.
maptype Facultatif Définit le type de tuiles de carte à charger. roadmap (par défaut) ou satellite
language Facultatif Définit la langue à utiliser pour les éléments d'interface utilisateur et pour l'affichage des libellés sur les tuiles de carte. Par défaut, les visiteurs verront une carte dans leur propre langue. Ce paramètre n'est compatible qu'avec certaines tuiles de pays. Si la langue spécifique demandée n'est pas compatible avec l'ensemble de tuiles, la langue par défaut de cet ensemble de tuiles sera utilisée.
region Facultatif Définit les frontières et les libellés appropriés à afficher, en fonction des sensibilités géopolitiques. Accepte un code régional spécifié sous forme de sous-tag de région Unicode à deux caractères (non numériques) mappé avec les valeurs ccTLD ("domaine de premier niveau") à deux caractères que vous connaissez. Consultez Détails de la couverture Google Maps Platform pour obtenir une liste des régions prises en charge.

Paramètres d'ID de lieu

L'API Maps Embed permet d'utiliser des ID de lieu au lieu de fournir un nom ou une adresse de lieu. Les ID de lieu permettent d'identifier un lieu de manière unique et stable. Pour en savoir plus, consultez la documentation de l'API Places (New).

L'API Maps Embed accepte les ID de lieu pour les paramètres d'URL suivants :

  • q
  • origin
  • destination
  • waypoints

Pour utiliser un ID de lieu, vous devez d'abord ajouter le préfixe place_id:. Le code suivant spécifie l'hôtel de ville de New York comme point de départ d'une demande d'itinéraire : origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius définit un rayon, spécifié en mètres, dans lequel rechercher un panorama, centré sur la latitude et la longitude données. Les valeurs valides sont des entiers non négatifs. La valeur par défaut est 50.

  • source limite les recherches Street View aux sources sélectionnées. Les valeurs valides sont les suivantes :

    • default utilise les sources par défaut pour Street View. Les recherches ne sont pas limitées à des sources spécifiques.
    • outdoor limite les recherches aux collections extérieures. Les collections d'images d'intérieur ne sont pas incluses dans les résultats de recherche. Notez qu'il est possible que les panoramas extérieurs ne soient pas disponibles pour le lieu spécifié. Notez également que la recherche ne renvoie que les panoramas pour lesquels il est possible de déterminer s'ils sont en intérieur ou en extérieur. Par exemple, les PhotoSphères ne sont pas renvoyées, car on ne sait pas si elles sont prises en intérieur ou en extérieur.