Overview
The Cloudinary API search
method allows you fine control on filtering and retrieving information on all the assets in your account with the help of query expressions in a Lucene-like query language. A few examples of what you can accomplish using the search
method include:
- Searching by descriptive attributes such as public ID, filename, folders, tags, context, etc.
- Searching by file details such as type, format, file size, dimensions, etc.
- Searching by embedded data such as Exif, XMP, etc.
- Searching by analyzed data such as the number of faces, predominant colors, auto-tags, etc.
- Requesting aggregation counts on specified parameters, for example the number of assets found broken down by file format.
The search
method is part of the Admin API. See the documentation for more information on authentication, pagination, error handling and usage limits.
IMPORTANT: This functionality is available only to customers with the Advanced Extra plan or higher and is currently in Beta. Contact us to activate this feature for your account.
Quick example
Find images tagged with 'kitten', that have been uploaded within the last day, and are larger than 1MB in size. In the response, sort the results by public_id
in descending order, and limit the returned results to 30 resources:
Cloudinary::Search.expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m').sort_by('public_id','desc').max_results(30).execute
Tiers
The search
capabilities described here are available to customers with the Advanced Extra plan or higher. The search functionality is furthermore divided into 2 tiers:
- Tier 1 includes support for using the
search
method with a large selection of fields, operators, and search syntax. - Tier 2 includes extra search functionality at an additional cost, including support for search expressions based on image analysis and metadata fields as well as support for aggregated counting information in the response. Functionality that is limited to tier 2 is noted as such. Please contact support to activate this option.
Note: All customers have access to the basic search (listing) functionality as described in the Browse resources section of the Admin API documentation.
Syntax
Cloudinary::Search.execute
new \Cloudinary\Search()->execute();
cloudinary.api.search().execute()
cloudinary.v2.search.execute(function(error, result) {console.log(result)});
cloudinary.search().execute(ObjectUtils.emptyMap());
GET https://api.cloudinary.com/v1_1/<cloud_name>/resources/search
Parameters
All the parameters of the search
method are optional. Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.
expression
- The (Lucene-like) string expression specifying the search query. If this parameter is not provided then all resources are listed (up tomax_results
). For details, see the expressions section below.sort_by
- An array of key value pairs where the key is the field to sort by and the value is the direction. Valid sort directions areasc
ordesc
(the default value). If this parameter is not provided then the results are sorted by relevance (results with higher relevance are listed first). You can specify more than onesort_by
parameter; results will be sorted according to the order of the fields provided.max_results
- The maximum number of results to return. Default50
. Maximum500
.next_cursor
- When a search request has more results to return thanmax_results
, thenext_cursor
value is returned as part of the response. You can then specify this value as thenext_cursor
parameter of the following request.with_field
- The name of an additional asset attribute to include for each asset in the response. Possible value:context
,tags
, and for Tier 2 alsoimage_metadata
, andimage_analysis
.aggregate
- (Tier 2 only) The names of fields (attributes) for which aggregation counts should be calculated and returned in the response. Supported parameters:resource_type
,type
,pixels
(only the image assets in the response are aggregated),duration
(only the video assets in the response are aggregated),format
, andbytes
. For aggregation fields without discrete values, the results are divided into categories. For example:bytes
are divided into small (<500 kb), medium (500 - 5mb), large (5mb - 100 mb), and huge (>100 mb).- Video
duration
is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min).
Examples
Find assets containing 'cat' in any field (attribute), include context metadata and tags in the details of each resource, and limit the returned results to 10 resources:
Cloudinary::Api.search.expression('cat').with_field('context').with_field('tags').max_results(10).execute
Find assets containing 'cat' in any field but not 'kitten' in the tags field, sort the results by public_id in descending order, and calculate an aggregation count based on the values of the format field:
Cloudinary::Api.search.expression('cat -tags:kitten').sort_by('public_id','desc').aggregate('format').execute
For more examples of expressions, see the expression examples section below.
Response
The response includes the total count of assets matching the search criteria, the time taken to process the request, any aggregation counts requested (tier 2 only), and the details of each of the assets (resources) found.
Sample JSON Response:
{ "total_count": 32, "time": 30, "aggregations": { "format": { "png": 4, "jpg": 21, "mp4": 3, "doc": 4 } }, "next_cursor": "b16b8bd80426df43a107f26b0348", "resources": [ { "public_id": "sample", "folder": "", "filename": "sample", "format": "png", "version": 1492606756, "resource_type": "image", "type": "upload", "created_at": "2017-04-03T09:56:49+00:00", "uploaded_at": "2017-04-19T12:59:16+00:00", "bytes": 3381, "backup_bytes": 16905, "width": 241, "height": 51, "aspect_ratio": 4.7254901960784315, "pixels": 12291, "context": {}, "image_analysis": { "face_count": 0, "faces": [], "grayscale": true, "illustration_score": 1, "transparent": false, "colors": { "gray": 96.7 } }, "url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png", "secure_url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png", "status": "active", "access_mode": "public" }, { "public_id": "dog", … … } … }
Expressions
The expression parameter in the search
method describes the query string for filtering the assets in your account. A query string contains search terms that can be combined with Boolean operators to form a more complex query. You can also limit your search to specific fields or you can run your query on all fields.
If your search term contains a space or other reserved characters such as a colon, place the search term in quotes. For example, "hello dolly" or "16:9"
You can also append an asterisk to the end of your search term in order to look for the search term as a prefix. For example, to search for "cat", "cats" or "catfish", you can use the search term:
cat*
Fields
By default, the term is searched for in all the asset's string fields, except for strings with a value that is limited to a fixed list (e.g. access_mode is limited to the values 'public' or 'authenticated'). The search can be confined to a specific field (including fields not automatically included in the default search) by typing the field name followed by a colon : (or other relevant operator) and then the term you are looking for. For example, if you want to find assets of type "authenticated":
type:authenticated
Field names are case sensitive. For a list of supported fields, see the Expression fields reference.
Field operators
When using fields in your query, you need to indicate the relationship between the search value and the field. For example, whether you are searching for assets where the field value is greater than, less than, or equal to the value you specify. The following operators are supported: : = > >= < <= [ ] { }
The supported operators and values you can use for a particular field depend on the type of that field, as detailed in Field types and supported operators.
String operators - exact or tokenized searches
Using the =
operator finds a match where the value is an exact match, whereas using the :
operator finds a match where the value matches any complete token within the string value (e.g., whitespace within the string value breaks it up into individual tokens (or words)). For example:
tags=cat
Finds a match only when the tag equals cat
tags:cat
Finds a match as long as one of the tokens in a tag entry includes cat, for example, a tag value of "cat and dog" returns a match but "catfish" doesn't.
Notes:
- Some string fields support only exact matches. In these cases, even if you use a
:
operator, it will still behave as an exact match search. Fields that support exact match only are indicated in the Expression fields reference table. - The values of some string fields are case-sensitive, and some are a combination: case-sensitive when performing an exact (
=
) search and case-insensitive when performing a tokenized (:
) search. Those that support exact match only are usually case-sensitive, while free text fields are either case-insensitive or a combination. The case sensitivity of each string field is indicated in the Expression fields reference table.
Range operators - inclusive or exclusive ranges
To search for a value that falls within a specific range, enclose the range values within square brackets to include the specified values or within curly brackets to exclude the specified values, and separated with the TO
operator. For example, to find assets with a file size within the range 1000 to 20000 bytes:
bytes:{1000 TO 20000}
You can also search for an alphabetic range, using any alphanumeric characters in your range query, for example, searching for public_ids with names that are alphabetically between "a" and "mz":
public_id:[a TO mz]
Boolean Operators
Boolean operators allow search terms to be combined through logic operators. Note that Boolean operators must be ALL CAPS.
Operator | Example | Description |
---|---|---|
OR or || |
tags:cat OR public_id:cat tags:cat || public_id:cat tags:cat public_id:cat |
Links two search terms and finds a match if either of the terms exist. This is the default operator for linking 2 terms. |
AND or && |
tags:cat AND public_id:cat tags:cat && public_id:cat |
Links two search terms and finds a match if both of the terms exist. |
+ |
+cat +lion | Must have the term after the + symbol. |
NOT or ! |
animals NOT lions animals !lions |
Excludes assets that contain the term after NOT. |
- |
-animals -lions | Must not have the term after the - symbol. |
Notes:
Use parentheses to group terms to form sub-queries. This can be useful if you want to control the boolean logic for a query. For example, to search for either "cat" or "lion", and "animal" use the query:
(cat OR lion) AND animal
If only a single term is used in the expression without an operator then the
+
operator is implied. For example, the following expressions are identical:animal +animal
If part of the query evaluates to 'must have', either by using the
+
operator or by an intersection of 2 terms with theAND
operator, then any additional terms linked with theOR
operator will only be used for prioritizing the order of the results. For example, to search for "animals" and prioritize results that also have "cats":+animals OR cats +animals cats
Expression examples
Assets containing "shirt" and with a tag that exactly matches "cotton":
shirt AND tags=cotton
Images with a width between 200 and 1028, and an aspect_ratio of 16:9:
resource_type:image AND width:{200 TO 1028} AND aspect_ratio:"16:9"
Originally created before January 15th 2017 and uploaded (overwritten) between 1 and 4 weeks ago:
created_at<2017-01-15 AND uploaded_at:[1w TO 4w]
Uploaded less than 2 days ago and still pending moderation:
uploaded_at>2d AND moderation_status:pending
PNG images with some transparency:
format:png AND transparent:true
Images with more than 2 faces:
resource_type:image AND face_count>2
Images larger than 10 MB or videos longer than 3 minutes:
(resource_type:image AND bytes>10000000) OR (resource_type:video AND duration>180)
Expression Fields Reference
You can use the following fields to limit your search criteria. The operators that you can use with a field depend on the field's value type. For details, see Field types and supported operators. You can use all fields for all resource types (image, video, raw) unless otherwise specified. Additionally, all string fields support both exact and tokenized search unless otherwise specified.
Field Name | Type | Examples | Details |
---|---|---|---|
Asset Management | |||
access_mode |
String (fixed list) | access_mode:authenticated | The authentication level currently set for the resource. Possible values: public , authenticated Case-sensitive |
context |
String | context.productType:shoe context.productType=shoe context."key with spaces":myValue context:keyname //check for key existence |
You can search for a specific key-value pair, or for all resources with a particular key regardless of the value, or with a particular value regardless of the key. To search for the value of a key, specify the key value of the context using the dot (.) notation, and the value using a colon (:). To check for the existence of a key name, specify the keyname you are searching for after an equal sign (=). Key names are exact match only and are case-sensitive. Values can be tokenized or exact match. Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive. |
created_at |
Date | created_at:[YYYY-MM-DDT12:00:00Z TO 1w] created_at:[1w TO 4w] created_at>10d created_at<1w created_at<=2016-01-01 created_at<1486910712 |
|
folder |
String | folder=test/sample // exact folder, no subfolders folder:sample // any path that contains sample folder:sample/* // prefix, all contents of 'sample' under root |
You can search for an exact or tokenized folder path, or you can search for a folder prefix, which returns all contents of the specified folder and all its subfolders. Case-sensitive. |
moderation_status |
String | moderation_status=approved | The current moderation status. Possible values: pending , approved , rejected Case-sensitive. |
public_id |
String | public_id=test/sample/dog public_id:test/sample/dog public_id:test/sample/dog* |
The full public ID, including folder names when relevant. You can search for an exact or tokenized filename, or you can search for a filename prefix using the * operator. Case-sensitive |
tags |
String | tags:siamese //tokenized search tags=siamese //exact search tags="siamese cats" -tags=siamese |
Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive. |
type |
String (fixed list) | type:private | The asset type. Possible values: upload , private , authenticated , fetch , facebook , twitter , etc.Exact match only. Case-sensitive. |
uploaded_at |
Date | uploaded_at<1d // uploaded date is smaller than the date one day ago = longer than 1 day ago. | |
Media Properties | |||
aspect_ratio |
Number or String | aspect_ratio="16:9" aspect_ratio<=1 |
You can specify the aspect ratio as a decimal number, or a string in the format "Width:Height". Exact match only. Image resources only. Case-sensitive. |
duration |
Number | duration>5 | The duration of the video in seconds. Video resources only. |
filename |
String | filename=”hound-dog” filename:(dog cat) filename:hound* |
Refers to the last element of the public ID without a format extension. You can search for an exact or tokenized filename, or you can search for a filename prefix using the * operator. Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive. |
format |
String | format=(jpg OR mp4) | Exact match only. Case-insensitive. |
height |
Number | height<=100 | Not relevant for raw files. |
pixels |
Number | pixels>400000 | Number of total pixels (width x height). Not relevant for raw files. |
resource_type |
String (fixed list) | resource_type:image resource_type:video |
Possible values: image , video , raw Exact match only. Case-sensitive. |
bytes |
Number | bytes:[1000 TO 5000000] bytes>100000 |
The file size, in bytes by default. |
width |
Number | width>100 width=1028 |
Not relevant for raw files. |
System | |||
backup_bytes |
Number | backup_bytes>0 // all resources that are backed up. | If the resource is backed up, indicates the space taken in the backup system by all backed up versions. |
status |
String (fixed list) | status=deleted status=deleted OR active |
Possible values: active , deleted Notes: - Resource data is stored in the database with status deleted only if the resource has a backup. - By default, when you conduct a search, the response includes only resources with active status. If you want the response to include resources with a deleted status, you must use this field to specify it. Exact match only. Case-sensitive. |
Asset analysis and metadata (Tier 2) | |||
colors |
String | Colors:blue //images that contain blue colors.blue>=2 //images that are at least 2% blue |
To search for images that contain a specified color (as one of the detected predominant colors), use the colon notation. Supported colors: red, orange, yellow, green, teal, blue, purple, pink, white, gray, black. To search for images that have a specified % of the specified color, the dot (.) notation. Image resources only. |
etag |
String | etag=d8ee49a7e9fb633c91cd4d4b2b | Exact match only. Case-sensitive. |
face_count |
Number | num_faces>=1 | Image resources only. |
grayscale |
Boolean | grayscale:true | Image resources only. |
illustration_score |
Number | illustration_score>0.5 | The likelihood that the image is an illustration (as opposed to a photo). Values between 0 (photo) and -1 (illustration). Image resources only. |
transparent |
Boolean | transparent:true | Contains one or more colors with an alpha channel. Image resources only. |
metadata |
String | metadata.license=a1s3d5f7a9s2d4f | Accesses the asset's metadata, such as Exif data or XMP. Specify any metadata element using the dot (.) notation. Metadata element values are case-sensitive. Specify their names exactly as stored in actual image metadata. Image resources only. |
Field types and supported operators
Field type | Supported operators | Notes |
---|---|---|
Boolean | = |
Possible values: true , false |
Date | = > >= < <= [ ] { } |
The date can be given as: - Unix time - ISO8601 syntax: yyyy-mm-dd[Thh:mm:ss] - Relative time: a relative amount of time ago from today, such as an hour, day, week, month ago: 1h, 1d, 1w, 1m. Notes: - When specifying ranges, it is possible to specify each element of the range in a different date format. For example, a range from January 15 2016 until 1 week ago: created_at:[2016-01-15T12:00:00Z TO 1w] - When using operators such as greater than or less than with relative times, the comparison is in unix time. For example, 'greater than' indicates a unix time that is larger than the specified relative time. Therefore >3d indicates a date within the last 3 days. |
Number | = > >= < <= [ ] { } |
|
String | : = [ ] { } |
Some string fields support both tokenized searches using the colon (:) operator, and exact searches using the equal sign (=) operator. Other fields support only exact searches. In these cases, regardless of whether you use a colon or equal sign operator, an exact search is performed. You can use the [ ] or { } range operators to search for strings falling into an alphabetical range. Note: The following string fields are not included in global searches. To search in these fields, you must explicitly specify the field in the search criteria: type , status , resource_type |