Photo Upload API

  • 4 minute(s) read
Prev Next

Use this API to submit food & beverage CPG product photos to Nutritionix. For each submission, you will submit the following photos:

  1. Front of Package
  2. Nutrition Facts Panel
  3. Ingredient Statement

Products must be identified in the API request by the UPC as extracted from the barcode on the product packaging.

Resource Information Value
Response Form JSON
Requires Authentication Yes
HTTP Method POST
Host Domain sample: https://photoapi-qa.nutritionix.com
Endpoint /upload

Header

The header of the request contains parameters to authenticate the request. The request is authenticated only if the API authentication is enabled for you.
To authenticate the request, you must pass the “x-app-id” and “x-app-password”. For more information, see Understand Request Headers.

Parameters

No parameters.

Request Body

Field Required? Details
UPC Required string
remoteUserID string
frontOfPackage Required string ($binary); image/png, image/jpeg
nutritionLabel Required string ($binary); image/png, image/jpeg
ingredientStatement string ($binary); image/png, image/jpeg

Schema

image

Response

The response returns in JSON format.
The successful (201) response returns the upload event unique identifier (UUID).

image

Example value:

{
  "uuid": "6a187025-f25d-405f-ac22-3c9499a3e169"
}

Errors

Schema:

image

Error Codes:

statusCode Description Example
400 On request containing no image files; on form validation errors
403 On unauthenticated request {"message": "Forbidden resource", "error":"Forbidden", "statusCode": 403 }
406 If body is not a multipart form {"message": "the request is not multipart", "error": "Not Acceptable", "statusCode": 406 }
413 On image file exceeding file size limit; on too many files { "error": "Payload Too Large", "message": "ingredientStatement is too large. Maximum allowed size is 5242880 bytes", "statusCode": 413 }
415 On an attempt to upload an unsupported file { "error": "Unsupported Media Type", "message": "The asset format webp is not supported", "statusCode": 415 }

User Experience Requirements

UX Requirements for Compliant Photo Upload API Participation:

Scan, Snap, + Submit:

image

  1. The UPC must be obtained systematically through a barcode scanning feature or plug-in.
  2. API request to v2/search/item endpoint (whether a UPC-Lookup request or a fire-and-forget) is required as part of the UX flow.
  3. Do not allow users to select photos from their photo libraries; photos must be taken in real-time as part of the submission experience.

STEP 1: Barcode Scanning UX

  1. Allow the user to search for a CPG food & beverage product by scanning the product’s barcode:

    1. Barcode scanning libraries for iOS/Android:
      1. There are many open-source barcode scanning plugins available, and we have had good experience with these:
        1. https://github.com/phonegap/phonegap-plugin-barcodescanner for Android and iOS.
        2. https://github.com/tjwoon/csZBar for iOS only.
      2. Calculate the check-digit of a barcode to confirm the mobile device read the barcode correctly. You can utilize this script as a starting point. Sometimes in low light situations, or curved packages, the mobile phone will misread the barcode. If the incorrect barcode is sent to Nutritionix, it will incorrectly appear that the product does not exist in the database. In the event of a misread barcode event, we recommend building logic into your app to ask the user to scan the product one more time, or manually enter in the barcode number as a backup.

  2. You will use the UPC value obtained through barcode scanning to determine whether or not to direct the user into the Photo Upload flow.

image

Pro-tips:

a. Product Updates: In addition to having end-users submit photos for new products, there are two easy ways to facilitate photo submissions for keeping products fresh:

#1: Automatically navigate your end-user into the Photo Upload flow if any scanned product has a Last Verified date older than a particular threshold. We recommend a threshold of 6 months, although you may choose a longer timeframe. We do allow anything less than two months.

#2: Allow users to manually enter the Photo Upload flow. This can be achieved by offering a button in an appropriate UI location with calls-to-action such as:

image

REQUIRED: If you allow users to manually engage the Photo Upload flow, users must be brought to the Barcode Scanning step. We require that users start the submission process by scanning the product barcode; do not allow users to manually input a UPC.

b. We recommend making the scanned UPC visible to the user either during the next steps or upon final review for submission.

STEP 2 - 4: Photo Prompts

You must guide your user through the process of taking the following product photos:

  • Front of Package
  • Nutrition Facts Panel
  • Ingredient Statement

Pro-tips:

a. Because the NFP and ingredient statement can be found in variable places on packaging across products, it is important to make sure that users know which view they are intended to capture. We also recommend maintaining a consistent order in which you prompt for each photo type so that the flow feels more intuitive to users with each user of this feature.

b. Choose the prompt experience that is most consistent with your app’s existing UX standards, and when in doubt, always work to reduce the number of clicks required by an end- user to ensure a quick & convenient experience.

c. Only photos of sufficient quality can result in database additions and updates, so allowing your end-user to review the snapped photos prior to submission – as well as making it easy (minimal clicks!) to re-take a photo that missed the mark – is recommended for setting your end-users up for success.