ArcGIS Runtime SDK for .NET

Search for content

Portals can contain a huge amount of information. 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 having specific tags.

Portal administrators can configure a number of settings to highlight specific content to users, such as the set of available basemaps,the content featured in the portal homepage and gallery, and the featured groups for the organization. Learn how to easily find featured basemaps, content, and groups.

Searching is done from the ArcGISPortal 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.

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 PortalQueryParameters object and pass the search term (string) into the constructor. Then use the PortalQueryParameters in a call to the FindItemsAsync method. The resulting PortalQueryResultSet<PortalItem> contains portal items that use the search term in any of the searched fields.

Tip:

Use PortalQueryParameters with an Envelope to find portal items that intersect a specified extent. You can optionally provide a query string to define search parameters that include both spatial and attribute criteria.

var portal = await ArcGISPortal.CreateAsync();
// Create a new SearchParameters (or SpatialSearchParameters)
var searchParams = new PortalQueryParameters(searchText);
searchParams.Limit = 25;
// Search the portal for items matching the search criteria
PortalQueryResultSet<PortalItem> searchResultInfo = await portal.FindItemsAsync(searchParams);


// Get the enumeration of result items
IEnumerable<PortalItem> searchResults = searchResultInfo.Results;
 // Iterate thru the results 
foreach(PortalItem item in searchResults)
{
    // ... work with items here ...
}
ArcGISPortal search methods, such as FindItemsAsync, FindGroupsAsync, and FindUsersAsync allow you to provide an optional CancellationToken argument that gives the user the ability to cancel execution of the search task.

Note:

Remember, only the items that are accessible to the authenticated user of the portal will be included in the search results. When a user is not authenticated, only publicly shared items are found.

By default, 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.

Order the search results

If there are more than a few results, you may want to help your user narrow down the results to find items of most interest. Your app can show the most recently updated results to the user first, sorting search results by the date they were last modified, in descending order.

searchParams.SortField = "modified";
searchParams.SortOrder = PortalQuerySortOrder.Descending;

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 search to find only web maps.

The expression used to set the QueryString property can further refine search criteria using specific fields as well. In your query expression, use a property identifier (such as orgid, owner, title, or type), followed by a colon and the value. The following expression, for example, will search for web map items within the portal organization with id 123ABC that match the term Cache.

var searchParams = new Esri.ArcGISRuntime.Portal.PortalQueryParameters("\"Cache\" orgid:\"123ABC\" type:(\"web map\" NOT \"web mapping application\")");
See the ArcGIS Rest API search reference for more information, including the fields available for use in your query expression.

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

Find groups by keyword

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

The following example searches for portal groups with the specified name (title) that do not require an invitation to join. A maximum of three results are returned, sorted by group creation date (oldest to newest).

// Build a query that searches for a specified group name (Title)
var queryString = string.Format("title:\"{0}\" isinvitationonly:{1}", groupName, "false");


// Create a SearchParameters object, set options
var searchGroupParameters = new PortalQueryParameters(queryString)
{
    SortField = "created",
    SortOrder = PortalQuerySortOrder.Ascending,
    Limit = 5
};


// Execute the search
var groupResultInfo = await portal.FindGroupsAsync(searchGroupParameters);
var groupSearchResults = groupResultInfo.Results;

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.

Continuing from the previous example, the code below finds items for each result of a group search.

// Report groups and some of the items they contain
Debug.Print("Items for Selected Groups");
// Iterate thru groups in the results
foreach (PortalGroup group in groupSearchResults)
{
    // Print the group name
    Debug.Print(group.Title);
    // Define a new search for (a max of three) items with this group ID
    var groupSearchItemsParams = new PortalQueryParameters("group:" + group.GroupId);
    groupSearchItemsParams.Limit = 3;
    // Perform the search and get the results
    var itemResultInfo = await portal.FindItemsAsync(groupSearchItemsParams);
    var itemSearchResults = itemResultInfo.Results;


    // Print the name of each item in the results (if any)
    if(itemSearchResults.Count() == 0) { Debug.Print("\t--No Items"); }
    foreach (PortalItem item in itemSearchResults)
    {
        Debug.Print("\t--" + item.Title);
        SearchResultsList.Items.Add(item);
    }
}
// Output for a search of groups with "Logan" in the name ...
//Items for Selected Groups
//Logan 911
//    --Story Map Tour
//    --Finder
//    --Basic Viewer
//Logan City Council / Alliance Collaboration
//    --No Items
//Logan City Open Data
//    --Logan Park Finder
//    --Logan Planning Scheme Dec 2015
//    --Logan City Sharps Disposal Locations

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.

You can create a query string to find an item using its (unique) id as shown in the following example.

var portal = await ArcGISPortal.CreateAsync();
// Create a new SearchParameters with a query string that specifies the item ID
var searchParams = new PortalQueryParameters("id:" + itemId);
// Search the portal for an item matching the id
PortalQueryResultSet<PortalItem> searchResultInfo = await portal.FindItemsAsync(searchParams);


// Get the enumeration of result items
IEnumerable<PortalItem> searchResults = searchResultInfo.Results;
// There should either be one or zero items in the results
PortalItem item = searchResults.FirstOrDefault();
if (item == null) { return; }


// ... work with the item here ...
You can also open an ArcGISPortalItem directly using the static CreateAsync method on the ArcGISPortalItem class, as shown in the following example.
var portalItem = PortalItem.CreateAsync(portal, itemId);

Define a query

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

var portalSearchParams = new PortalQueryParameters("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.

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

Tip:

You can also search using ranges of dates that 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 for featured basemaps, content, and groups

Portal administrators can configure a number of settings to highlight specific content to users. Configurable settings include the set of available basemaps, content featured in the portal homepage and gallery, and featured groups for the organization.

Get Home page and Gallery featured content

Administrators can configure two groups that contain featured content to show in different situations. The portal 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 also display featured content from a chosen group, and the maximum number of items displayed can be separately configured. 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 featured items are web maps, app users may want to browse a list of these maps, and then open them.

The simplest way to search for the portal items featured as homepage content is to use the Portal.GetHomePageFeaturedContentAsync method. Note that this returns all of the featured items and is not limited by the number of items the portal administrator may have configured to be shown. The featured content count can be found with PortalInfo.HomePageFeaturedContentCount.

// Open the portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();

// Get the featured content
IEnumerable<PortalItem> featuredContent = await portal.GetHomePageFeaturedContentAsync();

// Use Linq to only take as many items as are specified by the portal for display
featuredContent = featuredContent.Take(portal.PortalInfo.HomePageFeaturedContentCount);

Similarly, the GetFeaturedItemsAsync method returns the set of featured items shown in the gallery.

// Open the portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();

// Get the featured content
IEnumerable<PortalItem> featuredContent = await portal.GetFeaturedItemsAsync();

Alternatively, you can find the group or groups configured to contain featured content or items by using PortalInfo.FeaturedItemsGroupQuery or PortalInfo.HomePageFeaturedContentGroupQuery and using this value to set the query string for a PortalQueryParameters. You can then use the query to find the group or groups, and in turn query for the PortalItems contained. One advantage of this approach is that query results are returned in batches, suitable for paging.

// Open the portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();
// Get the portal info
PortalInfo info = portal.PortalInfo;
// Set up the featured content group query
PortalQueryParameters featuredContentGroupQuery = new PortalQueryParameters(info.HomePageFeaturedContentGroupQuery);
// Get the featured content group
PortalQueryResultSet<PortalGroup> results = await portal.FindGroupsAsync(featuredContentGroupQuery);


// Take the first group in the results
PortalGroup group = results.Results.FirstOrDefault();
// Return if the result is empty
if (group == null) { return; }

// Set up query for the items in the featured group
PortalQueryParamters itemsSearchParams = new PortalQueryParameters("group:" + group.GroupId);
// Run the search
PortalQueryResultSet<PortalItem> featuredItemsResultInfo = await portal.FindItemsAsync(itemsSearchParams);
// Get the result portal items
IEnumerable<PortalItem> featuredItems = featuredItemsResultInfo.Results;

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.

// Open the portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();

// Get the basemaps
IEnumerable<Basemap> basemaps = await portal.GetBasemapsAsync();

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.

Additionally, you can use another predefined query (PortalInfo.BasemapGalleryGroupQuery) to find out the basemaps group for a portal if required, and from there you can list the items in that group.

Get featured groups

A list of featured groups can be configured to appear on the Groups and My Organization pages of the website. You can find out these groups, and in turn can get the contents as you would for any other group.

// Open the portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();

// Get the groups
IEnumerable<PortalGroup> groups = await portal.GetFeaturedGroupsAsync();

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 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 following code creates a PortalQueryParameters, sets the initial query, and calls the ArcGISPortal.FindItemsAsync method. After iterating through the initial results, the PortalQueryResults<T>.NextQueryParameters method is used to get the correct query to find the next set of results. If this query is not null, then a second call to FindItemsAsync is made. This pattern is repeated until PortalQueryResults<T>.NextQueryParameters method returns null, indicating there are no more results to get.

// See if all results have been processed
if (_gotAllResults) { return; }


// Create a new PortalQueryParameters (if it doesn't exist, this is the first query)
if(_portalSearchParams == null)
{
    // Set the query text and the limit
    _portalSearchParams = new PortalQueryParameters("Cache Valley");
    _portalSearchParams.Limit = 10;
    _portalSearchParams.StartIndex = 1;         
}


// Search for portal items using the SearchParameters
PortalQueryResultSet<PortalItem> searchResultInfo = await _portal.FindItemsAsync(_portalSearchParams);
 // ... work with search results here ...
 // Get the NextQueryParameters so the next search will return the appropriate set of results
_portalSearchParams = searchResultInfo.NextQueryParameters;
 // Set the flag for all results, if NextQueryParameters is null all results have been processed
_gotAllResults = _portalSearchParams == null;
Note:

When all results have been returned for a search, PortalQueryResults<T>.NextQueryParameters returns null.

If you want to retrieve results in larger batches, use SearchParameters.Limit to change the batch size.

Related topics