Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Add a Google Map with a Marker using JavaScript

  • This tutorial provides a step-by-step guide for embedding a Google Map with a marker on a webpage using HTML, CSS, and JavaScript.

  • You'll need to obtain a Google Maps API key and enable billing in order to use the Maps JavaScript API.

  • The tutorial covers HTML structure, API key integration, map initialization, and marker placement with code examples in both TypeScript and plain JavaScript.

  • The map is centered on Uluru, Australia with a customizable marker for demonstration purposes.

  • You can find additional resources and tips for customization and troubleshooting within the tutorial.

Introduction

This tutorial shows you how to add a Google map with a marker to a web page,using HTML, CSS, and JavaScript. It also shows you how to set map options, andhow to use control slotting to add a label to the map.

Below is the map you'll create using this tutorial. The marker is positioned atUluru (also known as Ayers Rock) in theUluru-Kata Tjuta National Park.

Getting started

There are three steps to creating a Google map with a marker on your web page:

  1. Get an API key
  2. Create an HTML page
  3. Add a map with a marker

You need a web browser. Choose a well-known one like Google Chrome(recommended), Firefox, Safari, or Edge, based on your platform from thelist of supported browsers.

Step 1: Get an API key

This section explains how to authenticate your app to theMaps JavaScript API using your own API key.

Follow these steps to get an API key:

  1. Go to theGoogle Cloud console.

  2. Create or select a project.

  3. ClickContinue to enable the API and any related services.

  4. On theCredentials page, get anAPI key (and set the API keyrestrictions). Note: If you have an existing unrestricted API key, or a keywith browser restrictions, you may use that key.

  5. To prevent quota theft and secure your API key, seeUsing API Keys.

  6. Enable billing. SeeUsage and Billingfor more information.

  7. Once you've got an API key, add it to the following snippet by clicking"YOUR_API_KEY". Copy and paste the bootloader script tag to use on your ownweb page.

    <script>(g=>{varh,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});vard=b.maps||(b.maps={}),r=newSet,e=newURLSearchParams,u=()=>h||(h=newPromise(async(f,n)=>{await(a=m.createElement("script"));e.set("libraries",[...r]+"");for(king)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({key:"YOUR_API_KEY",v:"weekly",// Use the 'v' parameter to indicate theversion to use (weekly, beta, alpha, etc.).// Add otherbootstrap parameters as needed, using camel case.});</script>

Step 2: Create an HTML page

Here's the code for a basic HTML web page:

<!DOCTYPE html><!-- @license Copyright 2025 Google LLC. All Rights Reserved. SPDX-License-Identifier: Apache-2.0--><html>  <head>    <title>Add a Map</title>    <link rel="stylesheet" type="text/css" href="./style.css" />    <script type="module" src="./index.js"></script>    <!-- prettier-ignore -->    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})        ({key: "YOUR_API_KEY", v: "weekly"});</script>  </head>  <body>    <!-- The map, centered at Uluru, Australia. -->    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">    </gmp-map>  </body></html>

This is a very basic HTML page which uses agmp-map element todisplay a map on the page. The map will be blank since we haven't added anyJavaScript code yet.

Understand the code

At this stage in the example, we have:

  • Declared the application as HTML5 using the!DOCTYPE html declaration.
  • Loaded the Maps JavaScript API using the bootstrap loader.
  • Created agmp-map element to hold the map.

Declare your application as HTML5

We recommend that you declare a trueDOCTYPE within your web application.Within the examples here, we've declared our applications as HTML5 using theHTML5DOCTYPE as shown below:

<!DOCTYPE html>

Most current browsers will render content that is declared with thisDOCTYPEin "standards mode" which means that your application should be morecross-browser compliant. TheDOCTYPE is also designed to degrade gracefully;browsers that don't understand it will ignore it, and use "quirks mode" todisplay their content.

Note that some CSS that works within quirks mode is not valid instandards mode. Specifically, all percentage-based sizes must inheritfrom parent block elements, and if any of those ancestors fail tospecify a size, they are assumed to be sized at 0 x 0 pixels. Forthat reason, we include the followingstyle declaration:

<style>  gmp-map {    height: 100%;  }  html, body {    height: 100%;    margin: 0;    padding: 0;  }</style>

Load the Maps JavaScript API

The bootstrap loader prepares the Maps JavaScript API for loading(no libraries are loaded untilimportLibrary() is called).

<script>(g=>{varh,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});vard=b.maps||(b.maps={}),r=newSet,e=newURLSearchParams,u=()=>h||(h=newPromise(async(f,n)=>{await(a=m.createElement("script"));e.set("libraries",[...r]+"");for(king)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({key:"YOUR_API_KEY",v:"weekly",// Use the 'v' parameter to indicate theversion to use (weekly, beta, alpha, etc.).// Add otherbootstrap parameters as needed, using camel case.});</script>

SeeStep 3: Get an API key for instructions on getting yourown API key.

At this stage of the tutorial a blank window appears, showing only theunformatted label text. This is because we haven't added any JavaScript codeyet.

Create agmp-map element

For the map to display on a web page, we must reserve a spot for it. Commonly,we do this by creating agmp-map element and obtaining a reference to thiselement in the browser's document object model (DOM). You can also use adiv element to do this (learn more),but it's recommended to use thegmp-map element.

The code below defines thegmp-map element, and sets thecenter,zoom,andmap-id parameters.

<gmp-mapcenter="-25.344,131.031"zoom="4"map-id="DEMO_MAP_ID"></gmp-map>

Thecenter andzoom options are always required. In the above code, thecenter property tells the API where to center the map, and thezoom propertyspecifies the zoom level for the map. Zoom: 0 is the lowest zoom, and displaysthe entire Earth. Set the zoom value higher to zoom in to the Earth at higherresolutions.

Zoom levels

Offering a map of the entire Earth as a single image would either require animmense map, or a small map with very low resolution. As a result, map imageswithin Google Maps and the Maps JavaScript API are broken up into map "tiles"and "zoom levels." At low zoom levels, a small set of map tiles covers a widearea; at higher zoom levels, the tiles are of higher resolution and cover asmaller area. The following list shows the approximate level of detail you canexpect to see at each zoom level:

  • 1: World
  • 5: Landmass or continent
  • 10: City
  • 15: Streets
  • 20: Buildings

The following three images reflect the same location of Tokyo at zoom levels 0,7 and 18.

The code below describes the CSS that sets the size of thegmp-map element.

/* Set the size of the gmp-map element that contains the map */gmp-map{height:400px;/* The height is 400 pixels */width:100%;/* The width is the width of the web page */}

In the above code, thestyle element sets the size of thegmp-map. Set thewidth and height to greater than 0px for the map to be visible. In thiscase, thegmp-map is set to a height of 400 pixels, and width of 100% todisplay across the width of the web page. It's recommended to always explicitlyset the height and width styles.

Note: For raster maps, the limit for the maximum dimension is 6144 x 6144 pixels.

Control slotting

You can use control slotting to add HTML form controls to your map. Aslot is apredefined position on the map; use theslot attribute to set the neededposition for an element, and nest elements within thegmp-map element. Thefollowing snippet shows adding an HTML label to the upper-left corner of themap.

<!-- The map, centered at Uluru, Australia. --><gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">  <div slot="control-inline-start-block-start">    <h3>My Google Maps Demo</h3>  </div></gmp-map>

Step 3: Add JavaScript code

This section shows you how to load the Maps JavaScript API into aweb page, and how to write your own JavaScript that uses the API to add a mapwith a marker on it.

TypeScript

asyncfunctioninitMap():Promise<void>{//  Request the needed libraries.const[{Map},{AdvancedMarkerElement}]=awaitPromise.all([google.maps.importLibrary("maps")asPromise<google.maps.MapsLibrary>,google.maps.importLibrary("marker")asPromise<google.maps.MarkerLibrary>,]);// Get the gmp-map element.constmapElement=document.querySelector("gmp-map")asgoogle.maps.MapElement;// Get the inner map.constinnerMap=mapElement.innerMap;// Set map options.innerMap.setOptions({mapTypeControl:false,});// Add a marker positioned at the map center (Uluru).constmarker=newAdvancedMarkerElement({map:innerMap,position:mapElement.center,title:"Uluru/Ayers Rock",});}initMap();
Note: Read theguide on using TypeScript and Google Maps.

JavaScript

asyncfunctioninitMap(){//  Request the needed libraries.const[{Map},{AdvancedMarkerElement}]=awaitPromise.all([google.maps.importLibrary("maps"),google.maps.importLibrary("marker"),]);// Get the gmp-map element.constmapElement=document.querySelector("gmp-map");// Get the inner map.constinnerMap=mapElement.innerMap;// Set map options.innerMap.setOptions({mapTypeControl:false,});// Add a marker positioned at the map center (Uluru).constmarker=newAdvancedMarkerElement({map:innerMap,position:mapElement.center,title:"Uluru/Ayers Rock",});}initMap();

The above code does the following things wheninitMap() is called:

  • Loads themaps andmarker libraries.
  • Gets the map element from the DOM.
  • Sets additionalmap optionson the inner map.
  • Adds a marker to the map.

Get the map object and set options

TheinnerMap represents an instance of theMap class.To set map options, get theinnerMapinstance from the map element and callsetOptions.The following snippet shows getting theinnerMap instance from the DOM, thencallingsetOptions:

// Get the gmp-map element.constmapElement=document.querySelector("gmp-map")asgoogle.maps.MapElement;// Get the inner map.constinnerMap=mapElement.innerMap;// Set map options.innerMap.setOptions({mapTypeControl:false,});

Wait for the map to load

When using thegmp-map element, the map loads asynchronously. This can resultin a race condition if other requests are made at initialization time (forexample geolocation or a Place details request). To ensure that your code onlyruns after the map is fully loaded, use anaddListenerOnce idle event handlerin your initialization function, as shown here:

// Do things once the map has loaded.google.maps.event.addListenerOnce(innerMap,'idle',()=>{// Run this code only after the map has loaded.console.log("The map is now ready!");});

Doing this ensures that your code is only run after the map has loaded; thehandler is only triggered once during the app's lifecycle.

Complete example code

See the complete example code here:

TypeScript

asyncfunctioninitMap():Promise<void>{//  Request the needed libraries.const[{Map},{AdvancedMarkerElement}]=awaitPromise.all([google.maps.importLibrary("maps")asPromise<google.maps.MapsLibrary>,google.maps.importLibrary("marker")asPromise<google.maps.MarkerLibrary>,]);// Get the gmp-map element.constmapElement=document.querySelector("gmp-map")asgoogle.maps.MapElement;// Get the inner map.constinnerMap=mapElement.innerMap;// Set map options.innerMap.setOptions({mapTypeControl:false,});// Add a marker positioned at the map center (Uluru).constmarker=newAdvancedMarkerElement({map:innerMap,position:mapElement.center,title:"Uluru/Ayers Rock",});}initMap();
Note: Read theguide on using TypeScript and Google Maps.

JavaScript

asyncfunctioninitMap(){//  Request the needed libraries.const[{Map},{AdvancedMarkerElement}]=awaitPromise.all([google.maps.importLibrary("maps"),google.maps.importLibrary("marker"),]);// Get the gmp-map element.constmapElement=document.querySelector("gmp-map");// Get the inner map.constinnerMap=mapElement.innerMap;// Set map options.innerMap.setOptions({mapTypeControl:false,});// Add a marker positioned at the map center (Uluru).constmarker=newAdvancedMarkerElement({map:innerMap,position:mapElement.center,title:"Uluru/Ayers Rock",});}initMap();
Note: The JavaScript is compiled from the TypeScript snippet.

CSS

/* * Always set the map height explicitly to define the size of the div element * that contains the map. */gmp-map{height:100%;}/*   * Optional: Makes the sample page fill the window.   */html,body{height:100%;margin:0;padding:0;}

HTML

<html>  <head>    <title>Add a Map</title>    <link rel="stylesheet" type="text/css" href="./style.css" />    <script type="module" src="./index.js"></script>    <!-- prettier-ignore -->    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>  </head>  <body>    <!-- The map, centered at Uluru, Australia. -->    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">      <div slot="control-inline-start-block-start">        <h3>My Google Maps Demo</h3>      </div>    </gmp-map>  </body></html>

Try Sample

Learn more about markers:

Tips and troubleshooting

  • Learn more aboutgetting latitude/longitudecoordinates, or converting an address into geographical coordinates.
  • You can tweak options like style and properties to customize the map. Formore information on customizing maps, read the guides tostyling, anddrawing on the map.
  • Use theDeveloper Tools Console in your web browser to test and run yourcode, read error reports and solve problems with your code.
  • Use the following keyboard shortcuts to open the console in Chrome:
    Command+Option+J (on Mac), or Control+Shift+J (on Windows).

  • Follow the steps below to get the latitude andlongitude coordinates for a location on Google Maps.

    1. Open Google Maps in a browser.
    2. Right-click the exact location on the map for which you requirecoordinates.
    3. SelectWhat's here? from the context menu that appears.The map displays a card at the bottom of the screen. Find the latitudeand longitude coordinates in the last row of the card.

  • You can convert an address into latitude and longitude coordinates using theGeocoding service. The developer guides provide detailed information ongetting started with the Geocoding service.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.