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

CoreMedia Adds Cloudinary to its CoreMedia Studio Platform

Today we’re pleased to announce a new technology partnership with CoreMedia, a leading Content Experience Platform provider. CoreMedia users can now leverage Cloudinary’s web-based digital asset management (DAM) solution to organize, search, manage and optimize their media assets, including images and videos, and to orchestrate, preview and deliver digital experiences consistently and optimized across all channels and browsers. The official press release is available here.

Read more
Facial-Surveillance System for Restricted Zones

In Africa, where Internet access and bandwidth are limited, it’s not cost-effective or feasible to establish and maintain a connectivity for security and surveillance applications. That challenge makes it almost impossible to build a service that detects, with facial-recognition technology, if someone entering a building is authorized to do so. To meet the final-year research requirement for my undergraduate studies, I developed a facial-surveillance system. Armed with a background in computer vision, I decided to push the limits and see if I could build a surveillance system that does not require recording long video footage.

Read more
Complex Networks Case Study

Complex Networks has been using Cloudinary since 2014 to manage and optimize images across seven websites and two mobile apps, making editorial workflow more efficient, improving page performance and load time, and increasing user engagement. Cloudinary was instrumental in enabling Complex Networks to redesign its web properties. Without the flexibility that Cloudinary offers to both creative and development teams, it would not have been possible for Complex Networks to achieve such a fast time to market.

Read more
Automate Placeholder Generation and Accelerate Page Loads

If you run a Google search on LQIP you’ll see very few relevant articles, very little guidance, and definitely no Wikipedia articles. In this post, we’ll discuss some of the feedback on LQIP we have gathered from the community and suggest and open for conversation a few approaches based on the built-in capabilities of the Cloudinary service. Specifically, we’ll explain what LQIP are, where they are best used, and how you can leverage them to accelerate page loads and optimize user experience.

Read more
Best Practices for Optimizing Web Page Speed

If you're like most consumers today, you engage more with pictures or videos on a website than text. The stats don't lie - four times as many visitors would rather watch a video about a product than read about it, and sites with compelling images average twice as many views as text-heavy ones.

Read more
A day of fun with Girls Who Code and Cloudinary

During both my computer science studies and work in the tech field, there have not been a lot of women present. While our ranks have grown, women still make up only a small percentage. In many ways, I think the traditionally male-dominated world can be intimidating to women and girls who may be interested in pursuing these types of tech careers.

Read more