Photo Reader API Endpoints

URI Structure

All Ditto Photo Reader API endpoints are located at http://<BASE-ENDPOINT>.ditto.us.com. There are 2 <BASE-ENDPOINT>: 1) base endpoint to process an image and 2) base endpoint to query for various stats, such as current capacity and client usage numbers

If you have a custom account configured with us, we will provide you with the correct <BASE-ENDPOINT>. If you do not, then the generic base endpoints are:

  • process images: ondemand-p02-api
  • stats: ondemand-p02-stats-api

To process an image, there is one endpoint you can call to the base endpoint:

  • Find: process an image

    http://<BASE-ENDPOINT>.ditto.us.com/v1/find?...

For the stats base, there are 3 endpoints:

  • Capacity: Get the current capacity number of the system

    http://<BASE-ENDPOINT>.ditto.us.com/v1/capacity?...

  • Usage: Get the number of requests made with your client id

    http://<BASE-ENDPOINT>.ditto.us.com/v1/usage?...

  • This is valid only for customers with custom accounts configured with us.
    Brands: Get brands associated with your account, if applicable.

    http://<BASE-ENDPOINT>.ditto.us.com/v1/brands?...


Find Endpoint

Request Parameters

Parameter Description Required?
http://<BASE-ENDPOINT>.ditto.us.com Domain for API Yes
version The version of the API for compatibility tracking. Currently v1 is supported. Yes
endpoint API endpoint for image processing: /find Yes
client_id A unique API key that identifies you as a client and controls your access to the Ditto Photo Reader API Yes
url A URL to an image Yes
uid A unique identifier of your choice Yes

Find Response

Common Response Elements

The response to a /find query is a JSON hash with the following fields:

Field Type Description Notes
status String A status value indicating whether or not the query was successful. See Status Codes for more details
url String Location of image url (from request)
uid String Unique identifier (from request)
data Hash Analysis results of image See Data Hash for more details

Status Codes

List of status codes and messages returned in the find response.

Status Code Status Message Retry Notes
400 Invalid Endpoint N A non-existent endpoint was called, required arguments are missing, or invalid client_id
401 Unauthorized N Invalid authorization
404 Failed to retrieve image N Image could not be retrieved in a timely fashion
408 Image Retrieve Timeout Y Retry with limited exponential backoff
415 Invalid Image N Image retrieved does not appear to be an image
429 Rate Limit Exceeded Y Wait to retry; the client_id has exceeded the hourly quota of requests
500 Other Y Other status messages can be treated the same as No Capacity. Ex: No Slot
503 No Capacity Y Wait for capacity to retry. Request could not be processed because there is no available capacity. You can either discard or retry the request (using a suitable backoff algorithm)
504 ERR N System couldn't process image

Data Hash

Information on the image is returned as a hash with the following fields:

Field Type Description Notes
image_width Integer Width of the image in pixels
image_height Integer Height of the image in pixels
matches Array of hash An array that contains a hash for every brand found in the image See Matches Hash for more details
attributes Hash

A hash containing information about identified objects and contexts in the image and the confidence in those matches.

The "Safe for Work" label is contained in the attributes hash for clients who have signed up for this classifier.

Please note: a low "Safe for Work" score indicates it is less likely to be safe, rather than it being less safe.

Please contact us if you're interested.

See Attributes Hash for more details

nfaces Integer The number of faces detected in the image
faces Array of hash Any array that contains a hash for every face found in the image See Faces Hash for more details
nmoods Integer The number of expressions detected in the image
moods Array of hash Any array that contains a hash for every expression found in the image See Moods Hash for more details
average_mood Float A score indicating the number of smiles (positive or negative) found in an image. The positive and negative values determine the mood of the image.

Matches Hash

A matches hash contains information about a specific brand found in the image. The fields are:

Field Type Description Notes
brand String The name of the brand
match_quality String A score indicating the confidence in the match quality of the image to the logo Possible values:
  • High
  • Medium
  • Low
logo_rect Array A nested array of 4 coordinate pairs indicating the location of the logo within the image Each coordinate pair is one corner point (x,y) of the brand logo as it would appear in the image. Please note that these points can be outside the image if the brand logo is near the boundary of the photo.

Attributes Hash

The attributes hash contains information about the objects and contexts being returned. The fields are:

Field Type Description Notes
labels Array of hashes An array that contains a hash for every object or context See Labels Hash for more details

Labels Hash

A labels hash contains information about the objects and contexts found in the image. The fields are:

Field Type Description Notes
id Integer A unique id for the associated object or context label
label String The object or context label, such as "beach" or "glass" Strings may not be unique
confidence Float

The confidence score indicates the chance that our prediction is correct.

Consuming only images that were returned with high scores will provide you with the greatest chance for accurate predictions. Please be aware that with a very high threshold you will increase your chances of missing correctly labeled but lower scoring images.

When it is critical for your application to only show correctly labeled images (for example, with "Safe for Work") we recommend a minimum confidence score of 0.90:

Confidence ScoreDescription
0.99 < C <= 1.00Very High Confidence
0.90 < C <= 0.99High Confidence
0.50 < C <= 0.90Medium Confidence
0.00 <= C < 0.50Low Confidence
Range can be 0.0-1.0
probability Float

The "Safe for Work" classifier is a particularly sensitive and important label. For users interested in a precisely calibrated metric we also offer a probability score for this classifier. If you opt to filter based on the probability score we recommend a threshold of 0.997 or above.

The "Safe for Work" probability score can be understood as follows:

“For 1,000 images with a probability of .999, you can expect 999 images to be Safe for Work”

Please note: The "Safe for Work" confidence score (described above) is derived from this probability. For most use cases we recommend using the confidence score.

At this time only "Safe for Work" offers a probability score.

Range can be 0.0-1.0


Faces Hash

A faces hash contains information about the faces found in the image. The fields are:

Field Type Description Notes
face_rect Array A nested array of 4 coordinate pairs indicating the location of the face within the image Each coordinate pair is one corner point (x,y) of the face as it would appear in the image. Please note that these points can be outside the image if the face is near the boundary of the photo.
score Integer A score indicating the confidence in the identified area containing a face
Moods hash

A moods hash contains information about identifiable expressions found in the image. The fields are:

Field Type Description Notes
face_rect Array A nested array of 4 coordinate pairs indicating the location of the facial expression within the image Each coordinate pair is one corner point (x,y) of the expression as it would appear in the image. Please note that these points can be outside the image if the facial expression is near the boundary of the photo.
mood Float A score of how positive or negative the expression is Higher values indicate bigger smiles. Lower values indicate deeper frowns.

Sample Response
http://ondemand-p02-api.ditto.us.com/v1/find?client_id=...&url=http://example-url.com/image.jpg&uid=myidentifier1
        
  {
    "url": "http://example-url.com/image.jpg",
    "uid": "myidentifier1",
    "data": {
      "image_width": 800,
      "image_height": 640,
      "matches": [
        {
          "match_quality": "High",
          "brand": "Starbucks",
          "logo_rect": [[479, 521],[476, 669],[641, 671],[643, 518]]
        },
        {
           "match_quality": "Medium",
           "brand": "Dunkin_Donuts",
           "logo_rect": [[91,101],[73,336],[273,285],[274,99]]
         }
      ],
      "attributes:" {
        "labels": [
          {
            "id": 1036,
            "label": "baked goods",
            "confidence": 0.81353479325771332
          },
          {
            "id": 1049,
            "label": "coffee cup",
            "confidence": 0.91216262727975845
          },
          {
            "id": 2001,
            "label": "safe for work"
            "confidence": 0.9963533772044218,
            "probability": 0.8843898776065096,
          }
        ]
      },
      "nfaces": 2,
      "faces": [
        {
          "face_rect": [[404, 187],[584, 187],[404, 429],[584, 429]],
          "score": 45
        },
        {
          "face_rect": [[73, 155],[303, 155],[73, 461],[303, 461]],
          "score": 38
        }
      ],
      "nmoods": 1,
      "average_mood": 1.370337,
      "moods": [
        {
          "mood": 5.150946,
          "face_rect": [[393, 207],[605, 207],[393, 419],[605, 419]]
        }
      ]
    },
    "status": "OK"
  }
        
      

Capacity Endpoint

Request Parameters

Parameter Description Required?
http://<BASE-ENDPOINT>.com Domain for API Yes
version The version of the API for compatibility tracking. Currently v1 is supported. Yes
endpoint API endpoint for information about capacity: /capacity Yes
client_id A unique API key that identifies you as a client Yes

Capacity Response

The response to a /capacity request is a hash with 2 key-value pairs:

Field Type Description Notes
capacity Integer The number of simultaneous requests available for the Photo Reader API
age Integer The age since the capacity was computed Unit type: seconds
Sample Response
http://ondemand-p02-stats-api.ditto.us.com/capacity?client_id=...
        
          {
            "capacity": 128,
            "age": 6
          }
        
      

Usage Endpoint

Request Parameters

Parameter Description Required? Notes
http://<BASE-ENDPOINT>.com Domain for API Yes
version The version of the API for compatibility tracking. Currently v1 is supported. Yes
endpoint API endpoint for information about usage: /usage Yes
client_id A unique API key that identifies you as a client Yes
period The resolution of the usage No Possible values:
  • hour
  • day
  • week (Sunday start date)
Defaults to day
date A date to request usage numbers from No Format is YYYYMMDD. Defaults to today's date. NOTE: If period is set to week, then the usage number will correspond to the week that the requested date is in (Sunday - Saturday inclusive)
hour An hour to request numbers from No Expressed in 24-hour and UTC. Defaults to 0. NOTE: This parameter only works if period is set to hour

Usage Response

The response to a /usage request is a hash with a single key-value pair:

Field Type Description Notes
usage Integer The number of requests the API has received in the time range
monthly_usage Integer The number of requests the API has received in the month relative to the time range
Sample Responses
This will return the usage number for the current day. http://ondemand-p02-stats-api.ditto.us.com/usage?client_id=...
        
          {
            "usage": 2583779,
            "monthly_usage": 3028729
          }
        
      

This will return the usage number for '2015-01-12'. The monthly_usage number will be for January 2015.
http://ondemand-p02-stats-api.ditto.us.com/usage?client_id=...&day=20150112'

This will return the usage number for the 13th hour UTC for today.
http://ondemand-p02-stats-api.ditto.us.com/usage?client_id=...&period=hour&hour=13

This will return the usage number for the current week.
http://ondemand-p02-stats-api.ditto.us.com/usage?client_id=...&period=week

This will return the usage number for the week that '2015-01-12' is in, so from '2015-01-11 00:00:00' to '2015-01-17 23:59:59'.
http://ondemand-p02-stats-api.ditto.us.com/usage?client_id=...&period=week&date=20150112

Brands Endpoint

NOTE: This endpoint will only return brands if you have a custom configured account with us.

Request Parameters

Parameter Description Required? Notes
http://<BASE-ENDPOINT>.com Domain for API Yes
version The version of the API for compatibility tracking. Currently v1 is supported. Yes
endpoint API endpoint for information about brands: /brands Yes
client_id A unique API key that identifies you as a client Yes

Brands Response

The response to a /brands request is a hash with a single key-value pair:

Field Type Description Notes
"brands" Array of Strings An array containing strings of the brands configured for the account
Sample Responses
NOTE: This endpoint will only return brands if you have a custom configured account with us. Otherwise the brands array will be empty. http://ondemand-p02-stats-api.ditto.us.com/brands?client_id=...
        
          {
            "brands": [
              "brand_name_1",
              "brand_name_2",
              "brand_name_3"
            ]
          }