Search for content

Portals can contain a huge amount of information, so to help your users find the information they want to work with, you can add searching to your app. Searching can allow users to find information in different ways, for example, by searching for the groups that include a keyword, or finding all portal items that are web maps that have specific tags.

Portals provide some predefined queries for common requests. For example, you can use predefined queries to find the basemaps or featured maps that have been configured by the portal administrator. Learn more about using predefined portal queries.

Searching is done from the Portal class. Publicly accessible items and groups can be accessed without any authentication, but to find items that are secured, a user with access to the item must be authenticated with the portal. See Access the ArcGIS Platform for more information about authenticating with a portal.

Searching may be a lengthy operation, so when adding search functionality to your app, make sure that it does not block the user interface, and ideally you should allow search cancellation.

Search by defining query parameters

The API provides a flexible, generic search, along with some convenience methods to help you perform common portal searches.

Find portal items by keyword

To search for portal items using a keyword, construct a query that includes the keyword you want to search for. By default, the query will return portal items that include the keyword in any of the common fields of a portal item, including the title, tags, description, and type. The results of the query can be iterated.

Create a PortalQueryParams object and pass the keyword you want to search for into the constructor as the query parameter. Then pass the PortalQueryParams to the Portal.findItems method. The resulting PortalQueryResultSet should contain all of the portal items that contain the keyword in any of the searched fields.

Portal portal = new Portal("", userCredentials);
PortalQueryParams queryParams = new PortalQueryParams("san francisco");
PortalQueryResultSet<PortalItem> resultSet = portal.findItems(queryParams);


Remember, only the items that are accessible to the authenticated user of the portal will be included in the search results.

The result set contains only the first 10 results but provides a convenient way to fetch subsequent sets of results if required. To learn more about working with large result sets, see Display many search results.

For a full list of the default fields used for searching, and complete information on constructing portal query strings, see the ArcGIS Online Search reference.

Display search results by order

If there are only a few results, all of the results might immediately be displayed. However, if there are many results, you may want to help your user narrow down the results to find items of most interest. The code below shows the most recently updated results to the user first, sorting search results by the date they were last modified, in descending order.


Results can be sorted in either ascending or descending order, by portal item fields such as the title, date of creation or date last modified, type, and owner. For a full list of sort fields, see ArcGIS Online Search.

Find items by type

You can restrict the results of a search to be a specific type or types of content; for example, you can adapt the previous example to find only web maps.

The setQuery method has a number of overloads—the code below uses the overload allowing you to specify the PortalItemType that results must match, along with a group ID (in this case, null indicates you want to search regardless of any groups) and the search query. The PortalItemType enum provides a full list of content types that may be stored as items in a portal.

PortalQueryParams queryParams = new PortalQueryParams();
queryParams.setQuery(PortalItemType.WEBMAP, null, "san francisco");
PortalQueryResultSet<PortalItem> resultSet = portal.findItems(queryParams);

If you want to find results of more than one type of portal item, you can do this by defining your query string.

Find items in your organization

By default, a search returns results from within an organization, and also public results from outside the organization. It may be useful to restrict results to only those within the organization of the authenticated user, as shown below.


Portal administrators can turn off the ability for their users to search for items outside the organization when using the website. This setting is independent of the query API, but you can get and use the portal-level setting as shown below to allow the portal administrators setting to determine the search behavior in your app as well as in the website.

PortalInfo info = portal.fetchPortalInfo();            
PortalQueryParams queryParams = new PortalQueryParams("san francisco");
PortalQueryResultSet<PortalItem> resultSet = portal.findItems(queryParams);

Find groups by keyword

You can find groups by using a keyword in a similar way used when finding portal items. For groups, the default fields searched include title, description, and tags (as for portal items), but also include owner.

Create a PortalQueryParams object and pass the keyword you want to search for into the constructor as the query parameter. Then pass the PortalQueryParams to the Portal.findGroups method. The resulting PortalQueryResultSet should contain all of the groups that contain the keyword in any of the searched fields. In this case, the query should find all of the groups containing "esri_demographics", including those owned by the user named "esri_demographics".

PortalQueryParams groupQuery = new PortalQueryParams("esri_demographics");
PortalQueryResultSet<PortalGroup> groupResults = portal.findGroups(groupQuery);

Find items in a known group

After a search for groups, you might want to list all of the items shared with those groups. Alternatively, you might want to list the items in a group returned from the authenticated users list of groups. If a search result set contains at least one group, to find all the items in that group, issue a second search using the group ID as part of the second query.

The code below continues from the previous example, by creating a second PortalQueryParams object, using the first PortalGroup from the initial search to set the group ID in the setQueryForItemsInGroup method, and then calling the Portal.findItems method to perform the second search.

if (groupResults.getResults().size() > 0)
  PortalGroup group = groupResults.getResults().get(0);
  PortalQueryParams groupContentQuery = new PortalQueryParams();
  PortalQueryResultSet<PortalItem> groupContentResults = portal.findItems(groupContentQuery);
  // Display the results.

Find items by ID

If you already know the ID of a portal item, you can search for it by using that ID. You might find this technique useful if your app is closed while displaying a specific item—you can save the ID and fetch the item again to ensure the item is still accessible and all the properties are up-to-date, and use this information to restore the state of the app. If the search returns no results, then the item may no longer be available; for example, the owner may have changed the access permissions, and your app can react accordingly.

PortalQueryParams itemIdQuery = new PortalQueryParams("");
itemIdQuery.setQueryForItemWithId("1966ef409a344d089b001df85332608f ");
PortalQueryResultSet<PortalItem> itemResults = portal.findItems(itemIdQuery);
if (! itemResults.getResults().isEmpty()) {
  PortalItem theItem = itemResults.getResults().get(0);

You can also directly fetch a PortalItem by ID using the static PortalItem.fetchItem method, passing in the ID and the Portal. However, this approach throws an exception if the item cannot be found.

PortalItem itm = PortalItem.fetchItem(portal, "1966ef409a344d089b001df85332608f ");

Define a query

If you need to search for items using more complex criteria, you can build a query to satisfy that, making use of multiple predicates, Boolean operators, ranges, and wildcards. For example, the query below finds items that are WebMaps, owned by the user "esri", with either of the tags "atlantic" or "pacific".

PortalQueryParams queryParams = new PortalQueryParams(
  "type:"\web map\" AND owner:esri AND tags:(pacific OR atlantic)"

Adding specific criteria can be especially useful when you are localizing your app, as you can limit results to a specific culture.

PortalQueryParams queryParams = new PortalQueryParams(
  "culture:fr-FR AND type:\"map service\"");

You can also search using ranges of dates items were created and last modified, using the created and modified fields of a portal item. However, be aware that portal searches use UNIX epoch dates (defined as the number of seconds that have elapsed since midnight January 1, 1970), as noted in the ArcGIS Online Search reference.

Search using predefined queries

As well as creating your own queries, you can search by using a number of predefined queries, defined on a portal depending on the configurations made by the portal administrator.

Get Homepage and Gallery featured content

Administrators can configure two groups that contain featured content to show in different situations. The Gallery can be populated either with the contents of a group or with the top 100 most-viewed items. The Homepage of the organization can display up to 12 items of featured content from a chosen group. Depending on the type of content that is featured, you may want your app to display the same featured items as shown in the website. For example, if the groups contain web maps, the results of the queries may be especially useful to app users.

To search for the items displayed as Homepage featured content, create a query using the PortalInfo.getHomepageFeaturedContentGroupQuery method to set the query string. Use the query to find the group containing the featured content, and then perform a second search to find the items shared with that group.

PortalInfo info = portal.fetchPortalInfo();
PortalQueryParams featuredContentGroupQuery = 
  new PortalQueryParams(info.getHomepageFeaturedContentGroupQuery());
PortalQueryResultSet<PortalGroup> featuredContentGroupResults = 
if (! featuredContentGroupResults.getResults().isEmpty()) {
  PortalGroup group = featuredContentGroupResults.getResults().get(0);
  PortalQueryParams groupContentQuery = new PortalQueryParams();
  PortalQueryResultSet<PortalItem> groupContentResults = 
  // Display the results.

To search for the items displayed in the Gallery, create a query using the PortalInfo.getHomepageFeaturedContentGroupQuery method to set the query string. Note that if the administrator has chosen to show most-viewed items, this query will in fact return portal items (not groups).

Get a list of configured basemaps

Many apps allow a user to change the basemap used to provide context for other data shown in a map. Portal administrators can configure the list of basemaps they want to be available to a user of a portal by sharing web maps into a specific group. You can use another predefined query to find out the basemaps group for a portal, and from there you can list the items in that group.

PortalQueryParams basemapsGroupQuery = 
  new PortalQueryParams(info.getBasemapGalleryGroupQuery());
PortalQueryResultSet<PortalGroup> basemapGroupResults = 

For each web map in the result set, you can show the thumbnail and title of the item in a gallery or list. You can easily display a web map from the selected item by using its ID.

Get featured groups

A list of featured groups can be configured to appear on the Groups and My Organization pages of the website. Searching for these groups is slightly different from the predefined queries above, as there are multiple queries used to find all of the groups. You can get a list of queries from the portal, each of which should return a single featured group.

PortalInfo info = portal.fetchPortalInfo();
List<String> querys = info.getFeaturedGroupsQueries();
int totalResults = 0;
for (String query : querys) {
  PortalQueryParams featuredGroupsQuery = new PortalQueryParams(query);
  PortalQueryResultSet<PortalGroup> featuredGroupsResults = portal.findGroups(featuredGroupsQuery);
  if (! featuredGroupsResults.getResults().isEmpty()) {
    // Use the groups found by the query.

Display many search results

Searches may return just a few results, or many thousands of results. To reduce network traffic and memory , search results are returned in batches (by default, only the first 10 are returned), along with a count of the total results found on the portal.

Often, the required item is in the first set of results, but your app can let the user decide if they need to see more items, for example, by scrolling past the end of a list, switching to the next page of results, or by tapping a more results button. You can easily issue another query to find the next set of results, as the result set from your first query constructs the correct subsequent query for you.

The code below uses creates a PortalQueryParams, sets the initial query, and calls the Portal.findItems method. After iterating through the initial results, PortalQueryParams.getNextQueryParams is used to get the correct query to find the next set of results (you can check the getQuery method to find out how this works). If this query is not null, then a second call to findItems is made. This pattern is repeated until getNextQueryParams returns null, indicating there are no more results to fetch.

PortalQueryResultSet<PortalItem> resultSet = null;
PortalQueryParams queryParams = new PortalQueryParams("global rainfall");
while ( queryParams != null ) {
  resultSet = portal.findItems(queryParams);
  if (resultSet == null) continue;
  for (PortalItem result : resultSet.getResults()) {
    // Display the result
  queryParams = resultSet.getNextQueryParams();

If you want to retrieve results in larger batches, use the PortalQueryParams.setLimit method to change the batch size.