Social Stream API Endpoints

URI Structure

All Ditto REST API endpoints are located at https://social.dittolabs.io (supports http as well). There are three endpoints available:

  • Stream: get information about posted photos for specific brands to your client_id.

    https://social.dittolabs.io/v3/stream?client_id=...&brands=...

  • Photos: get information about posted photos for specific brands to your client_id.

    https://social.dittolabs.io/v3/photos?client_id=...&brands=...

  • Brands: get information about the brands specific to your client_id.

    https://social.dittolabs.io/v3/brands?client_id=...

Stream Endpoint

Request Parameters

Parameter Description Required?
https://social.dittolabs.io Domain for API Yes
version The version of the API for compatibility tracking. Currently v3 is supported. Yes
endpoint API endpoint for information about photos: /stream Yes
client_id A unique API key that identifies you as a client and controls which brands you can access using the Ditto REST API Yes
brands A unique number indicating the ID of the specified brand in the request. If this parameter isn't specified, then results are returned for all brands for the client account. Use the brands endpoint to find the IDs of available brands. No
min_time The earliest time in epoch seconds inclusive, from which records will be retrieved. This parameter is intended to be used to start the paging process. It is not intended not be provided with the offset parameter. All of the data equal to or later than this time will be returned from this request and any subsequent requests as the results are paged through using offset. The data will not necessarily be in order by time. The data may also include some results that are earlier than the min_time. If neither a min_time nor an offset are provided, then the earliest results returned will start at current date and time minus the look back interval for the account. No
offset A string offset that is used to support paging through the results. This offset should come from the next_offset provided in an earlier response. No
count The maximum number of photos to return (the default is 20). The maximum value is 250. No

Response

Common Response Elements

The response to a /stream 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. Possible values:
  • OK
  • invalid_argument
  • invalid_endpoint
more_available String "true" if there are more photos available immediately and "false" otherwise. Since photo matches are being generated continuously, even if the response is "false", there may be more data available immediately after the response is received Possible values:

"true", "false"

next_offset String The value to hand in on the next request as the offset to get the next "batch" of photos for the brands specified. If there was no new data available for the brands specified, then the next_offset returned may be same as the offset in request.
photos Array An array of hashes with one for each of the photos provided in the response See the photo hash documentation below
Photos Hash
Field Type Description Notes
id String The database id of the match derived from the unique id of the source
source String Data source of the image
photo_date Integer Time that the photo was posted in epoch seconds
photo_date_utc String Time that the photo was posted in UTC time
image_width Integer The width of the image in pixels
image_height Integer The height of the image in pixels
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

image_index Integer Indicates the index of the image if a post contains multiple images 0-based
native_id String The unique id of the post from Twitter. For twitter, this is the tweet_id.
nfaces Integer The number of faces detected in the image
faces Array of hash An 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 An 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.
user_id String The user ID of the person who posted the photo Only available for Twitter
matches Array An array that contains a match hash for every brand found in the image See the match hash documentation below
image_coordinates_scaled String Indicates whether the coordinates provided in the image_width, image_height, logo_rect and smiles rects are in the coordinate system of the image provided in the original image dimensions or scaled. If this is "true", then the image_width and image_height have the same aspect ratio as the image itself, but are both scaled by the same value. Also the the logo_rect and smiles rects are scaled by the same amount, so their locations are proportional to the image_width and image_height. Possible values:

"true", "false"

Match Hash
Field Type Description Notes
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
brand String The brand id Use the brands endpoint to find the IDs of available brands.
match_quality String A score indicating the confidence in the match quality of the image to the logo Possible values:
  • High
  • Medium
  • Low
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
        
{
  "status": "OK",
  "more_available": "false",
  "next_offset": "68403560",
  "photos": [
    {
      "id": "555555",
      "source": "twitter",
      "photo_date": 1394851907,
      "photo_date_utc": "2014-03-15 02:51:47",
      "image_width": 768,
      "image_height": 1024,
      "average_mood": -2.30217,
      "nmoods": 2,
      "moods": [
        {
          "mood": -0.154335,
          "face_rect": [[91,230],[355,230],[91,494],[355,494]]
        },
        {
          "mood": -4.45,
          "face_rect": [[639,69],[787,69],[639,217],[787,217]]
        }
      ],
      "nfaces": 3,
      "faces": [
        {
          "score": 65,
          "face_rect": [[646,567],[762,567],[646,723],[762,723]]
        },
        {
          "score": 62,
          "face_rect":[[101,188],[345,188],[101,514],[345,514]]
        },
        {
          "score": 47,
          "face_rect":[[659,65],[779,65],[659,223],[779,223]]
        }

      ],
      "attributes": {
        "labels": [
          {
            "id": 751,
            "label": "race car",
            "confidence": ​0.935932
          },
          {
            "id": 581,
            "label": "grille",
            "confidence": ​0.845735
          },
          {
            "id": 2001,
            "label": "safe for work"
            "confidence": 0.9963533772044218,
            "probability": 0.8843898776065096,
          }
        ]
      },
      "image_index": 0,
      "native_id": "555555",
      "user_id": "123456789",
      "matches":[
        {
          "logo_rect": [[202,239],[175,451],[404,474],[408,251]],
          "brand": 833,
          "match_quality": "High"
        }],
      "image_coordinates_scaled": "true"
     }]
}
        
      

Photos Endpoint

Request Parameters

Parameter Description Required?
https://social.dittolabs.io Domain for API Yes
version The version of the API for compatibility tracking. Currently v3 is supported. Yes
endpoint API endpoint for information about photos: /photos Yes
client_id A unique API key that identifies you as a client and controls which brands you can access using the Ditto REST API Yes
brands A unique number indicating the specified brand in the request. Yes
min_time The earliest time in epoch seconds, inclusive, from which records will be retrieved No
max_time The latest time in epoch seconds, inclusive, from which records will be retrieved No

Photos Response

Common Response Elements

The response to a /photos 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. Possible values:
  • OK
  • invalid_argument
  • invalid_endpoint
min_time Integer Earliest time (when a photo was posted) returned for a photo in epoch seconds
max_time Integer Latest time (when a photo was posted) returned for a photo in epoch seconds
photos Array Array of data for each image returned See photos for more details
Photos Array

Information on the photos are returned as an array. Each element of the array is a hash with the following fields:

Field Type Description Notes
id String The database id of the match derived from the unique id of the source (Twitter). This is an internal id, but for Twitter images, it is the tweet_id.
source String Data source of the image Possible values:
  • twitter: Twitter
url String The URL to obtain the posted image
brand Integer A numeric value that maps to the desired brand To find out the brands available through your API key, read about the brands endpoint
match_quality String A score indicating the confidence in the match quality of the image to the logo Possible values:
  • High
  • Medium
  • Low
photo_date Integer Time that the photo was posted in epoch seconds
photo_date_utc String Time that the photo was posted in UTC time
image_width Integer The width of the image in pixels
image_height Integer The height of the image in pixels
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

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

image_index Integer Indicates the index of the image if a post contains multiple images 0-indexed
native_id String The unique id of the post from Twitter
nfaces Integer The number of faces detected in the image
faces Array of hash An 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 An 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.
user_id String The user ID of the person who posted the photo Only available for Twitter

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
        
          {
            "status": "OK",
            "min_time": 1388590348,
            "max_time": 1388621319,
            "photos": [
              {
                "id": "123456789",
                "source": "twitter",
                "url": "https://example-url.com/image.jpg",
                "brand": 6,
                "match_quality": "High",
                "photo_date": 1388604624,
                "photo_date_utc": "2014-01-01 19:30:24",
                "image_width": 400,
                "image_height": 533,
                "logo_rect": [[271,142],[287,305],[408,265],[386,146]],
                "average_mood": -2.30217,
                "nmoods": 2,
                "moods": [
                  {
                    "mood": -0.154335,
                    "face_rect": [[91,230],[355,230],[91,494],[355,494]]
                  },
                  {
                    "mood": -4.45,
                    "face_rect": [[639,69],[787,69],[639,217],[787,217]]
                  }
                ],
                "nfaces": 3,
                "faces": [
                  {
                    "score": 65,
                    "face_rect": [[646,567],[762,567],[646,723],[762,723]]
                  },
                  {
                    "score": 62,
                    "face_rect":[[101,188],[345,188],[101,514],[345,514]]
                  },
                  {
                    "score": 47,
                    "face_rect":[[659,65],[779,65],[659,223],[779,223]]
                  }

                ],
                "attributes": {
                  "labels": [
                    {
                      "id": 751,
                      "label": "race car",
                      "confidence": ​0.935932
                    },
                    {
                      "id": 581,
                      "label": "grille",
                      "confidence": ​0.845735
                    },
                    {
                      "id": 2001,
                      "label": "safe for work"
                      "confidence": 0.9963533772044218,
                      "probability": 0.8843898776065096,
                    }
                  ]
                },
                "image_index": 0,
                "user_id": "123456789",
                "native_id": "123456789"
              }
            ]
          }
        
      

Brands Endpoint

Request Parameters

Parameter Description Required?
https://social.dittolabs.io Domain for API Yes
version The version of the API for compatibility tracking. Currently v3 is supported. Yes
endpoint API endpoint for information about photos: /brands Yes
client_id A unique API key that identifies you as a client and controls which brands you can access using the Ditto REST API Yes

Brands Response

The response to a /brands request is an array of brands associated with the client_id. Each element is a hash containing the following:

Field Type Description Notes
id Integer The id associated internally with each brand and used in requests
name String The brand name
Sample Response
        
          [
            {
              "id": "529",
              "name": "Disney"
            },
            {
              "id": "2",
              "name": "Dunkin Donuts"
            },
            {
              "id": "108",
              "name": "Cadillac"
            },
            {
              "id": "79",
              "name": "Harley-Davidson"
            }
          ]