Cloudinary Blog

Finding the right media assets with a powerful new search API

Finding the Right Media Assets with a Robust Search API

Great content is hard to come by. You can invest a lot of time and effort in building a great media library, but if content managers and editors can't quickly find what they need at the right time, it's almost useless (and frustrating). Good search capabilities allow you to provide them with a better experience: present relevant content or a well-organized catalog by a variety of criteria such as tags, folders, size, resolution, aspect ratio, faces, colors and many more.

Introducing image & video advanced search API

Cloudinary is an end-to-end image and video management solution. Our new search API allows you to incorporate advanced search capabilities into your media management workflow, letting your content managers easily find assets uploaded to Cloudinary by almost any criteria. You can use the data in the search response to display an organized view of your catalog, display relevant content, or even expose dynamic search options directly.

Webinar
Marketing Without Barriers Through Dynamic Asset Management

For example, let's say John is an editor who is writing an article that needs an image. The website design requires a landscape image with good quality. John also remembers that the company purchased some images earlier this month and there was one with a dog that could be just right, that may have been tagged. Well, if the company's images are stored in a Cloudinary account, then finding that perfect image is easy with the Search API.

Here's a quick Ruby example:

Copy to clipboard
Cloudinary::Search.expression('tag:dog uploaded_at>1m aspect_ratio>="4:3" width>2048').execute

This query returns a JSON response that provides a summary of the search results and lists all matching images. In this example, the response includes all images tagged with 'dog', with an aspect ratio of 4:3, wider than 2048px, and that were uploaded within the past month. Results are sorted by relevance.

Search API - sample result returned 1

Search API - sample result returned 2

Search API - sample result returned 3

Search API - sample result returned 4

The search API is based on a robust new asset search engine, so that even if you have millions of assets, results are returned immediately. You can truly focus on your core product and let us do the searching for you.

Search for any combination of criteria

The search expression syntax is Lucene-based, and supports any combination of attributes:

  • Asset attributes such as file size, aspect ratio, resolution, video duration
  • Categorization attributes such as tags, context, folders
  • Dates such as when the resource was uploaded or created
  • Advanced options such as embedded image metadata (Exif) and image analysis (colors, faces, transparency, and more).

Using flexible query expressions, you can tailor your search to match the way your content managers and editors like to search for content.

Faceted search

Faceted search is a great way to provide themed navigation and exploration by predefined categories, usually more suitable for the less tech-savvy users within your organization. Rather than expecting users to search by different criteria, you can use the API's aggregation options to proactively display different category values, and how many assets match that category.

Here's an example of aggregating assets by format:

Copy to clipboard
Cloudinary::Search.('flower').aggregate('format').execute

The response returns all assets that contain the search term 'flower', listing the number of assets for each of these formats:

Copy to clipboard
{
  
  "aggregations": {
    "format": {
      "png": 484,
      "jpg": 121,
      "gif": 3,
      "pdf": 2
    }
  },
  
}

More examples

1. Dynamic image search in an eCommerce catalog

Say you have an eCommerce catalog, with millions of product images, and multiple photographers who upload them from a variety of sources. Images are usually uploaded to a specific folder (e.g., 'products/photos/'), and you carefully manage metadata for product types, but for a specific campaign you want to be able to find all blue shirts, with high quality (above 5 MP), that were taken within the last week. Just one simple query and here they are:

Copy to clipboard
Cloudinary::Search.expression(
'resource_type:image AND folder:products/photos/* AND
 context.productType:shirt AND 
(colors.blue>10 pixels>5mp taken_at>1w)').execute

Now it's easy to download them, tag them, or publish them on your website.

2. Housekeeping and cleanup

You can also use the search API for cleaning up a cluttered media library. Let's say you want to get rid of meaningless large videos to save some space. Just search for all mp4 videos that are shorter than 1 minute and weigh over 10 MB, and request them in descending order of size. Housekeeping has never been easier.

Copy to clipboard
Cloudinary::Search.expression(
'format:mp4 AND duration<30s AND size>10mb').sort_by('size','desc').execute

3. Taking advantage of auto-tagging

Tagging every image in your media library is valuable in many ways and improves the searchability of your media assets, but manual tagging according to image content is a very time-consuming task. And if you have a lot of user-generated content, you simply cannot manually handle it all.

Cloudinary offers fully integrated add-ons for automatic image tagging using AWS Rekognition & Imagga. Using one of these, you can ensure that all your images are automatically tagged with relevant terms based on content. You can then easily search for specific content or for inspiration, without relying on manual categorization and taxonomy. And if your search turns out to be too broad, it's easy to refine it to quickly find what you're looking for without the tedious manual efforts.

Here is an example of searching for an image of a bike. Note that when no fields are specified in the search expression, we search for the term in all string fields, including tags.

Copy to clipboard
Cloudinary::Search.expression('bike').execute

Examples of results appear below, along with the automatic tags that were identified.

Search API - auto tagging 1

Search API - auto tagging 2

Still haven't found what you're looking for?

There are many more examples of what you can accomplish with the advanced search API. Search for transparent logos, photos with a certain number of people in them, media assets that are protected with copyright or taken with a specific camera model in a specific location, and more.

Check out our Search API documentation for a full list of search options.

Give it a try

The asset search API is part of our Admin API and is available in the following SDKs: Ruby, Node, Java, PHP, Python and Scala.

It is included for our Advanced Extra plans and higher and requires a small setup on our side. An additional search tier is available which allows more advanced functionality, such as embedded image metadata, image analysis and aggregations.

Our beta customers have been trying it out for a while now, and so far we've been hearing great feedback. Want to try it out? Contact us and we'll set it up for you. Looking forward to hearing what you think!

Further Reading on Digital Asset Management

Recent Blog Posts

Creating an API With Python Flask to Upload Files to Cloudinary

Code

Cloudinary offers SDKs for many programming languages and frameworks. Even though it also offers an Upload API endpoint for both back-end and front-end code, most developers find the SDKs very helpful. If you're working with a powerful back-end framework like Python Flask, you'll be happy to hear that a Python SDK is now available.
This tutorial walks you through the process of building an API to upload images to Cloudinary. You can also upload other file types, including video and even nonmedia files, with the API.

Read more
How to Use the Cloudinary Media Editor Widget

At Cloudinary, we manage the entire pipeline of media assets for thousands of customers of varying sizes from numerous verticals.

As part of our commitment to support the entire flow of media assets, we are now introducing an intuitive media editing widget: an out­-of­-the-­box, interactive UI providing your users with a set of common image editing actions for immediate use on your website or web app. The widget is interactive and simple, built on Cloudinary's transformation capabilities, and requiring only a few lines of code to integrate. Afterwards, you can seamlessly and effortlessly add content to your site or app with no need for in-house image editing capabilities.

Read more
Shoppable Video Is Becoming Popular in E-Commerce

As pandemic restrictions necessitated, many shopping trips in 2020 took place outside the traditional brick-and-mortar store, or at least void of the physical aisle-browsing experience. Same-day curbside pickup became a safe and convenient alternative, and e-commerce transactions skyrocketed as consumers shopped online. In fact, Digital Commerce 360 estimates that, compared to 2019, e-commerce transactions grew by more than 40% last year.

Read more
Enhance Your Travel Site With Cloudinary in Anticipation of a Return to New Normal

Read more
The Benefits of Headless DAMs

Headless is not a buzzword anymore. In fact, the concept of headless architecture is gaining momentum due to the flexibility it offers for composing new experiences and for tackling the undue complexity of an ever-evolving technology stack. That’s because while the evolution of the martech landscape has enabled disruptive, digital innovations, the approach of buying point solutions for solving specific challenges can expose companies to the complicated nature of new technologies, systems, and platforms.

Read more