Search API reference

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.

Quick example

Find images tagged with 'kitten', that have been uploaded within the last day, and are larger than 1 MB in size. In the response, sort the results by public_id in descending order, and limit the returned results to 30 resources:

result = 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

$result = $cloudinary->searchApi()
  ->expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')
  ->sortBy('public_id','desc')
  ->maxResults(30)
  ->execute();

$search = new \Cloudinary\Search();
$search->expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m');
$search->sort_by('public_id','desc');
$search->max_results(500);
$result = $search->execute();

result = 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()

cloudinary.v2.search
  .expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')
  .sort_by('public_id','desc')
  .max_results(30)
  .execute()
  .then(result=>console.log(result));

result = cloudinary.search()
  .expression("resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m")
  .sortBy("public_id","desc")
  .maxResults(30)
  .execute();

SearchResult result = cloudinary.Search()
  .Expression("resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m")
  .SortBy("public_id","desc")
  .MaxResults(30)
  .Execute();

resp, err := cld.Admin.Search(ctx, search.Query{
    Expression: "resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m",
    SortBy:     []search.SortByField{{"public_id": "desc"}},
    MaxResults: 30})

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m",
        "sort_by": [{"public_id": "desc"}],
        "max_results":30
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cld search "resource_type=image AND tags=kitten AND uploaded_at>1d AND bytes>1m" -s public_id desc -n 30

Tiers

The Search API capabilities are 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 (Premium): Includes extra search functionality including support for search expressions based on image analysis and embedded metadata fields as well as support for aggregated counting information in the response. Functionality that is limited to Tier 2 is noted as such.
  

Tier activation and pricing

• Tier 1 Search API functionality is automatically enabled for all accounts with up to 10 million assets. If your account already has, or is approaching 10 million assets, contact support.

• Tier 2 is available upon request for Advanced plans and higher. Tier 2 is provided at an extra cost for Advanced plans. For Enterprise plans, Tier 2 functionality is included in the price of your package for up to 10 million assets (and available at an additional cost for more than 10M assets). Regardless of your account plan, you must contact support to request the Tier 2 option.

Search method

The Search method enables you to find the specific assets in your account that meet your given criteria.

Syntax

GET /resources/search

result = Cloudinary::Search.execute

$result = $cloudinary->searchApi()->execute();

$result = \Cloudinary\search->execute();

result = cloudinary.Search().expression().execute()

cloudinary.v2.search.execute().then(callback);

result = cloudinary.search().execute();

SearchResult result = cloudinary.Search().Execute();

resp, err := cld.Admin.Search(ctx, search.Query{})

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

Examples

1. 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:

   RubyPHPPythonNode.jsJava.NETGoEndpointAll

   Ruby (cloudinary 1.x):

   Copy to clipboard

   result = Cloudinary::Search
     .expression('cat')
     .with_field('context')
     .with_field('tags')
     .max_results(10)
     .execute

   PHP (cloudinary_php 2.x):

   Copy to clipboard

   $result = $cloudinary->searchApi()
     ->expression('cat')
     ->withField('context')
     ->withField('tags')
     ->maxResults(10)
     ->execute();

   cloudinary_php 2.x cloudinary_php 1.x (legacy)

   PHP (cloudinary_php 1.x (legacy)):

   Copy to clipboard

   $result = \Cloudinary\search
     ->expression('cat')
     ->with_field('context')
     ->with_field('tags')
     ->max_results(10)
     ->execute();

   cloudinary_php 2.x cloudinary_php 1.x (legacy)

   Python (cloudinary 1.x):

   Copy to clipboard

   result = cloudinary.Search()\
     .expression('cat')\
     .with_field('context')\
     .with_field('tags')\
     .max_results('10')\
     .execute()

   Node.js (cloudinary 1.x):

   Copy to clipboard

   cloudinary.v2.search
     .expression('cat')
     .with_field('context')
     .with_field('tags')
     .max_results(10)
     .execute()
     .then(result=>console.log(result));

   Java (cloudinary 1.x):

   Copy to clipboard

   result = cloudinary.search()
     .expression("cat")
     .withField("context")
     .withField("tags")
     .maxResults(10)
     .execute();

   .NET (CloudinaryDotNet 1.x):

   Copy to clipboard

   SearchResult result = cloudinary.Search()
     .Expression("cat")
     .WithField("context")
     .WithField("tags")
     .MaxResults(10)
     .Execute();

   Go (cloudinary-go 1.x):

   Copy to clipboard

   resp, err := cld.Admin.Search(ctx, search.Query{
             Expression: "cat",
             WithField:  []string{"tags", "context"},
             MaxResults: 10})

   endpoint:

   Copy to clipboard

   curl \
     -H "Content-Type: application/json" \
     -d '{
           "expression": "cat",
           "with_field": ["context", "tags"],
           "max_results": 10
         }' \
     https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

   cli:

   Copy to clipboard

   cld search "cat" -f context -f tags -n 10

2. 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:

   RubyPHPPythonNode.jsJava.NETGoEndpointAll

   Ruby (cloudinary 1.x):

   Copy to clipboard

   result = Cloudinary::Search
     .expression('cat AND -tags:kitten')
     .sort_by('public_id','desc')
     .aggregate('format')
     .execute

   PHP (cloudinary_php 2.x):

   Copy to clipboard

   $result = $cloudinary->searchApi()
     ->expression('cat AND -tags:kitten')
     ->sortBy('public_id','desc')
     ->aggregate('format')
     ->execute();

   cloudinary_php 2.x cloudinary_php 1.x (legacy)

   PHP (cloudinary_php 1.x (legacy)):

   Copy to clipboard

   $result = \Cloudinary\search()
     ->expression('cat AND -tags:kitten')
     ->sort_by('public_id','desc')
     ->aggregate('format')
     ->execute();

   cloudinary_php 2.x cloudinary_php 1.x (legacy)

   Python (cloudinary 1.x):

   Copy to clipboard

   result = cloudinary.Search()\
     .expression('cat AND -tags:kitten')\
     .sort_by('public_id','desc')\
     .aggregate('format')\
     .execute()

   Node.js (cloudinary 1.x):

   Copy to clipboard

   cloudinary.v2.search
     .expression('cat AND -tags:kitten')
     .sort_by('public_id','desc')
     .aggregate('format')
     .execute()
     .then(result=>console.log(result));

   Java (cloudinary 1.x):

   Copy to clipboard

   result = cloudinary.search()
     .expression("cat AND -tags:kitten")
     .sortBy("public_id","desc")
     .aggregate("format")
     .execute();

   .NET (CloudinaryDotNet 1.x):

   Copy to clipboard

   SearchResult result = cloudinary.Search()
     .Expression("cat AND -tags:kitten")
     .SortBy("public_id","desc")
     .Aggregate("format")
     .Execute();

   Go (cloudinary-go 1.x):

   Copy to clipboard

   resp, err := cld.Admin.Search(ctx, search.Query{
         Expression: "cat AND -tags:kitten",
         SortBy:     []search.SortByField{{"public_id": "desc"}},
         Aggregate:  []string{"format"},
         MaxResults: 2})

   endpoint:

   Copy to clipboard

   curl \
     -H "Content-Type: application/json" \
     -d '{
           "expression": "cat AND -tags:kitten",
           "sort_by": [{"public_id": "desc"}],
           "aggregate": ["format"]
         }' \
     https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

   cli:

   Copy to clipboard

   cld search "cat AND -tags:kitten" -s public_id desc -a format

   Tip

   For more examples, see the expression examples documentation.

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": [
  {
    "asset_id": "5f9d30acd36ac3c4f48a82241a37a299",
    "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,
    "access_control": [       
     { access_type: "token" },
     { access_type: "anonymous", start: "2017-12-15T12:00Z", end: "2018-01-20T12:00Z" }],
    "context": {},
    "image_analysis": { 
      "face_count": 0,
      "faces": [],
      "grayscale": true,
      "illustration_score": 1,
      "transparent": false,
      "colors": {
        "gray": 96.7
      }
    },
    "url": "http://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"

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 Expression fields.

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 matches where the value is an exact match.
• Using the : operator finds matches where the value matches any complete token within the string value.

A token is a part of a search string that is separated by a separator character. Spaces, hyphens, and underscores are the most common characters that separate tokens within a search string. For example:

tags=cat

Finds a match only when the tag equals cat

tags:cat

Finds a match as long as any of the tokens in a tag entry includes cat, for example, tag values of cat and dog or dog-cat return as matches but catfish doesn't.

You can also append an asterisk (*) to the end of a search term in order to look for your search term as a prefix. For example, to search for "cat", "cats" or "catfish", you can use the search term:

cat*

You can also combine the use of asterisks with exact (=) or tokenized (:) searches to further fine-tune your result:

• If you only want to return results where the entire value starts with cat*, use an exact (=) search. For example, tag=cat*
• If you want to return all results where any token in the value starts with cat*, use a tokenized (:) search. For example, tag:cat*

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

Expression examples

1. Assets containing "shirt" and with a tag that exactly matches "cotton":

   Copy to clipboard

   shirt AND tags=cotton

2. Images with a width between 200 and 1028, and an aspect_ratio of 16:9:

   Copy to clipboard

   resource_type:image AND width:{200 TO 1028} AND aspect_ratio:"16:9"

3. Originally created before January 15th 2017 and uploaded (overwritten) between 1 and 4 weeks ago:

   Copy to clipboard

   created_at<2017-01-15 AND uploaded_at:[1w TO 4w]

4. Uploaded less than 2 days ago and still pending moderation:

   Copy to clipboard

   uploaded_at>2d AND moderation_status:pending

5. PNG images with some transparency:

   Copy to clipboard

   format:png AND transparent:true

6. Images with more than 2 faces:

   Copy to clipboard

   resource_type:image AND face_count>2

7. Images larger than 10 MB or videos longer than 3 minutes:

   Copy to clipboard

   (resource_type:image AND bytes>10000000) OR (resource_type:video AND duration>180)

Expression Fields

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 types and supported operators