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.

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:

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:

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:

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

More examples

1. Dynamic image search in an e-commerce catalog

Say you have an e-commerce 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:

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.

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.

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!

Recent Blog Posts

A Guide to Website Image Optimization and Performance

Part 1 of this series delves into the background for this guide. Here in part 2 are the ins and outs.

Wait, hear me out. I know, we just talked about this: Nobody is sheepishly pleading you, “Please, might we have just one more image on the page?” No, I’m not telling you to pick that particular fight. Instead, use a little smoke and mirrors to avoid requests for images that your audience needn’t render right away and might never need at all while loading them asynchronously—only as needed.

Read more
A Guide to Image Optimization for Website Performance

I’ve spent a lot of time thinking about the rules of putting images on the web.

For such a flexible medium as the web, software development can feel like a painstaking, rules-oriented game—an errant comma might break a build, a missing semicolon might wipe out an entire page. For a long time, the laws of image rendering seemed similarly cut-and-dry: For example, if your markups contained an img element , the singular content of its src attribute would be foisted on the audience regardless of their browsing context, period.

Read more
Digital Asset Management Platform: Meeting Customer Expectations

Consumers today expect media-rich experiences. No longer a novelty, it’s second nature to swipe through multiple photos on mobile apps, zoom in on product images for a closer look, visualize online travel reviews, socialize cool video clips while browsing, and encounter brand messages when walking into brick-and-mortar stores. These experiences weave together visual cues and clues with relevant content to create meaning and more authentic connections for customers.

Read more
How to Customize Cloudinary's eCommerce Android App

Recently we added the Cloudinary Demo - eCommerce App to the Google Play Store. This app demonstrates the best practices for optimal delivery of images on a storefront, including category pages, product pages, and a shopping cart. At the time, we published Introducing the Cloudinary Demo Android App, Part 1, which provided an under-the-hood tour of how the eCommerce Android App was designed and how Cloudinary was integrated throughout.

Read more