Cacheable search URLs

You can generate a search URL that can then be used to return the results of a specified search. This URL can be given a specific time to live, and then the results of the search are cached on the CDNs for that amount of time before the search results are regenerated. Since this feature generates a URL, the search results can also be available for access in client-side code via this URL.

Search URL syntax

The syntax for creating the search URL is similar to the syntax for performing a regular search, except that instead of calling the execute method at the end to return the search results themselves, you call the to_url method to build the search URL that will return the search results.

The to_url function accepts the following optional parameters:

• ttl - The time to live in seconds of the search results, calculated from the time the URL is first requested, which is when the results are actually generated. This is in effect the amount of time the results of the search are cached before they need to be regenerated. Default: 300
• next_cursor - When a 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.

Search URL examples

1. Return the URL for a search that will find assets containing 'shirt' in any field (attribute), include only the tags field in the details of each resource and cache the results for 300 seconds by default:

2. Return the URL for the next page (next_cursor = "db27cfb02b3") of a search that finds assets containing 'hat' in any field but not 'black' 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. Cache the search results for 1000 seconds:

Search URL return value

The return value is a string with the search URL, for example:

Search URL structure

If you need to manually generate a search URL instead of using a Cloudinary SDK, you will also need to authenticate the request with a signature based on the parameters you use in the request. The signature is a hexadecimal message digest (hash value) created with the SHA-256 (Secure Hash Algorithm) cryptographic function. This signature should be generated on your backend, as you should never expose your api_secret in client-side code.

The search URL takes the following form:

The URL includes the following parameters:

• cloud_name - The name of your Cloudinary product environment.
• ttl - The time to live in seconds of the search results, calculated from the time the URL is first requested, which is when the results are actually generated. This is in effect the amount of time the results of the search are cached before they need to be regenerated.
  

• search_parameters - The URL-safe base 64 encoding of a JSON struct of all the search parameters. For example, the following search parameters as a JSON struct:

  ...in URL-safe base 64 encoding would become:

• signature - A signature generated on your backend, (never expose your api_secret in client-side code). The signature is the hexadecimal message digest (hash value) of a string using an SHA256 cryptographic function. In this case the string is made up of the following parameters:ttl + base64_encoded_search_parameters + api_secret. Note that next_cursor is not part of the signature to allow for client side pagination. For example, if you have the following parameters:

  • ttl: 1000
  • base64_encoded_search_parameters: eyJhZ2dyZWdhdGUiOlsiZm9ybWF0Il0sImV4cHJlc3Npb24iOiJkb2cgQU5EIC10YWdzOnB1cHB5IiwibWF4X3Jlc3VsdHMiOjEwLCJzb3J0X2J5IjpbeyJwdWJsaWNfaWQiOiJkZXNjIn1dfQ==
  • api_secret: abcd

  Then the signature would be the result of running the SHA256 function on the string:

  The SHA256 result:

• next_cursor - (Optional) - When a 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.

Putting all the example parameters used above in a single URL: