Overview

Photo upload permits users to upload their own images as part of submitting content allowing them to better express their experiences and assist other customers by showing them products in real-life scenarios.

Photos uploaded to the Bazaarvoice platform must be associated with a piece of primary content. This is accomplished through a two-step process:

1. Photo is uploaded to Bazaarvoice platform using an HTTPS POST request to the API endpoint described at Photo Upload documentation.
   • EX: POST https://[stg.]api.bazaarvoice.com/data/uploadphoto.[FORMAT]
2. Associate successfully uploaded photo with one of the following primary content types during the submission process:
   • Review
   • Question
   • Answer

When an image is uploaded during step one the Bazaarvoice platform will temporarily store the original image as well as create a small version (thumbnail) and an intermediate size version (normal). URLs to the thumbnail and normal versions are returned in response to a successful submission request. By submitting the thumbnail URL during step two the photo is associated with the primary content.

This two step process makes it possible to show users the results of a photo upload before they complete the primary content submission. For example, a reviewer might upload photos while writing a review (step 1), and then see those images in the context of the form before completing the review submission (step 2).

Submission guidelines

Photos submission is subject to the following:

• Must be 10 MB or less
• Image name must be a single word without any spaces or special characters.
• Minimum width and height of uploaded photo (see Appendix below)
• A thumbnail size (see Appendix below)
• A normal size (see Appendix below)
• Upload can be either the image file, or a URL to the image file hosted publicly on the internet (apiversion >= 5.4)
• The following formats are accepted:
  • PNG
  • GIF
  • JPG
  • HEIC
  • TIFF
• Non JPG image will be converted to JPG format
• Image orientation is determined by the Exif orientation tag in the image metadata

Walk-through

The following walk-through uses cURL. Copy/paste the code to your command line with modification as noted to follow along. For details on cURL see The Art Of Scripting HTTP Requests Using Curl.

🚧

Demonstration purposes only. Do not reuse the API passkeys below in your application.

Step 1: Upload photo to Bazaarvoice

Photos can be uploaded using the image file directly or a URL to the image file, in which case Bazaarvoice will request the image.

Image file

Download thumbsup.jpg, switch to that directory, and execute the following cURL command.

curl -L -g -X POST 'https://stg.api.bazaarvoice.com/data/uploadphoto.json?apiversion=5.4&passkey=[PASSKEY]' \
-F 'contenttype="Review"' \
-F 'photo=@"/path/to/file"'

This cURL command transmits the POST body with content type multipart/form-data

Image URL

This option is available using apiversion >= 5.4

curl -L -g -X POST 'https://stg.api.bazaarvoice.com/data/uploadphoto.json?apiversion=5.4&passkey=[PASSKEY]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'contenttype=review' \
-d 'photourl=https%3A%2F%2Fdkv97bqrmxzll.cloudfront.net%2Fimg%2Fconversations-api%2Fthumbsup.jpg'

This cURL command transmits the POST body with content type application/x-www-form-urlencoded

Response

This truncated response to a successful upload shows the URLs to thumbnail and normal size images. See the appendix below for the complete response.

{
    "HasErrors": false,
    ...
    "Photo": {
        "Caption": null,
        "Sizes": {
            "thumbnail": {
                "Url": "https://apitestcustomer.ugc.bazaarvoice.com/bvstaging/5555/ps_amazon_s3_ea85cew8pya54lma81quray0k/photoThumb.jpg",
                "Id": "thumbnail"
            },
            "normal": {
                "Url": "https://apitestcustomer.ugc.bazaarvoice.com/bvstaging/5555/ps_amazon_s3_ea85cew8pya54lma81quray0k/photo.jpg",
                "Id": "normal"
            }
        },
        "SizesOrder": [
            "thumbnail",
            "normal"
        ],
        "Id": "ea85cew8pya54lma81quray0k"
    }
}

Step 2: Associate photo with primary content

Once a photo has been uploaded it can be associated with a piece of primary content. This is accomplished by submitting the thumbnail URL, provided in the response to a successful photo upload, with the primary content.

To execute the following cURL command it may be necessary to modify the UserId or UserNickname parameters.

📘

The following code applies to full submission only. It does not apply to progressive submission.

$ curl -d apiversion=5.4 -d ProductId=photo-upload-tut -d UserId=123456789 -d UserNickname=jsmith
-d passkey=2cpdrhohmgmwfz8vqyo48f52g -d action=submit -d "title=Photo upload tutorial" 
-d "reviewtext=Example of how to submit photos with the conversations api." -d rating=5 
-d photourl_1=https://apitestcustomer.ugc.bazaarvoice.com/bvstaging/5555/ps_amazon_s3_tj6dtn1wcofnde8kg874mb8cz/photoThumb.jpg 
-d "photocaption_1=This caption will be associated with photourl_1"    https://stg.api.bazaarvoice.com/data/submitreview.json

Note: The above cURL command uses the photocaption_1 parameter to associate a caption with photo_1

Appendix

Determining minimum width and height

Minimum width and height of the uploaded photo can vary from client to client and even from API key to API key. To determine the minimums for your application simply make an uploadphoto.json request with an image that is sure to be too small. The Conversation API will respond with an error message indicating the acceptable minimum.

Calculating thumbnail and normal image size

Thumbnail and normal image dimension are calculated by scaling the longest side of the user uploaded image down to a predetermined value, and then scaling the other dimension proportionally.

The following examples assume a user uploaded image is 2000px X 1500px and the predetermined size is 80px (thumbnail) and 333px (normal).

Thumbnail size

80 is 4% of 2000, so the the other side of the thumbnail will be 1500 * 4% = 60

Normal image size

333 is 16.65% of 2000, so the the other side of the thumbnail will be 1500 * 16.65% = 249.75

Response to review after photo upload

Requesting reviews using a filter and returning photos for a particular product

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Filter=HasPhotos:eq:true

Response format

{
  "Limit": 10,
  "Offset": 0,
  "TotalResults": 1,
  "Locale": "en_US",
  "Results": [
    {
      "Id": "123456890",
      "CID": "76769b053-972a-5d88-aa70-f49hs905bbc9",
      "SourceClient": "phototest",
      ...
      Photos": [
        {
          "Sizes": {
            "normal": {
              "Id": "normal",
              "Url": "https://photos-uat-us.bazaarvoice.com/photo/2/cGhvdG86Y29uY2llcmdlYXBpZG9jdW1lbnRhdGlvbg/e8b6c62c-5bd1-5d89-953c-d27ea8236b8c"
            },
            "thumbnail": {
              "Id": "thumbnail",
              "Url": "https://photos-uat-us.bazaarvoice.com/photo/2/cGhvdG86Y29uY2llcmdlYXBpZG9jdW1lbnRhdGlvbg/fede87ed-2ccf-5707-b031-13ce2a99e8b7"
            },
            "large": {
              "Id": "large",
              "Url": "https://photos-uat-us.bazaarvoice.com/photo/2/cGhvdG86Y29uY2llcmdlYXBpZG9jdW1lbnRhdGlvbg/71e67aba-1e7f-56c5-bdaa-2e2897588253"
            }
          },
          "Id": "658862",
          "SizesOrder": [
            "normal",
            "thumbnail",
            "large"
          ],
          "Caption": null
        }
      ],
			"Rating": 4,
      ...
    }
  ],
  "Includes": { },
  "HasErrors": false,
  "Errors": [ ]
}