Cacheable search URLs
Last updated: Sep-02-2024
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 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.
Search URL examples
-
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:
-
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 yourapi_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 thatnext_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:
- ttl:
next_cursor
- (Optional) - When a 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.
Putting all the example parameters used above in a single URL: