Hide Table of Contents
Build a web map using ArcGIS.com

The ArcGIS.com Map Viewer allows you to quickly and easily create and share web maps that tell interesting stories about your data. They may explain where people are buying homes, where sea surface temperature is changing, or where elephants migrate in the summer. These maps share information not just data.

In this tutorial, you'll build a sample application that uses the ArcGIS API for JavaScript to build an application that displays a web map from ArcGIS.com.

Build a web map

Web maps typically display a map service with operational data (such as available stands of timber) on top of a map service with reference information (such as imagery or a shaded relief map). Sometimes a reference map service that contains boundaries or labels is placed on top of the other layers to create a "map sandwich": two reference layers with the "meat", or operational data, in between. To build a web map visit the Create a map tutorial.

After creating the web map copy the web map id for use in the rest of this tutorial. To find the id, view your web map in ArcGIS.com and notice that the URL includes the unique map identifier.

View the code

View a live version of this sample in the ArcGIS API for JavaScript Sandbox.The sandbox is a live code editor that allows you to modify the sample's source and view the changes live. Try switching out the web map id in the sandbox for the id of your web map then hit Run to view your map.

Getting Started

  1. Open the tutorial sample in the sandbox and replace the code in the source section with the code below:
      <title>Create a Map</title>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
      <meta http-equiv="X-UA-Compatible" content="IE=7,IE=9" />
      <link rel="stylesheet" type="text/css" href="http://serverapi.arcgisonline.com/jsapi/arcgis/3.3/js/esri/css/esri.css" />
      <script type="text/javascript">djConfig = { parseOnLoad:true };</script>
      <script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/3.3compact"></script>
      <script type="text/javascript">
        function init(){
      <div id="mapDiv"></div>

    Note:If this code is new to you visit the Create your First Application help topic for details.

  2. Next we'll load the esri.arcgis.utils module to provide access to the esri.arcgis.utils.createMap method. To do so add the following code to the sandbox application.
    Now you are ready to use the createMap method. This method takes a web map id and optional map parameters and creates a map based on the web map content. Any symbology, popups, layer visibliity etc that you defined in your web map will be honored by the map.
  3. Add code to the init function to create a map based on the web map id. If you haven't created a web map yet you can use 1a40fa5cc1ab4569b79f45444d728067 for testing.
        function init(){
         var webmapid = 'Enter your web map id  here';
  4. Run the application and note that the web map from ArcGIS.com is displayed. The map displays with the symbology and popup information you defined in ArcGIS.com.
  5. Add a legend

    Starting at version 3.4, you can quickly add a legend to the application using the esri.arcgis.utils.getLegendLayers method. This method accepts the response from esri.argis.utils.createMap and builds an array of layerInfos that can be passed into the Legend constructor. The method takes into account the visibility settings for the layers and the output array will not contain the basemap. Try adding a legend to the test application.

    1. Add a div to the html section of the application below the existing map div.
      <div id="mapDiv"></div>
      <div id="legendDiv"></div>
    2. Add css to position the legend in the upper right corner of the map.
          background-color: #fff;
          position: absolute !important;
          z-index: 99;
    3. Now add the code that gets the legend layers. First load the Legend widget.
    4. Use the getLegendLayers method to build an array of legend layers.
          esri.arcgis.utils.createMap(webmapid, "mapDiv").then(function(response){
          map = response.map;
          var legend = new esri.dijit.Legend({
    5. Run the application and the legend should display in the upper right corner of the map.

    For more details on working with web maps from the ArcGIS API for JavaScript or working with the web application templates view the ArcGIS.com web maps help topic for details.