{"id":21166,"date":"2012-11-21T10:14:19","date_gmt":"2012-11-21T10:14:19","guid":{"rendered":"http:\/\/api_for_extracting_semantic_image_data_colors_faces_exif_data_and_more"},"modified":"2025-08-03T14:16:57","modified_gmt":"2025-08-03T21:16:57","slug":"api_for_extracting_semantic_image_data_colors_faces_exif_data_and_more","status":"publish","type":"post","link":"https:\/\/cloudinary.com\/blog\/api_for_extracting_semantic_image_data_colors_faces_exif_data_and_more","title":{"rendered":"API for Extracting Semantic Image Data – Colors, Faces, Exif Data, and More"},"content":{"rendered":"
<\/div>\n
When images are involved, web developers have a large set of relevant tools at their disposal. You can display images in your web sites and mobile applications. You can transform and transform such images using image editing and transformation software or cloud-based solutions like Cloudinary<\/a>. But there are other types of data embedded in image files that can add unique semantic information to the images and are hardly ever used.<\/div>\n
<\/div>\n
Consider what new designs can appear if your graphics designer could assume that only blue themed user uploaded photos will be featured on your homepage. What about featuring only photos that show your users’ faces? How about photos taken with new DSLR model cameras rather than older pocket ones? Only photos taken in the GPS vicinity of your website visitor? We believe that such capabilities can offer a new, important tool for web design and development.<\/div>\n
<\/div>\n
Unfortunately, such semantic data is usually locked safely within the images and rarely utilized by developers and designers. We hope that we can change that by introducing a new Cloudinary API<\/a> that allows you to easily extract rich information<\/a> regarding your website and mobile application’s photos. Using this information you can search, sort and classify your images in amazing new ways.<\/div>\n
<\/div>\n

Predominant Colors & Color Histogram<\/h3>\n
\"\"<\/a>Image search services such as Google Image Search allow you to filter your image search to show only images of a certain color. How is it done? Each image is analyzed and the colors of the images are mapped to one or more leading colors.<\/div>\n
<\/div>\n
Cloudinary now supports finding the leading colors of a given image using a standard palette of 12 main colors. Since Cloudinary is a cloud-based service, all image processing is done online and no software installation is required on your side.<\/div>\n
<\/div>\n
Finding the predominant colors<\/strong> in an image is also useful for stock-photo sites that wants to allow you to narrow photo searching by colors (see our previous post<\/a> of how-to quickly build a stock-photo site with Cloudinary) and for eCommerce sites. For example: if you have a fashion site, and you want your users to browse only blue or red shirts.<\/div>\n
<\/div>\n
For example, the following image with the public ID ‘fashion1’ was uploaded to Cloudinary:<\/div>\n
<\/div>\n
\"\"<\/a><\/div>\n
<\/div>\n
<\/div>\n
Using Cloudinary’s Admin API<\/a>, you can extract the photo’s main colors by setting the ‘colors<\/strong><\/span>‘ parameter to true<\/strong> (see reference documentation<\/a>). Here are examples for Ruby<\/strong>, PHP<\/strong>, Node.js<\/strong> and Python<\/strong>:<\/div>\n
Cloudinary::Api.resource('fashion1', :colors => true)\n<\/pre>\n
$api->resource(\"fashion1\", array(\"colors\" => TRUE));\n<\/pre>\n
cloudinary.api.resource('fashion1', \u00a0\n                        function(result) \u00a0{ console.log(result) }, { colors: true });\n<\/pre>\n
cloudinary.api.resource(\"fashion1\", colors = True)\n<\/pre>\n
<\/div>\n
Below is the JSON result of this API call. It seems that the main colors of this image are white (50.7%) and blue (27.8%), with touches of gray and brown. Cool.<\/div>\n
{\n  \"public_id\": \"fashion1\",\n  \"width\": 225,\n  \"height\": 380,\n  ...\n  \"predominant\": {\n    \"google\": [\n      [ \"white\", 50.7 ],\n      [ \"blue\",  27.8 ],\n      [ \"gray\", 11.2 ],\n      [ \"brown\", 5.1]\n    ]\n  }\n}\n<\/pre>\n
Using this info, you can keep the color mapping in your model and allow clothes to be searched based on colors. Searching for blue clothes should return this product.<\/div>\n
<\/div>\n
Another result you get as part of the color information API is a histogram of 32 RGB colors<\/strong> that best represent the image. The following JSON snippet was also included in the result of the API call.<\/div>\n
{\n  \"public_id\": \"fashion1\",\n  ...\n  \"colors\": [[\"#FFFFFF\", 50.7], [\"#011B43\", 5.8], [\"#5077A7\", 4.9], [\"#031235\", 4.3], [\"#F4CBB4\", 3.3], [\"#3A6498\", 1.9], [\"#6284AF\", 1.9], [\"#2D5E95\", 1.9], [\"#30578B\", 1.8], [\"#080918\", 1.8], [\"#E5B09D\", 1.8], [\"#36262F\", 1.7], [\"#264876\", 1.6], [\"#281A25\", 1.5], [\"#486A99\", 1.4], [\"#E3D6CF\", 1.4], [\"#4D3135\", 1.4], [\"#07264F\", 1.2], [\"#664E55\", 1.1], [\"#6E443C\", 1.0]]\n}\n<\/pre>\n
As you can see, you get RGB format and percentage breakdown of the 32 colors that best represent the image. ‘#FFFFFF’ is white, representing around half of the image, followed by multiple blue shades (e.g., ‘#011B43’ is 5.8%).<\/div>\n
<\/div>\n
Face detection info<\/h3>\n
Cloudinary supports face detection based cropping<\/a>\u00a0and pixelation<\/a>. Either a single face or multiple faces can be automatically detected. Our API now supports returning additional information regarding the detected faces in an uploaded photo.<\/div>\n
<\/div>\n
Simply set the ‘faces<\/strong><\/span>‘ parameter to true<\/strong> in the same method we showed above for ‘colors<\/strong>‘. Note that you can enable multiple flags in a single call for fetching all information at once. The result includes the exact coordinates of all detected faces, allowing you to easily find out how many faces are available in the photo and their exact positions.<\/div>\n
<\/div>\n
The following Ruby command asks for the faces information of the ‘fashion1’ image:<\/div>\n
Cloudinary::Api.resource('fashion1', :faces => true)\n<\/pre>\n
Here is the JSON result:<\/div>\n
{\n  \"public_id\": \"fashion1\",\n  ...\n  \"faces\": [[99, 21, 64, 87]]\n}\n<\/pre>\n
<\/div>\n
As you can see, a single face was correctly detected. It is positioned in the 99,21 – 64,87 rectangle of the original image.<\/div>\n
<\/div>\n
Same works for images with multiple faces:<\/div>\n
<\/div>\n
\"\"<\/a><\/div>\n
{\n  ...\n  \"faces\":  [ [513, 19, 38, 52], [409, 26, 40, 54], [79, 31, 43, 59], [232, 32, 40, 54], [321, 33, 41, 57], [160, 37, 43, 59], [211, 153, 43, 59], [503, 151, 43, 59], [113, 162, 40, 54], [427, 160, 45, 61], [307, 172, 48, 65] ]\n} \n<\/pre>\n
Note that face detection does not achieve 100% accuracy. If you need better accuracy, human moderation is recommended.<\/div>\n
<\/div>\n
Camera information – Exchangeable image file format (Exif)<\/h3>\n
**Update March 2017:<\/strong> The exif parameter has been deprecated. The exif data can now be extracted using the image_metadata parameter.<\/div>\n
<\/div>\n
Modern digital cameras and smartphones store additional metadata as part of the image files you shoot. Such information includes picture orientation, timestamps, camera model information, photo exposure, GPS location and more.<\/div>\n
<\/div>\n
By setting the ‘exif<\/strong><\/span>‘ parameter to true, Cloudinary’s API can extract metadata\u00a0from image’s (see our reference documentation<\/a>). In the sections above we’ve shown how to use the Admin API for fetching information of previously uploaded images. You can also request this information while uploading the photos, so it is returned as part of an upload response.<\/div>\n
<\/div>\n
For example, the following PHP command uploaded to Cloudinary a photo that was taken by an iPhone 4 in a portrait orientation.<\/div>\n
CloudinaryUploader::upload(\"exif_sample.jpeg\", \n   array(\"public_id\" => \"exif_sample\", \"colors\" => TRUE, \"exif\" => TRUE))\n<\/pre>\n
\"\"<\/a><\/div>\n
<\/div>\n
Here is the JSON of the upload response including the requested Exif<\/strong> and Colors<\/strong> information:<\/div>\n
{ \n  \"public_id\": \"exif_sample\",\n  \"width\": 2592,\n  \"height\": 1936,\n  ...\n  \"exif\": {\n    \"ApertureValue\": \"4281\/1441\",\n    \"ColorSpace\": \"1\",\n    \"ComponentsConfiguration\": \"1, 2, 3, 0\",\n    \"Compression\": \"6\",\n    \"DateTime\": \"2010:12:27 11:17:34\",\n    \"DateTimeDigitized\": \"2010:12:27 11:17:34\",\n    \"DateTimeOriginal\": \"2010:12:27 11:17:34\",\n    \"ExifImageLength\": \"1936\",\n    \"ExifImageWidth\": \"2592\",\n    \"ExifOffset\": \"204\",\n    \"ExifVersion\": \"48, 50, 50, 49\",\n    \"ExposureMode\": \"0\",\n    \"ExposureProgram\": \"2\",\n    \"ExposureTime\": \"1\/4309\",\n    \"Flash\": \"24\",\n    \"FlashPixVersion\": \"48, 49, 48, 48\",\n    \"FNumber\": \"14\/5\",\n    \"FocalLength\": \"77\/20\",\n    \"GPSAltitude\": \"20723\/924\",\n    \"GPSAltitudeRef\": \"0\",\n    \"GPSImgDirection\": \"42155\/344\",\n    \"GPSImgDirectionRef\": \"T\",\n    \"GPSInfo\": \"574\",\n    \"GPSLatitude\": \"21\/1, 768\/100, 0\/1\",\n    \"GPSLatitudeRef\": \"N\",\n    \"GPSLongitude\": \"86\/1, 4500\/100, 0\/1\",\n    \"GPSLongitudeRef\": \"W\",\n    \"GPSTimeStamp\": \"17\/1, 17\/1, 3326\/100\",\n    \"ISOSpeedRatings\": \"80\",\n    \"JPEGInterchangeFormat\": \"870\",\n    \"JPEGInterchangeFormatLength\": \"9932\",\n    \"Make\": \"Apple\",\n    \"MeteringMode\": \"1\",\n    \"Model\": \"iPhone 4\",\n    \"Orientation\": \"6\",\n    \"ResolutionUnit\": \"2\",\n    \"SceneCaptureType\": \"0\",\n    \"SensingMethod\": \"2\",\n    \"Sharpness\": \"2\",\n    \"ShutterSpeedValue\": \"4781\/396\",\n    \"Software\": \"4.2.1\",\n    \"SubjectArea\": \"1295, 967, 699, 696\",\n    \"WhiteBalance\": \"0\",\n    \"XResolution\": \"72\/1\",\n    \"YCbCrPositioning\": \"1\",\n    \"YResolution\": \"72\/1\"\n  },\n  \"colors\":[[\"#CBC9C5\",10.2],[\"#C4BCB4\",9.0],[\"#1888AB\",6.0],[\"#202618\",6.0],[\"#226391\",5.4],[\"#223A62\",4.3],[\"#B9B4AD\",3.8],[\"#2F88A1\",3.5],[\"#C9C3BA\",3.4],[\"#7492B2\",3.4],[\"#157193\",3.1],[\"#96ABCC\",2.9],[\"#C8B495\",2.8],[\"#4F97AB\",2.8],[\"#484033\",2.7],[\"#669FAD\",2.5],[\"#A0A29E\",2.4],[\"#38A7C8\",2.3],[\"#57A5B7\",2.3],[\"#2D8FAF\",2.2],[\"#ACCADC\",2.1],[\"#073554\",2.0],[\"#60AFC7\",2.0],[\"#1D4A6F\",2.0],[\"#A39477\",1.9],[\"#D1C4A0\",1.8],[\"#296F96\",1.7],[\"#4F6E91\",1.5],[\"#5F5F57\",1.4],[\"#90AECB\",1.0]],\n  \"predominant\": {\"google\":[[\"teal\",41.7],[\"brown\",35.6],[\"blue\",12.1],[\"green\",8.4]]\n}<\/pre>\n
By the way, you can also use Cloudinary’s Exif-based automatic rotation by setting the ‘angle<\/strong><\/span>‘ parameter (‘a<\/strong><\/span>‘ for URLs) to ‘exif<\/strong><\/span>‘. For example:<\/div>\n
<\/div>\n
https:\/\/res.cloudinary.com\/demo\/image\/upload\/a_exif<\/strong>\/exif_sample.jpg<\/a><\/div>\n
<\/div>\n
\"\"<\/a><\/div>\n
Summary<\/h3>\n
With the additional knowledge of image metadata<\/a> and semantic information, you can enhance your image rich web and mobile applications with little effort, while Cloudinary does all the heavy lifting for you. These additional layers of information adds an important aspect that allows Cloudinary to offer a better than ever cloud-based solution to all your online image management and transformation needs.<\/div>\n
<\/div>\n
All these new features were requested by Cloudinary’s users and we thank all of you for that. We have plenty more ideas for enhancing Cloudinary’s capabilities in this area and would love to hear<\/a> your feedback and suggestions.<\/div>\n
<\/div>\n
The ability to fetch Exif<\/strong>, Faces<\/strong>,\u00a0Predominant colors<\/strong> and Color histogram<\/strong><\/a> is now available to all of Cloudinary’s plans, free and paid. Click here<\/a>\u00a0to setup a free Cloudinary account.<\/div>\n
<\/div>\n
Want to Learn More About Digital Asset Management?<\/h2>\n