Accessing and creating content¶

Your GIS can host a variety of maps, web layers, analytical tools, apps and individual files. Using the gis module, you can search for, access and manage all your folders, contents and automate such maintenance workflows as scripts.

In this page, we are going to observe how the following can be accomplished:

• Searching for content
  • Wild card search
  • Searching for content outside your organization
• Creating new content
  • Publishing an item as a web layer
  • Importing data from a pandas dataframe
  • Publishing an empty service
• Organizing content
  • Using folders to organize your contents

Searching for content¶

Accessing the content property of your gis object returns you an instance of ContentManager class. You can use the search() method of the ContentManager object to search for items on your GIS. You can use the search() even if you are connected as an anonymous user, in which case you get to search for public content on ArcGIS Online.

The first step is to import the API and connect to your GIS

Lets see what you get when you access content property

As explained earlier, we don't recommend creating your instance of ContentManager by yourself, instead, access it through the content property of your GIS object as shown below:

The search() method returned us a list of Item objects that matched the search criteria. The query parameter supports a variety of inputs, refer the search reference for more ideas on what is supported. Some typical examples are shown below:

Notice how the search result includes items from other users that they shared across the organization. You can limit the search to only your content by specifying that in the query string as shown below:

Wild card search¶

Search supports usage of wild cards. You can use one asterisk * for multiple character wild card search and one question mark ? for single character.

When using the Jupyter notebook environment, you can utilize the rich representation of items for your query results.

Once you know an item's id (called itemId), you can access it using the get() method instead of searching for it.

Searching for content outside your organization¶

So far, we were able to search for content that belonged to the logged in user, items published by built-in accounts and other named users but shared across the organization. When connected to ArcGIS Online, you can also search for content published by other named users and shared publicly. You can do so by turning the outside_org flag to True.

Let us search for public web scenes visualizing 3D cities. Note, I want to see content that is most popular by number of views to be returned on the top. I am also concerned that if too many items show up, the query might be running slow, hence restrict the results to 15 items.

Thus, you saw how you can apply filters and optional parameters to search for content from other users in different orgs. This collaborative aspect of GIS is quite powerful. You can quickly scale up your projects by leveraging the maps and GIS data shared by other users. You can get ideas on how to visualize or render a particular phenomenon etc. You can do all of this using the API and automate such tasks with ease. For instance, you can build a script to notify you whenever someone shares an item in your topic of interest.

So far, you observed how existing items can be searched and accessed using the gis module. Next, let us observe how new content can be created.

Creating new content¶

To create new items on your GIS, you use the add() method on ContentManager object. As earlier, you would not create this object, instead access it from the content property of your GIS object.

The add() method accepts a dictionary containing the properties of the item to be created. The optional data parameter accepts a string path to a file. You can use the optional metadata parameter to specify an XML file containing metadata information.

All content you add this way is added to the authenticated user's contents. Let us add a csv file and publish it as a feature layer.

The add() method returns an object of type arcgis.gis.Item representing the added item. In Jupyter notebook environment, you can visualize it by querying the item

Note: You can specify most properties of an item as a dictionary to the item_properties parameter. Refer to the API ref doc of this method for a definitive list. You could also specify an empty dictionary to this parameter, the downside is search cannot index these items efficiently if it does not have sufficient metadata information, hence that is not a good programming practice.

Publishing an item as a web layer¶

In the example above you added a csv item. Items such as csv, service definitions, file geodatabases, shape files and packages such as tile, scene and vector tile can be published into hosted web layers. This is accomplished by calling the publish() method on that Item object.

The publish() method accepts an optional publish_parameters dictionary where you can specify certain parameters supported by the publish REST API. However this is optional. The address_fields parameter allows you to specify which field in your csv or dataset contains address fields suitable for geocoding.

Let us publish the csv into a web feature layer. This csv contains latitude and longitude coordinates of each point, hence the address_fields parameter can be ignored. The publish() method returns an Item object corresponding to the web layer created.

Notice that the GIS used the same metadata (thumbnail, title, description) of the source item used for publishing. This helps provide context on what the new item is and also as a good starting point for the metadata which you can edit later.

Importing data from a pandas data frame¶

Pandas is a popular data analysis library for Python. The data frame object of pandas allows you to store and analyze tabular information with ease. Using the Python API, you can import such data frames as an arcgis.features.FeatureCollection object using the import_data() method. You can then add that feature collection as an item to your GIS.

Let us create a new pandas data frame representing locations of a few coastal cities read from a csv file. Note, in the example below, you could publish the csv as an item as shown earlier, but we will observe how you can filter that data through pandas and add it as a feature collection instead.

Now that we have the desired data frame, let us import that as a feature collection

Next step is to convert the feature collection to a JSON and add it as a text based item to the GIS

Note: here, we used the add() method to add the FeatureCollection object in memory as an item on the GIS. Notice we used the text property to pass the JSON representation of the feature collection and the type property to indicate the item type. You can use the same method to publish web maps and web scenes.

The sample notebooks for content publishers show how the concepts discussed here can be used to publish web maps and scenes to your GIS

Publishing an empty service¶

So far, we observed how an existing item can be used to publish a service. The ContentManager class allows you to publish a new service without any content using the create_service() method. This capability is useful when you want to create an empty service first then add content to it by editing it from client applications - Collector for ArcGIS for instance.

Before you create a service, you would want to ensure your desired service name is available. Since service name is part of the URL for a service, they need to be unique for a service type in an org. For this purpose, you would use is_service_name_available() method.

Below, let us publish an empty feature service. If successful, the API would return a feature layer item.

Notice that, there are no layers in this service. The first step when you edit such a service would be to update its service definition and enable the editing related capabilities.

Organizing content¶

Over time, your GIS can get filled with content. You can create folders on your GIS, just like in your file system, and use it to organize.

Using folders to organize your content¶

The create_folder() and delete_folder() methods available on the ContentManager class can be used to manage your folders. Once created, you can use the move() method to move content into and out of folders.

Let us create a folder called 'ports' and move the ports_item into it

You can move content out of folders to root by calling the move() method and specifying / as folder name

Summary¶

Thus, in this guide you observed how the gis module can be used to create new content and search for existing ones. Head over to the guide on managing-your-content next. When combined into a script, the ArcGIS API for Python becomes a powerful tool to automate your GIS content creation and management tasks.