Items

An item is a reference to content stored in a portal. The content can be a map, layer, style, tool, application, file, data service, or notebook.

You can use an item to:

  • Securely store different types of content in a portal.
  • Share content with different users and groups.
  • Access data and services.
  • Manage and update content.

Working with items

The typical workflow for using an item is to:

  1. Create the item in a portal with data management tools or the REST API.
  2. Set the sharing permissions.
  3. Manage the item.
  4. Access the item with an application.

Item properties

All items contain a common set of properties such as the owner, title, type, tags, thumbnail, and description. These properties are common to all item types and are set when the item is created. The properties are also used to search for the item.

When an item is created, it is assigned a unique identifier, also known as an ID. You can use an ID to find and directly access an item in a portal.

Items that reference services can be used to manage the properties and capabilities of the service itself. For example, you can use a hosted feature layer item to store the pop-up and styling information for a hosted feature layer. It can also be used to set the editing capabilities for the feature layer in the feature service.

The sharing permissions of an item can also be set so it can be accessed by just the owner (private), the members of an organization (org), or everyone (public).

These properties are typically set using an item page.

Item types

Different types of items can be stored in a portal. This includes maps, layers, styles, tools, applications, files, data sources, or notebooks. Each item has a set of properties that describe and reference the content. For items that reference content that can be stored as text, such as a web map, the JSON data is stored in a child data source. For items that reference services, the URL property is used and, depending upon the type of service, child data may also be stored with the item.

Below is list of some of the more common item types, their label, and data type.

TypeLabel (in ArcGIS Online)Data Type or SourceDescription
Web MapWeb mapText/JSONA map with its configuration stored as a JSON structure.
Web SceneWeb sceneText/JSONA scene with its configuration stored as a JSON structure.
Feature ServiceFeature Layer (hosted)Text/JSONA hosted layer that references a feature layer in a feature service.
Vector Tile ServiceTile Layer (hosted)Text/JSONA hosted layer that references tile data and styles for a vector tile service.
Map ServiceTile Layer (hosted)Text/JSONA hosted layer that references static tile data in a Map service.
CSVCSVFileA reference to a file that contains comma separated values.
ShapefileShapefileFileA reference to a zipped file that contains a shapefile.

Access an item

To access an item in a portal, you can use data management tools, an item page, or the ArcGIS REST API. The sharing permissions set for an item determine who can view it. If the permissions are set to private, group, or organization, you need to provide authentication to access the item. If the permissions are set to public, you can access the item without providing authentication.

View properties with an item page

View an item and its properties with the item page in ArcGIS Online using the portal URL and ID. For example:

 
https://www.arcgis.com/home/item.html?id=5a5147abe878444cbac68dea9f2f64e7

View properties programmatically

Find and access an item by accessing it by the portal sharing URL and ID. The response contains the item properties.

Request

      
import { getItem } from "@esri/arcgis-rest-portal";
// Get a web map item
arcgisRest.getItem("5a5147abe878444cbac68dea9f2f64e7", { portal: "https://www.arcgis.com/sharing/rest" })
  .then((response) => {
    console.log(response); // Web map item properties
  });

Response

{
  "id": "5a5147abe878444cbac68dea9f2f64e7",
  "owner": "esri_devlabs",
  "orgId": "GVgbJbqm8hXASVYi",
  "created": 1569537110000,
  "modified": 1569537111000,
  "guid": null,
  "name": null,
  "title": "Seven Natural Wonders of the World Map",
  "type": "Web Map",
  "typeKeywords": [
    "ArcGIS Online",
    "Explorer Web Map",
    "Map",
    "Online Map",
    "Web Map"
  ],
  "description": null,
  "tags": [
    "map"
  ],
  "snippet": null,
  "thumbnail": "thumbnail/ago_downloaded.png",
  "documentation": null,
  "extent": [
    [
      -180,
      -68.6081
    ],
    [
      180,
      82.5122
    ]
  ],
  "categories": [],
  "spatialReference": null,
  "accessInformation": null,
  "licenseInfo": null,
  "culture": "en-us",
  "properties": null,
  "url": null,
  "proxyFilter": null,
  "access": "public",
  "size": 734,
  "subInfo": 0,
  "appCategories": [],
  "industries": [],
  "languages": [],
  "largeThumbnail": null,
  "banner": null,
  "screenshots": [],
  "listed": false,
  "commentsEnabled": true,
  "numComments": 0,
  "numRatings": 0,
  "avgRating": 0,
  "numViews": 2,
  "scoreCompleteness": 33,
  "groupDesignations": null
}

Access item data

Most items contain a child data resource that contains the associated data. You can request the data using the ID for the item you are interested in.

Get item data

This example gets the child data for the web map item referenced above. Data for a web map item is stored as JSON formatted text. Learn more about the web map format in Web map specification.

Request

      
import { getItemData } from "@esri/arcgis-rest-portal";
// Get data for a web map item
arcgisRest.getItemData("5a5147abe878444cbac68dea9f2f64e7", { portal: "https://www.arcgis.com/sharing/rest" })
  .then((response) => {
    console.log(response); // Web map JSON
  });

Response

{
  "operationalLayers": [
    {
      "id": "Seven_Natural_Wonders_of_the_World_6051",
      "layerType": "ArcGISFeatureLayer",
      "url": "https://services.arcgis.com/uCXeTVveQzP4IIcx/arcgis/rest/services/Seven_Natural_Wonders_of_the_World/FeatureServer/0",
      "visibility": true,
      "opacity": 1,
      "title": "Seven Natural Wonders of the World",
      "itemId": "da7cda8d38224b368bc74cc7d6f05d0f"
    }
  ],
  "baseMap": {
    "baseMapLayers": [
      {
        "id": "defaultBasemap",
        "layerType": "ArcGISTiledMapServiceLayer",
        "url": "https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer",
        "visibility": true,
        "opacity": 1,
        "title": "Topographic"
      }
    ],
    "title": "Topographic"
  },
  "spatialReference": {
    "wkid": 102100,
    "latestWkid": 3857
  },
  "authoringApp": "WebMapViewer",
  "authoringAppVersion": "5.4",
  "version": "2.11"
}

Examples

The following examples use ArcGIS REST JS to search the ArcGIS Online portal. To access a different portal, specify the portal URL.

Search for an item

Use a query to search for items in a portal. If many results are returned, use paging.

                
import { searchItems } from "@esri/arcgis-rest-portal";
// Define a query and text to search for
const query = new arcgisRest.SearchQueryBuilder()
  .match("Seven Natural Wonders of the World")
  .in("title")
  .and()
  .match("Web Map")
  .in("type")
  .and()
  .match("esri_devlabs")
  .in("owner")

arcgisRest.searchItems(query)
  .then((response) => {
    console.log(response);
});

Create an item

New items can be added by accessing a portal and specifying the item type and other required parameters.

              
import { createItem } from "@esri/arcgis-rest-portal";
// Create an item for a web map
createItem({
  item: {
    title: "World geography",
    description: "This is a web map of the world.",
    tags: ["map", "world", "geography"],
    type: "Web Map"
  },
  authentication
})
.then((response) => {
    console.log(response); // Item ID
});

Get an item

The most direct way to find an item is to access it by its unique item ID.

       
import { getItem } from "@esri/arcgis-rest-portal";
// Public
getItem("da7cda8d38224b368bc74cc7d6f05d0f") // Hosted feature layer
  .then(response);
// Private
getItem("YOUR-ITEM-ID", { authentication })
  .then(response) // Item properties

Get item data

You can get the child data for any item by accessing the the item data. The data returned is typically text (JSON) or a file.

       
import { getItemData } from "@esri/arcgis-rest-portal";
// Public
getItemData("5a5147abe878444cbac68dea9f2f64e7") // Web map item
  .then(response)
// Private
getItemData("YOUR-ITEM-ID", { authentication })
  .then(response) // Web map JSON

Share an item

To share an item with different sets of users, set the permissions to public, org, or private.

       
import { setItemAccess } from "@esri/arcgis-rest-portal";
// Set an existing item's sharing permissions
setItemAccess({
  id: "5a5147abe878444cbac68dea9f2f64e7",  // Hosted feature layer
  access: "public", // 'org' || 'private'
  authentication: authentication
})

Tutorials