Skip To Content

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:


{
  title:"San Francisco" AND type:"Layer Package"
}
Note:

The field is only valid for the term that it directly precedes. Use double quotation marks to group a phrase that consists of multiple words to be the keywords for the field. Item type filter type is case sensitive and must be surrounded by double quotation marks for exact item type matching; failure to do so can result in a nonexact match, thus returning incorrect results. For example, use type:"Web Map" if you are only interested in finding web map items; type:"web map" will return both web map and Web Mapping Application if both exist, type:Web Map will return non-web map items also, such as web scene, CityEngine web scene, and web mapping application, if any exist.

The example below demonstrate advanced search query:


https://org.arcgis.com/home/search.html?q=flood&restrict=false&contentstatus=org_authoritative&focus=maps-webmaps&modified=last30Days&access=public

q=flood //Search query for flood
contentstatus=org_authoritative //Return public and org authoritative items
focus=maps-webmaps //Only return webmaps
modified=last30Days //Has been modified within the last 30 days
access=public //Sharing level set to 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

Example

filter=username:"jsmith"

For Items

  • title
  • tags
  • typeKeywords
  • type
  • owner

Example

filter=tags:"public"

For Groups

  • title
  • typeKeywords
  • owner

Example

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:


{
  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:


{
  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:


{
  recent fires
}

or


{
  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:


{
  "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:


{
  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:


{
  California -Imagery
}

Special character searches

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

There are two ways to search using special characters:

  • Escape special characters using \. Example: q=title:test\:abc
  • Enclose query using double quotes "". Example: 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:


{
  (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:


{
  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.

Example

id:4e770315ad9049e7950b552aa1e40869
owner

Owner of the item.

Example

owner:esri
created

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

Example

created: [1249084800000 TO 1249548000000]
modified

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

Example

modified: [1249084800000 TO 1249548000000]
title

Item title.

Example

title:"Southern California"
type

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

Example

type:map
typekeywords

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

Example

typekeywords:tool
description

The item description.

Example

description:California
tags

The tag field for an item.

Example

tags:"San Francisco"
snippet

The snippet, or summary, of an item.

Example

snippet:"natural resources"
accessinformation

The access information for an item.

Example

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

Example

access:public
group

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

Example

group:1652a410f59c4d8f98fb87b25e0a2669
numratings

Number of ratings for an item.

Example

numratings:6
numcomments

Number of comments on an item.

Example

numcomments:[1 TO 3]
avgrating

Average rating for an item.

Example

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.

Example

culture:en-US
orgid

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

Example

orgid:5uh3wwYLNzBuU0Ef
categories

Organization content categories.

Example

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

Example

"contentStatus": "org_authoritative"

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.

Example

id:1db70a32f5f84ea9a88f5f460f22557b
title

The group title.

Example

title:redlands
owner

The group owner.

Example

owner:esri
description

The group description.

Example

description:"street maps"
typekeywords

Type keywords for a group.

Example

typekeywords:fire
snippet

The snippet, or summary, of the group.

Example

snippet:transportation
tags

The tag field for the group.

Example

tags:"bike lanes"
phone

The contact info for the group.

Example

phone:jsmith33@esri.com
created

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

Example

created:1247085176000
modified

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

Example

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

Example

access:org
isinvitationonly

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

Values: true | false

Example

isinvitationonly:false
orgid

The ID of the organization.

orgid:5uh3wwYLNzBuU0Ef