ArcGIS API for JavaScript (legacy) ^3.46

The ArcGIS API for JavaScript can work with web maps created using the ArcGIS.com map viewer. Use the map viewer to quickly and easily create and share maps. Web maps can contain layers from ArcGIS Server map, image and feature services, KML documents, and OGC web services. You can also import data you have stored in comma-separated values table (.csv or .txt) or a GPS Exchange format (.gpx) file. When creating the web map you can create and define popup content, set a basemap and specify the intial extent. More information and examples are available in the web map specification help topic.

Once you've created your map using the ArcGIS.com viewer save and share the map and its ready to use from the api. View the ArcGIS.com Resource Center for more details on creating and sharing a web map.

Getting started with the templates

You may also want to create a web application using your map with your own look and functionality that you can deploy on your organization's web server. ArcGIS.com includes customizable templates that make it easy to create a web mapping application. They include common map elements like a legend and scale bar and more advanced functionality like editing. See Make a web application help topic for additional information.

Create a map from an ArcGIS.com web map

The esri.arcgis.utils namespace contains utility methods to work with web maps from ArcGIS.com.

You can display a web map in an application built using the ArcGIS API for JavaScript using the esri.arcgis.utils utility methods. The esri.arcgis.utils.createMap method creates a map using information from an ArcGIS.com web map. This information can be either a web map id or a by value representation of the web map.

To create a map using the ArcGIS.com web map id navigate to the details page for the web map. The web map's ID is the value at the end of the URL of the details page. For example, for the Topographic map with the details URL https://www.arcgis.com/home/item.html?id=d5e02a0c1f2b4ec399823fdd3c2fdebd, the ID is d5e02a0c1f2b4ec399823fdd3c2fdebd.

Once you have the web map id use esri.arcgis.utils.createMap to create a map.

var mapid="d5e02a0c1f2b4ec399823fdd3c2fdebd"
var mapDeferred = esri.arcgis.utils.createMap(mapid, "map", {
  mapOptions: {
    slider: true,
    nav:false
  }
});

An alternative to creating a map using the web map id is to create a map using a json object that is a by value representation of the web map. This can be useful in situations where the application will not have access to ArcGIS.com. View the ArcGIS web map JSON format documentation for more details on this specification.

This snippet creates a new webmap and defines the title, description and initial extent of the map.

var webmap = {};
webmap.item = {
  "title":"Soil Survey Map of USA",
  "snippet": "Detailed description of data",
  "extent": [[-139.4916, 10.7191],[-52.392, 59.5199]]
};

Next,specify the layers that make up the map. In this snippet, the World Terrain basemap from ArcGIS.com is added along with an overlay layer that adds additional information to the map such as boundaries, cities, water features and landmarks and roads. An operational layer is added that displays soil information from the U.S. Department of Agriculture.

webmap.itemData = {
"operationalLayers": [{
  "url": "http://server.arcgisonline.com/ArcGIS/rest/services/Specialty/Soil_Survey_Map/MapServer",
  "visibility": true,
  "opacity": 0.75,
  "title": "Soil Survey Map",
  "itemId": "204d94c9b1374de9a21574c9efa31164"
}],
"baseMap": {
  "baseMapLayers": [{
    "opacity": 1,
    "visibility": true,
    "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer"
    },{
    "isReference": true,
    "opacity": 1,
    "visibility": true,
    "url": "http://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Reference_Overlay/MapServer"
    }],
  "title": "World_Terrain_Base"
},
"version": "1.1"
};

Once the web map is defined use esri.arcgis.utils.createMap to build a map from the definition.

var mapDeferred = esri.arcgis.utils.createMap(webmap, "map", {
  mapOptions: {
    slider: true
  }
});

Note: You can retrieve the item definition from an ArcGIS.com item using esri.arcgis.utils.getItem()

Working with the map

The return value of esri.arcgis.utils.createMap is dojo.Deferred. To work with the deferred define a .then() callback that will execute when the asynchronous request is completed.

mapDeferred.then(function(response) {
  map = response.map;
});

The information included in the response object returned to the callback depends on the version of the ArcGIS API for JavaScript you are using.

{
  map:<esri.Map>
}

{
  map: <esri.Map>,
  itemInfo:{
    item: <Object>,
    itemData:<Object>
  }
}

{
  map: <esri.Map>,
  itemInfo:{
    item: <Object>,
    itemData:<Object>,
    errors: [<Object>]
  }
}

{
  map: <esri.Map>,
  clickEventHandler, <Event Handler>
  clickEventListener, <Function>
  itemInfo:{
    item: <Object>,
    itemData:<Object>,
    errors: [<Object>]
  }
}

dojo.disconnect(response.clickEventHandle);

dojo.connect(map,"onClick",response.clickEventListener);

To access the layers in the web map use itemInfo.itemData.operationalLayers. In this snippet the operational layers are used to create a legend that displays the layers in the map.

var layers = response.itemInfo.itemData.operationalLayers;
var layerInfo = [];
dojo.forEach(layers,function(layer){
  if(!layer.featureCollection){
   layerInfo.push({"layer":layer.layerObject,"title":layer.title});
  }
});
var legendDijit = new esri.dijit.Legend({
  map:map,
  layerInfos:layerInfo
},"legendDiv");
legendDijit.startup();