Understand the map format

Web maps hosted on a mobile content server or on ArcGIS Online use JavaScript Object Notation (JSON) to format a map's content.

Learn about the web map format

A map is composed of operational and basemap layers, along with tasks. Both operational and basemap layers correspond to ArcGIS services. For each layer type, the following parameters are required:

  • url—URL to the specific service you want to add
  • visibility—Whether or not the layer is visible in the application when opened (true or false)
  • opacity—Number between 0–1 that defines transparency (0.5 is 50 percent transparent)

There are additional optional parameters for layers. For example, there is a title that is used in the legend.

Tasks expose pre-authored parameterized geospatial tasks. Currently, only the Query task is supported.

The following is an example of a map on ArcGIS Online that is publically available and its JSON:


  "operationalLayers": [{
    "url": "http://sampleserver5a.arcgisonline.com/ArcGIS/rest/services/Events/FeatureServer/0",
    "visibility": true,
    "opacity": 1,
    "mode": 1,
    "title": "SS5_Events - Events"
  "baseMap": {
    "baseMapLayers": [{
      "opacity": 1,
      "visibility": true,
      "url": "http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer"
    "title": "World_Topo_Map"
  "widgets": null,
  "version": "1.1"

There is much more to the JSON structure; however, the operational and basemap layer definition is what is critical to composing a map. To learn more about the web map format, see Web map format overview.

View examples from ArcGIS Online

Another way to understand the JSON format is to view examples from ArcGIS Online. You can read the JSON of a map that you create in ArcGIS Online by manipulating the URL in your web browser.

  1. Open a map using ArcGIS Online and view the URL of the map item in your browser. Each map is an item and the item has an ID. For example, the Topographic map can be opened using the following URL: http://www.arcgis.com/home/item.html?id=d5e02a0c1f2b4ec399823fdd3c2fdebd. Inside of this URL, d5e02a0c1f2b4ec399823fdd3c2fdebd is the item ID.
  2. View this map's JSON by using the following URL structure: http://www.arcgis.com/sharing/content/items/<item ID from your map>/data?f=pjson

    For example, to see the JSON of the map in Step 1, use the following URL: http://www.arcgis.com/sharing/content/items/d5e02a0c1f2b4ec399823fdd3c2fdebd/data?f=pjson.


    To see a map containing operational layers, a basemap, and a task, see http://www.arcgis.com/sharing/content/items/7d1d1070ab69435387f1ca44e20cdb5a/data?f=pjson.


    This approach works for maps that are shared with everyone. If you receive a 400 or 403 error attempting this with your map, it may be that your map is not shared. If this happens, you can still access the JSON by taking the steps in the following section.

Read the JSON of a private ArcGIS Online map

Reading the JSON of a publically available ArcGIS Online map can be accomplished using the steps in the previous section. If you attempt to access a map that is only available to certain user accounts, you receive a 400 or 403 error. Accessing those maps require generating a token, then providing it in the ArcGIS.com request. If you need to access a map that is only available to certain user accounts, generate a token based on your user ID and provide that in your ArcGIS.com request.

A token is generated by entering the following in the address bar of your browser: https://www.arcgis.com/sharing/generateToken?f=json&request=gettoken&username=myusername&password=mypassword&Referer=MyToken, where myusername and mypassword are replaced with your ArcGIS Online user name and password, respectively.


Use HTTPS instead of HTTP to generate the token.

This generates a response similar to the following:

{"token" :
: 1306883380145}

Once you have the token, use its value to retrieve the map's JSON by including "&token=" and the token value at the end of the URL. For example, http://www.arcgis.com/sharing/content/items/0a27f5cb1f07478fbdf117b70231c5c2/data?f=pjson&token=nEvfvFwGBaQ7laRKxUlH8ACGkwm2aHqUKiscQbyoG4lmVZU8EiG2NLa5nj6UKiEa. This uses the token value to request the formatted JSON from the specified item.