class SearchApi implements JsonSerializable

Class SearchApi

The Cloudinary API search method allows you fine control on filtering and retrieving information on all the assets in your cloud 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.

Methods

__construct(mixed $configuration = null)

SearchApi constructor.

expression(mixed $value)

Sets the query string for filtering the assets in your cloud.

maxResults(int $value)

Sets the maximum number of results to return.

nextCursor(string $value)

When a search request has more results to return than max_results, the next_cursor value is returned as part of the response.

sortBy(string $fieldName, string $dir = 'desc')

Sets the sort_by field.

aggregate(string $value)

The name of a field (attribute) for which an aggregation count should be calculated and returned in the response.

withField(string $value)

The name of an additional asset attribute to include for each asset in the response.

executeAsync()

Executes the search API request asynchronously.

execute()

Executes the search API request.

asArray()

Returns the query as an array.

jsonSerialize()

No description

Details

__construct(mixed $configuration = null)

SearchApi constructor.

Parameters

Name Type Description
$configuration mixed

$this expression(mixed $value)

Sets the query string for filtering the assets in your cloud.

If this parameter is not provided then all assets are listed (up to max_results).

Parameters

Name Type Description
$value mixed The (Lucene-like) string expression specifying the search query.

Return Value

$this

$this maxResults(int $value)

Sets the maximum number of results to return.

Parameters

Name Type Description
$value int Default 50. Maximum 500.

Return Value

$this

$this nextCursor(string $value)

When a search request has more results to return than max_results, the next_cursor value is returned as part of the response.

You can then specify this value as the next_cursor parameter of the following request.

Parameters

Name Type Description
$value string The next_cursor.

Return Value

$this

$this sortBy(string $fieldName, string $dir = 'desc')

Sets the sort_by field.

Parameters

Name Type Description
$fieldName string The field to sort by. You can specify more than one sort_by parameter; results will be sorted according to the order of the fields provided.
$dir string Sort direction. Valid sort directions are 'asc' or 'desc'. Default: 'desc'.

Return Value

$this

$this aggregate(string $value)

The name of a field (attribute) for which an aggregation count should be calculated and returned in the response.

(Tier 2 only).

You can specify more than one aggregate parameter.

Parameters

Name Type Description
$value string Supported values: resource_type, type, pixels (only the image assets in the response are aggregated), duration (only the video assets in the response are aggregated), format, and bytes. For aggregation fields without discrete values, the results are divided into categories.

Return Value

$this

$this withField(string $value)

The name of an additional asset attribute to include for each asset in the response.

Parameters

Name Type Description
$value string Possible value: context, tags, and for Tier 2 also image_metadata, and image_analysis.

Return Value

$this

PromiseInterface executeAsync()

Executes the search API request asynchronously.

Return Value

PromiseInterface

ApiResponse execute()

Executes the search API request.

Return Value

ApiResponse

Exceptions

GeneralError

array asArray()

Returns the query as an array.

Return Value

array

jsonSerialize()

Constants

SEARCH_API_ENDPOINT

SORT_BY

AGGREGATE

WITH_FIELD

EXPRESSION

MAX_RESULTS

NEXT_CURSOR

KEYS_WITH_UNIQUE_VALUES