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"
}
The example below demonstrate advanced search query:
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
filter=username:"jsmith"
For Items
title
tags
type
Keywords type
owner
Example:
filter=tags:"public"
For Groups
title
type
Keywords 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
and esri
, not including arcgis
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
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 blocks Copy q=title:test\:abc
- Enclose query using double quotes
""
.Use dark colors for code blocks Copy 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:
Field | Details |
---|---|
| ID of the item.
|
| Owner of the item.
|
| The date, expressed in UNIX time, that items were created.
|
| The date, expressed in UNIX time, that items were last modified.
|
| Item title.
|
| Returns the type of item and is a predefined field. See Items and item types for a listing of the types.
|
| Type keywords for an item. See Items and item types for a listing of the types.
|
| The item description.
|
| The tag field for an item.
|
| The snippet, or summary, of an item.
|
| The access information for an item.
|
| The access field of an item. You will only see private or shared items that you can access. Values: |
| The ID of the group. It returns the items within that group.
|
| Number of ratings for an item.
|
| Number of comments on an item.
|
| Average rating for an item.
|
| 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,
|
| The ID of the organization. It returns items within the given organization.
|
| Organization content categories.
|
| Item content status. Organization members, as well as public members for verified organizations, can search for items that have these badges using the Values: |
| Introduced at ArcGIS Enterprise 11.4 to support item classification. The classification value assigned to items. Examples
|
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:
Field | Details |
---|---|
| The group ID.
|
| The group title.
|
| The group owner.
|
| The group description.
|
| Type keywords for a group.
|
| The snippet, or summary, of the group.
|
| The tag field for the group.
|
| The contact info for the group.
|
| The date, expressed in UNIX time, that groups were created.
|
| The date, expressed in UNIX time, that groups were last modified.
|
| The access field returns either public, organization, or private groups. For example, Values: |
| The Values: |
| The ID of the organization.
|