SinglePlatform Photos API Documentation

Introduction

The SinglePlatform Photos API enables you to retrieve photo URLs for the hundreds of thousands of photos uploaded by merchants to SinglePlatform's database. All of the photos retrieved through this API have been manually curated, tagged with a photo category, and checked for quality and appropriateness.

The Request

Base URL: http://publishing-api.singleplatform.com

Get Photos by Location:

Send HTTP GET request to URL /locations/<location_id>/photos with the following URL parameters.

height: the maximum height (in pixels) for photos returned.

width: the maximum width (in pixels) for photos returned.

type: Including this parameter in your request will filter your results by photo category. SinglePlatform's categories include interior, exterior, item, logo, or uncategorized. Excluding this parameter in your request will return all photo categories.

source: Including this parameter in your request will filter your results by photo source. SinglePlatform's photo sources include singleplatform and mobile. The 'singleplatform' photo source indicates that the photo has been uploaded directly by the merchant. The 'mobile' photo source indicates the photo has been uploaded by a consumer via SinglePlatform's mobile sites. All photos, regardless of the source, have been manually approved for quality and appropriateness.

* Please note, querying by the type and source URL parameters is not available in this version.

** The height and width parameters specific the maximum dimensions for all photos returned by the request. The photos' original aspect ratios are maintained, so the final dimensions of photos may be smaller than the specified height and width parameters.

Get Photos by Date Added:

Send HTTP GET request to URL /photos/updated_since with the following URL parameters.

date: The date must be in a YYYY-MM-DD format. This would return a response of all photo URLs (and their respective attributes) that have been added/updated since the given date.

height: the maximum height (in pixels) for photos returned.

width: the maximum width (in pixels) for photos returned.

The Response

After the API receives a properly formatted request, it attempts to pass back all photo data for the respective location. The response is a JSON object with a status code and data list.

If there is no error in your request, and the location contains no photos, you will receive an empty data list with a 200 status code.

If there is an error in your request, you will receive an error status code paired an error type and error message.

Data Descriptions

{
  "location_id": {string},
  "photo_id": {string},
  "title": {string},
  "type"; {string},
  "url": {string},
  "original_height": {integer},
  "original_width": {integer},
  "size": {integer},
  "source": {string},
  "main_image": {boolean},
  "items": [{integer}]
}

Examples:

Querying a location with one photo

Request:

/locations/landmarc/photos

Response:

{
   "code" : 200,
   "data" : [
      {
         "location_id" : "landmarc",
         "size" : 52934,
         "original_height" : 480,
         "items" : [],
         "source" : "singleplatform",
         "original_width" : 720,
         "type" : "Logo",
         "main_image" : true,
         "photo_id" : "2f0b4fe88b3bdea96d1b21a64e67f54c6b21edfd",
         "title" : "Landmarc",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/2f0b4fe88b3bdea96d1b21a64e67f54c6b21edfd.jpg"
      }
   ]
}

Querying a location with multiple photos

Request:

/locations/frank-fats/photos

Response:

{
   "data" : [
      {
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/597a9fdc37152203d77b5bd7c7ae4a5f05d5ef35.jpg",
         "original_width" : 3008,
         "source" : "singleplatform",
         "items" : [],
         "main_image" : false,
         "original_height" : 2000,
         "photo_id" : "597a9fdc37152203d77b5bd7c7ae4a5f05d5ef35",
         "size" : 396559,
         "title" : "Jar Jung Mein",
         "type" : "Product",
         "location_id" : "frank-fats"
      },
      {
         "size" : 437181,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/1a95ebfb1181dff1787d94ed085940866d3cead1.jpg",
         "original_width" : 3008,
         "items" : [
            40048199
         ],
         "main_image" : false,
         "source" : "singleplatform",
         "photo_id" : "1a95ebfb1181dff1787d94ed085940866d3cead1",
         "original_height" : 2000,
         "type" : "Product",
         "location_id" : "frank-fats",
         "title" : "8 Treasure Fried Rice"
      },
      {
         "size" : 431991,
         "original_height" : 2000,
         "items" : [],
         "main_image" : false,
         "source" : "singleplatform",
         "photo_id" : "28edfafaa3da9573a9cbb65f5c35b34d0f056384",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/28edfafaa3da9573a9cbb65f5c35b34d0f056384.jpg",
         "original_width" : 3008,
         "location_id" : "frank-fats",
         "type" : "Product",
         "title" : "Mongolian Baby Back Ribs & Fries"
      },
      {
         "size" : 376722,
         "original_width" : 3008,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/c5ba585089a0ebb0044b797d7c42c6ec81007835.jpg",
         "items" : [
            40048200
         ],
         "main_image" : false,
         "source" : "singleplatform",
         "original_height" : 2000,
         "photo_id" : "c5ba585089a0ebb0044b797d7c42c6ec81007835",
         "type" : "Product",
         "location_id" : "frank-fats",
         "title" : "Meyer Lemon Chicken"
      },
      {
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/4514e4a264fa590248be7a044a2a10a96ee62543.jpg",
         "original_width" : 3008,
         "items" : [],
         "original_height" : 2000,
         "main_image" : false,
         "source" : "singleplatform",
         "photo_id" : "4514e4a264fa590248be7a044a2a10a96ee62543",
         "size" : 355699,
         "title" : "Mongolian Baby Back Ribs and Fries",
         "type" : "Product",
         "location_id" : "frank-fats"
      },
      {
         "title" : "",
         "type" : "Product",
         "location_id" : "frank-fats",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/a89ba18f58acb529ea39a4e5937fb4ecc92c0ae0.jpg",
         "original_width" : 3008,
         "main_image" : false,
         "items" : [
            25707073
         ],
         "original_height" : 2000,
         "source" : "singleplatform",
         "photo_id" : "a89ba18f58acb529ea39a4e5937fb4ecc92c0ae0",
         "size" : 456128
      },
      {
         "location_id" : "frank-fats",
         "type" : "Product",
         "title" : "",
         "size" : 139185,
         "items" : [
            25707091
         ],
         "main_image" : false,
         "photo_id" : "dbc3d966eb6a302e12cb264224b067b4a0c5f50a",
         "source" : "singleplatform",
         "original_height" : 1000,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/dbc3d966eb6a302e12cb264224b067b4a0c5f50a.jpg",
         "original_width" : 1420
      },
      {
         "size" : 146023,
         "main_image" : false,
         "items" : [
            40988657
         ],
         "original_height" : 1000,
         "source" : "singleplatform",
         "photo_id" : "4d84cc069aa931d71bf73ded48cb07f27c8b46a9",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/4d84cc069aa931d71bf73ded48cb07f27c8b46a9.jpg",
         "original_width" : 1504,
         "location_id" : "frank-fats",
         "type" : "Product",
         "title" : ""
      },
      {
         "items" : [
            25707083
         ],
         "source" : "singleplatform",
         "main_image" : false,
         "original_height" : 955,
         "photo_id" : "1e1fb3d5e7de9008b0438260dca6c3126d2423b9",
         "original_width" : 1459,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/1e1fb3d5e7de9008b0438260dca6c3126d2423b9.jpg",
         "size" : 177785,
         "title" : "",
         "location_id" : "frank-fats",
         "type" : "Product"
      }
   ],
   "code" : 200
}

Querying a location without photos

Request:

/locations/south-beach-grill/photos

Response:

{
   "code" : 200,
   "data" : []
}

Querying for photos by date added/updated

Request:

/photos/updated_since?date=2014-04-29

Response:

{
   "data" : [
      {
         "original_width" : 528,
         "original_height" : 375,
         "type" : "Exterior",
         "photo_id" : "373bcbd627e51c57a1e544481eb4cde18ea4d00a",
         "size" : 61422,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/373bcbd627e51c57a1e544481eb4cde18ea4d00a.jpg",
         "items" : [],
         "location_id" : "miss-shirleys",
         "main_image" : true,
         "source" : "singleplatform",
         "title" : ""
      },
      {
         "original_width" : 1500,
         "original_height" : 1259,
         "type" : "Product",
         "size" : 121584,
         "photo_id" : "f11a0f5758cece6b62aedf1425844fa8e144d6bc",
         "items" : [
            41684704
         ],
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/f11a0f5758cece6b62aedf1425844fa8e144d6bc.jpg",
         "main_image" : false,
         "location_id" : "miss-shirleys",
         "title" : "Spicy Shirley with 2 oz. Jumbo Lump Crab Meat",
         "source" : "singleplatform"
      },
      {
         "title" : "",
         "source" : "singleplatform",
         "main_image" : false,
         "location_id" : "southside-cafe",
         "items" : [],
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/38dd858d3ef3b27ae54718b6d928018059ef322a.jpg",
         "size" : 151056,
         "photo_id" : "38dd858d3ef3b27ae54718b6d928018059ef322a",
         "type" : "Product",
         "original_height" : 907,
         "original_width" : 1320
      },
      {
         "source" : "singleplatform",
         "title" : "1-800-Flowers Spring Inspiration",
         "location_id" : "1-800-flowers",
         "main_image" : true,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit/d5b517837bc84e14a29ce3074156002e1e0db854.jpg",
         "items" : [],
         "photo_id" : "d5b517837bc84e14a29ce3074156002e1e0db854",
         "size" : 34473,
         "original_height" : 378,
         "type" : "Product",
         "original_width" : 345
      }
   ],
   "code" : 200
}

Querying a location for photos and specifying photo dimensions

Request:

/locations/pizza-express-30/photos?width=700&height=100

Response:

{
   "data" : [
      {
         "items" : [
            25966190
         ],
         "title" : "",
         "source" : "singleplatform",
         "original_width" : 5616,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit,w_700,h_400/bdc3f4d83f43ec9eea1fc073c526aeabb65794e3.jpg",
         "photo_id" : "bdc3f4d83f43ec9eea1fc073c526aeabb65794e3",
         "type" : "Product",
         "main_image" : false,
         "original_height" : 3744,
         "size" : 887548,
         "location_id" : "sublime-9"
      },
      {
         "source" : "singleplatform",
         "title" : "",
         "items" : [
            25966050
         ],
         "original_width" : 5616,
         "type" : "Product",
         "photo_id" : "5c7613d096d2049807b53022bbc70911b9c0b5e1",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit,w_700,h_400/5c7613d096d2049807b53022bbc70911b9c0b5e1.jpg",
         "original_height" : 3744,
         "main_image" : false,
         "size" : 1005184,
         "location_id" : "sublime-9"
      },
      {
         "main_image" : false,
         "original_height" : 640,
         "size" : 42275,
         "location_id" : "sublime-9",
         "items" : [
            25966192
         ],
         "source" : "singleplatform",
         "title" : "",
         "original_width" : 640,
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit,w_700,h_400/3b4aba876fa518eb385a16f0304fc7d7601b8871.jpg",
         "type" : "Product",
         "photo_id" : "3b4aba876fa518eb385a16f0304fc7d7601b8871"
      },
      {
         "location_id" : "sublime-9",
         "original_height" : 640,
         "main_image" : false,
         "size" : 67751,
         "original_width" : 640,
         "photo_id" : "9116f28f542a0c0137df09279e1ace62223ba0aa",
         "type" : "Product",
         "url" : "http://d3lawkbdj6aabd.cloudfront.net/singleplatform/image/upload/c_fit,w_700,h_400/9116f28f542a0c0137df09279e1ace62223ba0aa.jpg",
         "source" : "singleplatform",
         "title" : "",
         "items" : [
            25966198
         ]
      }
   ],
   "code" : 200
}

Questions & API Support

Please reach out to Sean Marrero with any questions or feedback.

Email: smarrero@singleplatform.com