Photo Upload
This tutorial covers how to perform photo uploads using the Bazaarvoice Conversations API. Readers will learn about the photo upload process and walk-through the steps involved in performing a photo upload.
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:
- 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]
- EX: POST
- 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 -F [email protected] -F apiversion=5.4 -F contenttype=Review -F passkey=2cpdrhohmgmwfz8vqyo48f52g
https://stg.api.bazaarvoice.com/data/uploadphoto.json
This cURL command transmits the POST body with content type multipart/form-data
Image URL
This option is available using apiversion >= 5.4
$ curl --data "apiversion=5.4&contenttype=review&passkey=2cpdrhohmgmwfz8vqyo48f52g&photourl=https://dkv97bqrmxzll.cloudfront.net/img/conversations-api/thumbsup.jpg"
https://stg.api.bazaarvoice.com/data/uploadphoto.json
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
Uploaded image | 2000px X 1500px |
Predetermined Size | 80px |
Resulting Dimensions | 80px X 60px |
80 is 4% of 2000, so the the other side of the thumbnail will be 1500 * 4% = 60
Normal image size
Uploaded image | 2000px X 1500px |
Predetermined Size | 333px |
Resulting Dimensions | 333px X 250px |
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": [ ]
}
Updated about 2 months ago