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

10 Website Videos Mistakes and How to Solve Them

It should come as no surprise that video use on the internet is exploding. You can see the dramatic growth of video on the average site in this SpeedCurve blog post.

Average Website Weight over Time

With the growth in video comes greater bandwidth use, which is not only costly for your IT budget, but for your visitors as well. Beyond the expense, there is the user experience to consider. The heavier the page, the longer it will take to load, and the greater likelihood visitors will abandon your site. Page load speed is also an important factor in SEO ranking, so clearly video is something we need to take seriously and get right. Video is challenging, presenting terms still unfamiliar to developers - like codecs, bitrate and adaptive bitrate streaming. As a result, mistakes are being made in video implementation.

Read more
Android Data Saver: Optimizing Mobile Data Usage with Cloudinary

Over the life of a mobile device, the cost of a cellular data plan often exceeds that of the device itself. To optimize data usage and purge useless data on their mobile devices, users can enable Data Saver from Android 7.0 (API level 24). To do so, users toggle Data Saver in quick settings under the Notification shade or under Settings > Data usage. With Data Saver enabled, apps that aren't whitelisted cannot use cellular data in the background. They are also directed to consume less data while active.

Read more
Introducing the Cloudinary Upload Widget v2

At Cloudinary, we manage the entire pipeline of media assets for thousands of customers of varying sizes from numerous verticals. Cloudinary is an end-to-end solution for all your image and video needs, including upload, storage, administration, manipulation, optimization and dynamic delivery.

Read more
Convert an Image to a 3D Canvas With Cloudinary

Note
This post was cowritten with Daniel Mendoza.
Note
This post was cowritten with Daniel Mendoza.
Note

Famed American poet Henry David Thoreau once said, “This world is but a canvas to our imagination.” And, like your imagination, the transformations you can apply to images with Cloudinary are practically endless. You can even render any flat image to appear three-dimensional and framed on a canvas.

Read more
Mobile Optimization: Optimize Your Mobile-Web User Experience

TL;DR

We live in a visual world, often while on the go, and consumers expect media-rich web content. Accordingly, the loading speed of images and videos is a big factor in user experience. To optimize customer satisfaction with your mobile content, you must focus on the quality, format, and size of your digital assets. With Cloudinary, optimization is simple, not only enhancing your mobile web and app performance, but also upping your SEO game and boosting customer experience.

Read more