Search reference
Overview
The ArcGIS Portal API has a full-featured text search engine that allows you to create your own queries.
Care should be taken when using ArcGIS REST API search operations (search, user search, group search, group content search) to find items, groups, and users programmatically. The Portal uses a powerful search engine to index information and to allow full text searching on it. This search engine uses many different inputs to find the appropriate results and rank them. This often makes search 'fuzzy', making it ideal for human interaction, but not necessarily ideal for looking for specific records programmatically. Developers should avoid using search to find specific items (e.g. by title) as the results of these types of queries might change as the search engine evolves.
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.
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.
Also, 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
Example
filter=username:"jsmith"
For Items
- title
- tags
- typeKeywords
- type
- name
- 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
}
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 | ID of the item. Example |
| owner | Owner of the item. Example |
| created | The date, expressed in UNIX time, that items were created. Example |
| modified | The date, expressed in UNIX time, that items were last modified. Example |
| title | Item title. Example |
| type | Type returns the type of item and is a predefined field. See Items and item types for a listing of the types. Example |
| typekeywords | Type keywords for an item. See Items and item types for a listing of the types. Example |
| description | The item description. Example |
| tags | The tag field for an item. Example |
| snippet | The snippet, or summary, of an item. Example |
| accessinformation | The access information for an item. Example |
| 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 |
| group | The ID of the group. It returns the items within that group. Example |
| numratings | Number of ratings for an item. Example |
| numcomments | Number of comments on an item. Example |
| avgrating | Average rating for an item. Example |
| 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 |
| orgid | The ID of the organization. It returns items within the given organization. Example |
| categories | Organization content categories. Example |
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 |
|---|---|
| id | The group ID. Example |
| title | The group title. Example |
| owner | The group owner. Example |
| description | The group description. Example |
| typekeywords | Type keywords for a group. Example |
| snippet | The snippet, or summary, of the group. Example |
| tags | The tag field for the group. Example |
| phone | The contact info for the group. Example |
| created | The date, expressed in UNIX time, that groups were created. Example |
| modified | The date, expressed in UNIX time, that groups were last modified. Example |
| 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 |
| isinvitationonly | The isinvitationonly field returns groups that require an invitation to join. Values: true | false Example |
| orgid | The ID of the organization. |