Search reference

Overview

The ArcGIS Portal Directory REST API has a full-featured text search engine that allows you to create your own queries.

The portal uses a powerful search engine to index information and to allow full text searching. The search engine uses many different inputs to rank and display appropriate results. This makes search fuzzy, which is ideal for human interaction, but can cause issues when looking for specific records programmatically. For example, the order of results may vary each time a search is performed. Developers should exercise care when using search to locate specific items and groups as part of automated scripts. It is recommended to search for items and groups by their ID when possible.

The following list specifies the ArcGIS REST API search operations that are used to find items, groups, and users:

Search ranking

Items are ranked on a variety of different factors including, but not limited to, the number of times search terms appear in item, view counts, and authoritative or deprecated labels.

Search terms

A query is broken up into terms and operators. There are two kinds of terms: single term and phrase. A single term is a single word, such as fire or California. A phrase is a group of words. To create a phrase, surround multiple words with double quotation marks, such as "fire maps". Single quotation marks are not supported for a multiple-word search. Multiple terms can be combined with Boolean operators to form a more complex query.

Fields

When performing a search for items or groups, you can either specify a field or use the default fields.

For items, the default fields are as follows:

  • title
  • tags
  • snippet
  • description
  • type
  • typekeywords

For groups, the default fields are as follows:

  • id
  • title
  • description
  • snippet
  • tags
  • owner

The best match is always returned. For example, a search for fires will return records containing fire. You can search any field by typing the field name followed by a colon ":" and the search term. If you don't use a field indicator, the default fields will be searched.

As an example, to search for a layer package item that has San Francisco in the title, the query would be as follows:

Use dark colors for code blocksCopy
1
2
3
{
  title:"San Francisco" AND type:"Layer Package"
}

The example below demonstrate advanced search query:

Use dark colors for code blocksCopy
1
https://org.arcgis.com/home/search.html?q=flood&q=flood&restrict=false&contentstatus=org_authoritative&focus=maps-webmaps&modified=last30Days&access=public

Query Vs Filter

As a general rule, filter (i.e. defined in filter parameter) should be used instead of query:

  • for binary yes/no searches.
  • for queries on exact values.

Query (i.e. defined in q parameter) should be used instead of filter:

  • for full-text search.
  • for cases where the result depends on a relevance score.

The following fields are supported for the filter parameter:

For Users

  • username
  • firstname
  • lastname
  • fullname
  • email
Use dark colors for code blocksCopy
1
filter=username:"jsmith"

For Items

  • title
  • tags
  • typeKeywords
  • type
  • owner

Example:

Use dark colors for code blocksCopy
1
filter=tags:"public"

For Groups

  • title
  • typeKeywords
  • owner

Example:

Use dark colors for code blocksCopy
1
filter=owner:"jsmith"

Term modifiers

A number of term modifiers are supported to provide a wide range of searching options.

Range searches

Range searches allow you to match a single field or multiple field values between the lower and upper bounds. Range queries can be inclusive or exclusive of the upper and lower bounds. Inclusive range queries are denoted by brackets ([]). Exclusive range queries are denoted by braces ({}).

For example, to find all items created between December 1, 2009, and December 9, 2009, the search expression is as follows:

Use dark colors for code blocksCopy
1
2
3
{
  created: [1259692864000 TO 1260384065000]
}

The created field contains the date and time an item is created in UNIX time. UNIX time is defined as the number of seconds that have elapsed since midnight on January 1, 1970. The portal stores time in milliseconds, so you need to add three zeros to the end of the UNIX time.

Range searches are not reserved for date fields. You can also use range queries with nondate fields:

Use dark colors for code blocksCopy
1
2
3
{
  owner:{arcgis_explorer TO esri}
}

This will find all items from the owners between arcgis_explorer and esri, not including arcgis_explorer and esri.

Boolean operators

Boolean operators allow terms to be combined through logic operators. The Portal API supports AND, OR, NOT, and "-" as Boolean operators. Boolean operators must be in all caps.

AND

The AND operator is the default conjunction operator. This means that if there is no Boolean operator between two terms, the AND operator is used. The AND operator performs matching where both terms exist in either the given field or the default fields. This is equivalent to an intersection using sets.

To search for an item that contains the terms recent and fires, use the following query:

Use dark colors for code blocksCopy
1
2
3
{
  recent fires
}

or

Use dark colors for code blocksCopy
1
2
3
{
  recent AND fires
}

OR

The OR operator links two terms and finds a match if either term exists. This is equivalent to a union using sets.

To search for an item that contains the terms "recent fires" or fires, use the following query:

Use dark colors for code blocksCopy
1
2
3
{
  "recent fires" OR fires
}

NOT

The NOT operator excludes items that contain the term after NOT. This is equivalent to a difference using sets.

To search for documents that contain California but not Imagery, use the following query:

Use dark colors for code blocksCopy
1
2
3
{
  California NOT Imagery
}

The NOT operator cannot be used with only one term.

-

The -, or the prohibit operator, excludes items that contain the term after the - symbol.

To search for documents that contain California but not Imagery, use the following query:

Use dark colors for code blocksCopy
1
2
3
{
  California -Imagery
}

Special character searches

Search supports querying with special characters. These characters include: + - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

There are two ways to search using special characters:

  • Escape special characters using \.
    Use dark colors for code blocksCopy
    1
    q=title:test\:abc
  • Enclose query using double quotes "".
    Use dark colors for code blocksCopy
    1
    q=title:"test:abc"

Grouping

You can create subqueries using parentheses to group clauses. This can be useful to control the Boolean logic for a query.

To search for either California or recent and fires, create the following expression:

Use dark colors for code blocksCopy
1
2
3
{
  (California OR recent) AND fires
}

Field grouping

You can group multiple clauses to a single field using parentheses.

To search for a title that contains the phrase "population change" and the word recent, use the following query:

Use dark colors for code blocksCopy
1
2
3
{
  title:("population change" recent)
}

Item fields

You can refine your item searches by using specific fields in your search string. These fields include the following:

FieldDetails

id

ID of the item.

Use dark colors for code blocksCopy
1
id:4e770315ad9049e7950b552aa1e40869

owner

Owner of the item.

Use dark colors for code blocksCopy
1
owner:esri

created

The date, expressed in UNIX time, that items were created.

Use dark colors for code blocksCopy
1
created: [1249084800000 TO 1249548000000]

modified

The date, expressed in UNIX time, that items were last modified.

Use dark colors for code blocksCopy
1
modified: [1249084800000 TO 1249548000000]

title

Item title.

Use dark colors for code blocksCopy
1
title:"Southern California"

type

Returns the type of item and is a predefined field. See Items and item types for a listing of the types.

Use dark colors for code blocksCopy
1
type:map

typekeywords

Type keywords for an item. See Items and item types for a listing of the types.

Use dark colors for code blocksCopy
1
typekeywords:tool

description

The item description.

Use dark colors for code blocksCopy
1
description:California

tags

The tag field for an item.

Use dark colors for code blocksCopy
1
tags:"San Francisco"

snippet

The snippet, or summary, of an item.

Use dark colors for code blocksCopy
1
snippet:"natural resources"

accessinformation

The access information for an item.

Use dark colors for code blocksCopy
1
accessinformation:esri

access

The access field of an item. You will only see private or shared items that you can access.

Values: public | private | org | shared

group

The ID of the group. It returns the items within that group.

Use dark colors for code blocksCopy
1
group:1652a410f59c4d8f98fb87b25e0a2669

numratings

Number of ratings for an item.

Use dark colors for code blocksCopy
1
numratings:6

numcomments

Number of comments on an item.

Use dark colors for code blocksCopy
1
numcomments:[1 TO 3]

avgrating

Average rating for an item.

Use dark colors for code blocksCopy
1
avgrating:3.5

culture

Culture, or the locale, of an item. The search engine treats the two parts of the culture code as two terms, and searches for individual languages can be done. For example, culture:en returns all records that have an "en" in their culture code. There may be overlaps between the codes used for language and the codes used for country, for instance, fr-FR, but if the client needs to target a code with this problem, they can pass in the complete code.

Use dark colors for code blocksCopy
1
culture:en-US

orgid

The ID of the organization. It returns items within the given organization.

Use dark colors for code blocksCopy
1
orgid:5uh3wwYLNzBuU0Ef

categories

Organization content categories.

Use dark colors for code blocksCopy
1
categories:"Historical Maps"

contentStatus

Item content status. Organization members, as well as public members for verified organizations, can search for items that have these badges using the contentStatus filter. Authoritative items are automatically protected to prevent accidental deletion and are boosted in search results to increase visibility and encourage use.

Values: null | deprecated | org_authoritative | public_authoritative

classification

Introduced at ArcGIS Enterprise 11.4 to support item classification. The classification value assigned to items.

Examples

Use dark colors for code blocksCopy
1
2
3
classification:"Restricted;Proprietary"

classification:(Proprietary)

Group fields

You can filter your searches on groups by using specific fields in your search string. Only public groups or groups to which you have access will be searched. These fields include the following:

FieldDetails

id

The group ID.

Use dark colors for code blocksCopy
1
id:1db70a32f5f84ea9a88f5f460f22557b

title

The group title.

Use dark colors for code blocksCopy
1
title:redlands

owner

The group owner.

Use dark colors for code blocksCopy
1
owner:esri

description

The group description.

Use dark colors for code blocksCopy
1
description:"street maps"

typekeywords

Type keywords for a group.

Use dark colors for code blocksCopy
1
typekeywords:fire

snippet

The snippet, or summary, of the group.

Use dark colors for code blocksCopy
1
snippet:transportation

tags

The tag field for the group.

Use dark colors for code blocksCopy
1
tags:"bike lanes"

phone

The contact info for the group.

Use dark colors for code blocksCopy
1
phone:jsmith33@esri.com

created

The date, expressed in UNIX time, that groups were created.

Use dark colors for code blocksCopy
1
created:1247085176000

modified

The date, expressed in UNIX time, that groups were last modified.

Use dark colors for code blocksCopy
1
modified:1247085176000

access

The access field returns either public, organization, or private groups. For example, access:org returns groups shared with the organization.

Values: private | org | public

isinvitationonly

The isinvitationonly field returns groups that require an invitation to join.

Values: true | false

orgid

The ID of the organization.

Use dark colors for code blocksCopy
1
orgid:5uh3wwYLNzBuU0Ef

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.