> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic data extraction


When you upload an asset to Cloudinary, the upload API response includes basic information about the uploaded image such as width, height, number of bytes, format, and more. By default, the following semantic data is automatically included in the upload response as well: ETag, any face or custom coordinates, and the number of pages (or layers) in "paged" files. 

Cloudinary supports extracting additional semantic data from the uploaded image such as: media metadata (including Exif, IPTC, XMP and GPS), color histogram, predominant colors, custom coordinates, pHash image fingerprint, and face and/or text coordinates. You request the inclusion of this additional information in the upload response by including one or more [optional parameters](image_upload_api_reference#upload). 

You can request data extraction while [uploading](image_upload_api_reference#upload) an image, or by using the [explicit](image_upload_api_reference#explicit) method on an already uploaded image.

Clara Denari's Mystery Game: The Sapphire Earring Match

Clara found sapphire earrings in her backyard. Her neighbor, Mrs. Patterson, claims they're hers, a family heirloom, and has an old photo to prove it. Clara restored the blurry photo using Cloudinary's AI. They look pretty similar, but something feels off... Help Clara confirm whether it's an exact match. Extract the earrings from the photo and analyze their exact color to see if Mrs. Patterson's story holds up!

Play the Game

## Data extraction while uploading

The following example uploads an image and requests the pHash value, a color analysis, and the media metadata:

```multi
|ruby  
Cloudinary::Uploader.upload("couple.jpg",  
  colors: true,  
  phash: true,  
  media_metadata: true)
 
|php_2
$cloudinary->uploadApi()->upload("couple.jpg", [ 
    "colors" => true,
    "phash" => true,
    "media_metadata" => true]);

|python
cloudinary.uploader.upload("couple.jpg", 
  colors = True,
  phash = True,
  media_metadata = True)


|nodejs
cloudinary.v2.uploader
.upload("couple.jpg", 
  { colors: true,
    phash: true,
    media_metadata: true })
.then(result=>console.log(result)); 
  
|java
cloudinary.uploader().upload("couple.jpg", 
  ObjectUtils.asMap(
    "colors", true,
    "phash", true,
    "media_metadata", true));

|csharp
var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"couple.jpg"),
  Colors = true,
  Phash = true,
  Metadata = true};
var uploadResult = cloudinary.Upload(uploadParams);

|go
resp, err := cld.Upload.Upload(ctx, "couple.jpg", uploader.UploadParams{
	Colors:          api.Bool(true),
	Phash:           api.Bool(true),
	ImageMetadata:   api.Bool(true)})

|android
MediaManager.get().upload("couple.jpg")
  .option("colors", true)
  .option("phash", true)
  .option("media_metadata", true).dispatch();

|swift
let params = CLDUploadRequestParams()
  .setColors(true)
  .setPhash(true)
  .setMediaMetadata(true)
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createUploader().signedUpload(
  url: "couple.jpg", params: params) 

|cli
cld uploader upload couple.jpg colors=true phash=true media_metadata=true

|curl
curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=couple.jpg&media_metadata=true&colors=true&phash=true&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
```

## Data extraction on already uploaded images

There are two ways to request data extraction on already uploaded images:

* Use the [Explicit](image_upload_api_reference#explicit_method) method of the Upload API to request data extraction on a single asset. This method is not rate-limited and requires a signature to be generated on the server side.
* Use the [Update resources](admin_api#update_resources) method of the Admin API. This method is rate-limited and requires your API key and secret, so is not suitable for use in client-side code.

### Explicit example

The following example uses the [Explicit](image_upload_api_reference#explicit_method) method of the Upload API to request the pHash value, a color analysis, and the media metadata on an uploaded image with a public ID of "couple1":

```multi
|ruby  
Cloudinary::Uploader.explicit("couple1",  
  type: "upload",
  colors: true,  
  phash: true,  
  media_metadata: true)
 
|php_2
$cloudinary->uploadApi()->explicit("couple1", [ 
    "type" => "upload",
    "colors" => true,
    "phash" => true,
    "media_metadata" => true]);
  
|python
cloudinary.uploader.explicit("couple1", 
  type = "upload",
  colors = True,
  phash = True,
  media_metadata = True)


|nodejs
cloudinary.v2.uploader.explicit("couple1", 
  { type: "upload",
    colors: true,
    phash: true,
    media_metadata: true })
.then(result=>console.log(result)); 
  
|java
cloudinary.uploader().explicit("couple1", 
  ObjectUtils.asMap(
    "type", "upload",
    "colors", true,
    "phash", true,
    "media_metadata", true));

|csharp
var explicitParams = new ImageExplicitParams("couple1"){
  Type = "upload",
  Colors = true,
  Phash = true,
  Metadata = true};
var explicitResult = cloudinary.Explicit(explicitParams);

|go
resp, err := cld.Upload.Explicit(ctx, uploader.UploadParams{
	PublicID:       "couple1",
  Type:           "upload",
  Colors:         api.Bool(true),
	Phash:          api.Bool(true),
	ImageMetadata:  api.Bool(true)})

|android
MediaManager.get().explicit("couple1")
  .option("colors", true)
  .option("type", "upload")
  .option("phash", true)
  .option("media_metadata", true).dispatch();

|swift
let params = CLDExplicitRequestParams()
  .setColors(true)
  .setPhash(true)
  .setType("upload")
  .setMediaMetadata(true)
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createManagementApi().explicit("couple1", params: params)

|cli
cld uploader explicit couple1 type="upload" colors=true phash=true media_metadata=true

|curl
curl https://api.cloudinary.com/v1_1/demo/image/explicit -X POST --data 'type=upload&public_id=couple1&media_metadata=true&colors=true&phash=true&timestamp=173719931&api_key=436464676&signature=a788d68f86a6f868af'
```

### Update resources example

The following example uses the [Update resources](admin_api#update_resources) method of the Admin API to request the pHash value, a color analysis, and the media metadata on an uploaded image with a public ID of "table":

```multi
|curl
curl \
 -d "type=upload&media_metadata=true&colors=true&phash=true" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/table
        
|ruby
result = Cloudinary::Api
.update("table",
  type: "upload",
  colors: true,  
  phash: true,  
  media_metadata: true)

|php_2
$result = $api
->update("table", [
    "type" => "upload",
    "colors" => true,
    "phash" => true,
    "media_metadata" => true]);

|python
result = cloudinary.api\
.update("table",
  type = "upload",
  colors = True,
  phash = True,
  media_metadata = True)

|nodejs
cloudinary.v2.api
.update("table", 
  { type: "upload",
    colors: true,
    phash: true,
    media_metadata: true})
.then(result=>console.log(result)); 

|java
result = cloudinary.api()
.update("table",
  ObjectUtils.asMap(
    "type", "upload",
    "colors", true,
    "phash", true,
    "media_metadata", true));

|csharp
var updateParams = new UpdateParams("table"){
  Type = "upload",
  Colors = true,
  Phash = true,
  Metadata = true};
var updateResult = cloudinary.UpdateResource(updateParams); 

|go
	resp, err := cld.Admin.UpdateAsset(ctx, admin.UpdateAssetParams{
	PublicID:         "table",
	Type:           "upload",
  Colors:         api.Bool(true),
	Phash:          api.Bool(true),
	ImageMetadata:  api.Bool(true)})

|cli
cld admin update table type="upload" colors=true phash=true media_metadata=true
```

## Sample response

The following is an example of a JSON response returned with the following additional information: `media_metadata`, `colors`,and `phash`:

```json
{
  "asset_id": "3515c6000a548515f1134043f9785c2f",
  "public_id": "gotjephlnz2jgiu20zni",
  "version": 1719307544,
  "version_id": "7d2cc533bee9ff39f7da7414b61fce7e",
  "signature": "d0b1009e3271a942836c25756ce3e04d205bf754",
  "width": 1920,
  "height": 1441,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2024-06-25T09:25:44Z",
  "tags": [],
  "pages": 1,
  "bytes": 896838,
  "type": "upload",
  "etag": "2a2df1d2d2c3b675521e866599273083",
  "placeholder": false,
  "url": "http://res.cloudinary.com/cld-docs/image/upload/v1719307544/gotjephlnz2jgiu20zni.jpg",
  "secure_url": "https://res.cloudinary.com/cld-docs/image/upload/v1719307544/gotjephlnz2jgiu20zni.jpg",
  "asset_folder": "",
  "display_name": "couple",
  "image_metadata": {
    "PerspectiveHorizontal": "0",
    "RedHue": "0",
    "Exposure": "0.00",
    ...
    ...
    ...
    "ExposureTime": "1/320"
  },
  "colors": [
    ["#152E02", 7.9], ["#2E4F06", 6.3], ["#3A6604", 5.6], ["#EEF2F3", 5.2], ["#598504", 4.6], ["#0D1903", 4.6], ["#DCDFDB", 4.4], ["#7AA403", 3.9], ["#DBE98A", 3.8], ["#4C7208", 3.5], ["#8DAC30", 3.3], ["#6C9406", 3.2], ["#6E912F", 3.2], ["#B0C95F", 3.1], ["#89AF07", 3.1], ["#9E744E", 2.9], ["#CD9A6F", 2.8], ["#D8B395", 2.5], ["#719357", 2.4], ["#ACCDBC", 2.3], ["#8E6437", 2.3], ["#E2E0A0", 2.3], ["#2C4B16", 2.3], ["#656950", 2.1], ["#25370A", 2.0], ["#73A092", 1.9], ["#4E3721", 1.6], ["#A0AD9A", 1.6], ["#BBD258", 1.5], ["#5B602B", 1.3], ["#302B1D", 1.3], ["#9CA25C", 1.2]
  ], 
  "predominant": {
    "google": [
      ["green", 65.3], 
      ["white", 11.4], 
      ["brown", 6.6], 
      ["yellow", 5.9], 
      ["orange", 5.5], 
      ["gray", 0.5]], 
    "cloudinary":[
      ["olive", 39.4], 
      ["green", 25.1], 
      ["white", 11.4], 
      ["yellow", 5.9], 
      ["orange", 5.5], 
      ["brown", 5.2], 
      ["lime", 2.2], 
      ["gray", 0.5]
    ]
  },
  "phash": "ebb822db6d10f1e",
  "illustration_score": 0.9,
  "coordinates": {
    "custom": [[80, 140, 220, 111]],
    "faces": [[98, 74, 61, 83], [139, 130, 52, 71]]    
  },
  "semi_transparent": false,
  "grayscale": false,
  "original_filename": "couple",
  "api_key": "614335564976464"
}
```

## Clara Denari mini-mystery game

  
    
    
      
      
        🔬 The Color Lab Analysis
        A Clara Denari Mini Mystery, Part 2
        Didn't play Part 1 yet? Try it here.
      
    
    
    

    
    
      
        
        
          
            
            
              Welcome to my color lab! 🔬
              I found sapphire earrings in my backyard. My neighbor, Mrs. Patterson, claims they're hers and showed me an old photo of her grandmother wearing similar ones. The photo was blurry, so I uploaded a restored version using Cloudinary's AI.
              The earrings look similar, but are they the same? 
              Let's extract them from the photo and compare the exact colors. If they don't match, Mrs. Patterson has some explaining to do! 🕵️‍♀️
            
          
        
        
        
        
          🔍 Evidence to Analyze
          
            
              
                
              
              My earrings
            
            
              
                
              
              Restored photo
            
          
        
        
        
        
          
            🎮 Analyze the Colors
          
        
      
    

    
    
      
        
        
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              First, I need to extract just the earrings from the photo. Cloudinary can do this with AI! ✨
            
          
          
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              Build a URL with these transformations (in order, separated by <code>/, and between <code>/upload/ and <code>/v1768...):
              
                <code>e_extract:prompt_earring: AI extracts the earring
                <code>c_crop,w_100,h_100,g_north_west,x_355,y_385: crop & resize to 100x100px
                <code>f_auto: best format
                <code>q_auto: optimized quality
              
              Let's see those earrings!
            
          
          
          
          
        
        
        
        
          📸 Source Image
          
            
              
                
              
              earrings_restored.png
            
          
        
        
        
        
          
            Build your extraction URL:
            💡 Need a hint?
          
          https://res.cloudinary.com/demo/image/upload/earrings_restored.png
          
          
          
          
            ✂️ Extract the Earrings!
          
        
      
    
    

    
    
      
        
        
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              The extraction worked! Now let's upload this extracted image with color analysis enabled.
              First, choose which SDK you want to use:
              
                Node.js
                Python
                Ruby
                PHP
                Java
                Go
              
            
          
          
          
          
            
              
              
              
            
          
          
          
          
            
            
              Cool, you chose Node.js! Now edit the starter code with the values below so it analyzes colors:
              
                • To analyze colors: <code id="clara-mystery__param1-name-analyze">param1 → <code id="clara-mystery__param1-value-analyze">colors, <code id="clara-mystery__value1-label-analyze">value1 → <code id="clara-mystery__true-value-analyze">true
                • To name it: <code id="clara-mystery__param2-label-analyze">param2 → <code id="clara-mystery__param2-name-analyze">public_id, <code id="clara-mystery__value2-label-analyze">value2 → <code>cropped_earrings
                • To store in folder: <code id="clara-mystery__param3-label-analyze">param3 → <code id="clara-mystery__param3-name-analyze">asset_folder, <code id="clara-mystery__value3-label-analyze">value3 → <code>evidence
              
            
          
          
          
          
        
        
        
        
          ✂️ Extracted Earring
          
            
              
                
              
              Upload this image
            
          
          Source: https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/earrings_restored.png
        
        
        
        
          

  
    
      Node.js
      Python
      Ruby
      PHP
      Java
      Go
    
    💡 Need a hint?
  
  
  
    cloudinary.v2.uploader.upload('https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png', {
  param1: value1,
  param2: 'value2',
  param3: 'value3'
})
  
  
  
    cloudinary.uploader.upload('https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png',
  param1 = value1,
  param2 = 'value2',
  param3 = 'value3')
  
  
  
    Cloudinary::Uploader.upload('https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png',
  param1: value1,
  param2: 'value2',
  param3: 'value3')
  
  
  
    upload('https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png', [
  'param1' => value1,
  'param2' => 'value2',
  'param3' => 'value3'
])">(new UploadApi())->upload('https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png', [
  'param1' => value1,
  'param2' => 'value2',
  'param3' => 'value3'
])
  
  
  
    cloudinary.uploader().upload("https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png", ObjectUtils.asMap(
  "param1", value1,
  "param2", "value2",
  "param3", "value3"
));
  
  
  
    cld.Upload.Upload(ctx, "https://res.cloudinary.com/demo/image/upload/e_extract:prompt_earring/c_crop,w_100,h_100,g_north_west,x_355,y_385/f_auto/q_auto/v1768438613/earrings_restored.png", uploader.UploadParams{
  param1: value1,
  param2: "value2",
  param3: "value3"
})
  

          
          
          
          
            🎨 Upload & Analyze Colors!
            Reset Code
          
        
      
    
    

    
    
      
        
        
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              The upload worked and Cloudinary analyzed the colors! 🎨
              Now, look at the <code>colors array in the response. I need the second color - that's the predominant blue color after the white one.
            
          
          
          
          
            
              
              
              
            
          
          
          
          
            
            
              Find the hex code and enter it below. This is the moment of truth! 🔍
            
          
          
          
          
        
        
        
        
          📊 Color Analysis Response
          
            <pre class="clara-mystery__code" style="margin: 0; line-height: 1.3;"><code>{
  "asset_id": "a1b2c3d4e5f6g7h8i9j0",
  "public_id": "cropped_earrings",
  "version": 1763564796,
  "width": 100,
  "height": 100,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2024-01-15T10:30:00Z",
  "bytes": 12345,
  "type": "upload",
  "url": "http://res.cloudinary.com/.../cropped_earrings.jpg",
  "secure_url": "https://res.cloudinary.com/.../cropped_earrings.jpg",
  "asset_folder": "evidence",
  "colors": [
    ["#FCFCFB", 53.9],
    ["#404169", 25.0],
    ["#E3E3EA", 10.3]
  ],
  "predominant": {
    "google": [["white", 73.0], ["blue", 18.8]],
    "cloudinary": [["white", 73.0], ["blue", 18.8]]
  },
  "original_filename": "cropped_earrings"
}
          
        
        
        
        
          
            
              Enter the predominant color hex code:
              
            
            
            
            
            🔍 Check the Match!
          
        
      
    
    

    
    
      
        
        
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              🎉 Mystery Solved!
              I knew something was off! My earrings are Deep Slate Blue (#3B3D81), but Mrs. Patterson's are Indigo Blue (#404169). Color analysis proves they're NOT the same! 🕵️‍♀️
            
          
          
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              💡 Key Takeaways:
              
              You've learned how to:
              ✓ Extract colors with <code>colors: true
              ✓ Use AI object detection to isolate objects with <code>e_extract:prompt_object
            
          
          
          
          
            
            
              
              
              
            
          
          
          
          
            
            
              🚀 Next Steps:
              
              Try it in your environment! 
              Click Back for the game example, or explore more options here:
              
              
                📤 Extract Colors, Faces, EXIF & More
                🤖 Explore AI Content Analysis
              
            
          
          
        
        
        
        
          🔬 Color Analysis Results
          
            
              
                
              
              
              <code>#3B3D81
              My earrings
            
            
            ≠
            
            
              
                
              
              
              <code>#404169
              Photo earrings
            
          
          
            Note: This mini‑mystery uses a simulated upload. In real apps, authenticate uploads with your Cloudinary API key and secret on a secure server, and never expose those credentials in client‑side code.
          
        
        
        
        
          🎊 Case Closed!
          The earrings Clara found are NOT the same as Mrs. Patterson's grandmother's earrings. Clara gets to keep her treasure!
        
      
    

    
    
      ← Back
      Next →
      🔄 Play Again
    
      
    
  

  
    
      💡 Hint
      ✕
    
    
      
        URL Structure for Transformations:
        
          https://res.cloudinary.com/cloud_name/image/upload/transformations/version/public_id.format
        
        
        Key points:
        
          Transformations go right after <code>/upload/
          Transformations come before the version (<code>v1768438613)
          Multiple transformations are separated by forward slashes (<code>/)
          Parameters within a transformation are separated by commas (<code>,)
        
        
        You need these transformation groups:
        
          <code>e_extract:prompt_earring - extracts the earrings
          <code>c_crop,w_100,h_100,g_north_west,x_355,y_385 - crops to focus on earrings and resizes to 100x100px
          <code>f_auto - auto format
          <code>q_auto - auto quality
        
        
        
          Example structure:
          <code>...upload/group1/group2/group3/group4/...
          Separate groups with <code>/, parameters within groups with <code>,
        
      
      
      
        Remember the upload structure:
        
          // Each SDK has an uploader with an upload method:
          uploader.upload(file_url, {parameters})
        
        
        Quick tips:
        
          The file URL comes first, then the parameters object
          Use the extracted earring URL from Step 1
          You need these three parameters:
            
              Replace <code>param1 with <code>colors and <code>value1 with <code id="clara-mystery__hint-true-value">true
              Replace <code>param2 with <code>public_id and <code>value2 with <code>cropped_earrings
              Replace <code>param3 with <code>asset_folder and <code>value3 with <code>evidence
            
          
          Watch your syntax! Each language has slightly different formats:
            
              
                
                  Node.js: <code>param: value
                  Python: <code>param=value
                  Ruby: <code>param: value
                
              
              
                
                  PHP: <code>'param' => value
                  Java: <code>"param", value
                  Go: <code>Param: value
                
              
            
          
          Don't forget commas between parameters!
        
        
        
          Still stuck? Look at the placeholder code in your selected language tab - it shows the basic structure you need.
        
      
    
  

See the blog post on [API for extracting semantic image data - colors, faces, Exif data and more](/blog/api_for_extracting_semantic_image_data_colors_faces_exif_data_and_more) for more information on semantic data extraction.