openapi: 3.0.0
servers:
  - description: Production server (uses live data)
    url: https://chompthis.com/api/v2
info:
  contact:
    x-twitter: chomp_this_
  description: |
    ## Important
    An **[API key](https://chompthis.com/api/)** is required for access to this API. Get yours at **[https://chompthis.com/api](https://chompthis.com/api/)**.

    ### Getting Started
      * **[Subscribe](https://chompthis.com/api/#pricing)** to the API.
      * Scroll down and click the "**Authorize**" button.
      * Enter your API key into the "**value**" input, click the "**Authorize**" button, then click the "**Close**" button.
      * Scroll down to the section titled "**default**" and click on the API endpoint you wish to use.
      * Click the "**Try it out**" button.
      * Enter the information the endpoint requires.
      * Click the "**Execute**" button.

    ### Example 
      * Branded food response object: **[View example &raquo;](https://raw.githubusercontent.com/chompfoods/examples/master/branded-food-response-object.json)**
      * Ingredient response object: **[View example &raquo;](https://raw.githubusercontent.com/chompfoods/examples/master/ingredient-response-object.json)**
      * Error response object: **[View example &raquo;](https://raw.githubusercontent.com/chompfoods/examples/master/error-response-object.json)**

    ### How Do I Find My API Key?
      * Your API key was sent to the email address you used to create your subscription.
      * You will also find your API key in the **[Client Center](https://chompthis.com/api/manage.php)**.
      * Read **[this article](https://desk.zoho.com/portal/chompthis/kb/articles/how-do-i-find-my-api-key)** for more information.

    ### Helpful Links
      * **Help & Support**
        * [Knowledge Base &raquo;](https://desk.zoho.com/portal/chompthis/kb/chomp)
        * [Support &raquo;](https://chompthis.com/api/ticket-new.php)
        * [Client Center &raquo;](https://chompthis.com/api/manage.php)
      * **Pricing**
        * [Subscription Options &raquo;](https://chompthis.com/api/)
        * [Cost Calculator &raquo;](https://chompthis.com/api/cost-calculator.php)
      * **Guidelines**
        * [Terms & License &raquo;](https://chompthis.com/api/terms.php)
        * [Attribution &raquo;](https://chompthis.com/api/docs/attribution.php)
  title: Chomp Food Database API Documentation
  version: 1.0.0-oas3
  x-apisguru-categories:
    - tools
  x-logo:
    url: https://twitter.com/chomp_this_/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/chompfoods/examples/master/chomp-Chomp-1.0.0-oas3-swagger.json
      version: "3.0"
  x-providerName: chompthis.com
paths:
  /food/branded/barcode.php:
    get:
      description: |
        ## Get data for a branded food using the food's UPC/EAN barcode.

        **Example** 
        > ```https://chompthis.com/api/v2/food/branded/barcode.php?api_key=API_KEY&code=CODE```

        **Tips**
          * Read our **[Knowledge Base article](https://desk.zoho.com/portal/chompthis/kb/articles/im-having-trouble-getting-matches-for-barcodes-what-can-id-do)** for helpful tips and tricks.
      parameters:
        - description: |
            #### UPC/EAN barcode

            **Example**
            > ```&code=0842234000988```
          in: query
          name: code
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/200BrandedResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"
      security:
        - ApiKeyAuth: []
      summary: Get a branded food item using a barcode
  /food/branded/name.php:
    get:
      description: |
        ## Search for branded food items by name.

        **Example**
        > ```https://chompthis.com/api/v2/food/branded/name.php?api_key=API_KEY&name=NAME```

        **Tips**
          * Get started by using our **[food lookup tool](https://chompthis.com/api/lookup.php)**.

        > This API endpoint is only available to Standard and Premium API subscribers. Please consider upgrading your subscription if you are subscribed to the Limited plan. **[Read this](https://desk.zoho.com/portal/chompthis/kb/articles/can-i-upgrade-downgrade-my-subscription)** if you aren't sure how to upgrade your subscription.
      parameters:
        - description: |
            #### Search for branded food items using a general food name keyword. This does not have to exactly match the "official" name for the food.

            **Example**
            > ```&name=Starburst```
          in: query
          name: name
          required: true
          schema:
            type: string
        - description: |
            #### Set maximum number of records you want the API to return. The default value is "**10**."

            **Example**
            > ```&limit=10```
          in: query
          name: limit
          required: false
          schema:
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
            type: integer
        - description: |
            #### This is how you paginate the search result. By default, you will see the first 10 records. You must increment the page number to access the next 10 records, and so on. The default value is "**1**."

            **Example**
            > ```&page=1```
          in: query
          name: page
          required: false
          schema:
            type: integer
      responses:
        "200":
          $ref: "#/components/responses/200BrandedResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"
      security:
        - ApiKeyAuth: []
      summary: Get a branded food item by name
  /food/branded/search.php:
    get:
      description: |
        ## Search for branded food items using various parameters.

        **Example**
        > ```https://chompthis.com/api/v2/food/branded/search.php?api_key=API_KEY&brand=BRAND&country=COUNTRY&page=1```

        **Tips** 
          * Get started by using the **[Query Builder](https://chompthis.com/api/build.php)**.

        > This API endpoint is only available to Standard and Premium API subscribers. Please consider upgrading your subscription if you are subscribed to the Limited plan. **[Read this](https://desk.zoho.com/portal/chompthis/kb/articles/can-i-upgrade-downgrade-my-subscription)** if you aren't sure how to upgrade your subscription.
      parameters:
        - description: |
            #### Filter the search to only include branded foods that contain a specific allergen.

            **Example**
            > ```&allergen=Peanuts```

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: allergen
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that are owned by a specific brand.

            **Example**
            > ```&brand=Starbucks```
          in: query
          name: brand
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods from a specific category.

            **Example**
            > ```&category=Plant Based Foods```
          in: query
          name: category
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that are sold in a specific country.

            **Example**
            > ```&country=United States```

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: country
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that are considered compatible with a specific diet.

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: diet
          required: false
          schema:
            enum:
              - Vegan
              - Vegetarian
              - Gluten Free
            type: string
        - description: |
            #### Filter the search to only include branded foods that contain a specific ingredient.

            **Example**
            > ```&ingredient=Salt```
          in: query
          name: ingredient
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that are associated with a specific keyword.

            **Example**
            > ```&keyword=Organic```

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: keyword
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that contain a specific mineral.

            **Example**
            > ```&mineral=Potassium```
          in: query
          name: mineral
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that contain a specific nutrient.

            **Example**
            > ```&nutrient=Caffeine```

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: nutrient
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that contain a specific ingredient made using palm oil.

            **Example**
            > ```&palm_oil=E160a Beta Carotene```
          in: query
          name: palm_oil
          required: false
          schema:
            type: string
        - description: |
            ### Filter the search to only include branded foods that contain a specific trace ingredient.

            **Example**
            > ```&trace=Tree Nuts```

            **Important Note**: This parameter cannot be used alone. It must be paired with at least 1 additional parameter.
          in: query
          name: trace
          required: false
          schema:
            type: string
        - description: |
            #### Filter the search to only include branded foods that contain a specific vitamin.

            **Example**
            > ```&vitamin=Biotin```
          in: query
          name: vitamin
          required: false
          schema:
            type: string
        - description: |
            #### Set maximum number of records you want the API to return. The default value is "**10**."

            **Example**
            > ```&limit=10```
          in: query
          name: limit
          required: false
          schema:
            enum:
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
            type: integer
        - description: |
            #### This is how you paginate the search result. By default, you will see the first 10 records. You must increment the page number to access the next 10 records, and so on. The default value is "**1**."

            **Example**
            > ```&page=1```
          in: query
          name: page
          required: false
          schema:
            type: integer
      responses:
        "200":
          $ref: "#/components/responses/200BrandedResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"
      security:
        - ApiKeyAuth: []
      summary: Get data for branded food items using various search parameters
  /food/ingredient/search.php:
    get:
      description: |
        ## Get data for a specific ingredient or a specific set of ingredients.

        **Example #1: Single Ingredient**
        > ```https://chompthis.com/api/v2/ingredient/search.php?api_key=API_KEY&find=raw broccoli```

        **Example #2: Set of Ingredients**
        > ```https://chompthis.com/api/v2/ingredient/search.php?api_key=API_KEY&find=raw broccoli,mashed potatoes,chicken drumstick```

        **Tips**
          * Expose ingredient endpoints by using our **[food lookup tool](https://chompthis.com/api/lookup.php)**.

        > This API endpoint is only available to Standard and Premium API subscribers. Please consider upgrading your subscription if you are subscribed to the Limited plan. **[Read this](https://desk.zoho.com/portal/chompthis/kb/articles/can-i-upgrade-downgrade-my-subscription)** if you aren't sure how to upgrade your subscription.
      parameters:
        - description: |
            Search our database for a single ingredient or a specific set of ingredients.

            **Example #1: Single Ingredient**
            > ```&find=raw broccoli```

            **Example #2: Set of Ingredients**
            > ```&find=raw broccoli,buttermilk waffle,mashed potatoes```

            **Important Notes** 
              * Comma-separated lists cannot contain more than **10 ingredients**. You must perform additional API calls if you are looking up more than 10 ingredients.
          in: query
          name: find
          required: true
          schema:
            type: string
        - description: |
            #### Set maximum number of records you want the API to return, per search term. The default value is "**1**."

            **Example**
            > ```&limit=3```
          in: query
          name: limit
          required: false
          schema:
            enum:
              - 1
              - 2
              - 3
            type: integer
      responses:
        "200":
          $ref: "#/components/responses/200IngredientResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"
      security:
        - ApiKeyAuth: []
      summary: Get raw/generic food ingredient item(s)
components:
  responses:
    200BrandedResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BrandedFoodObject"
      description: |
        **Valid** - Will return an object containing any matching foods. 
    200IngredientResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/IngredientObject"
      description: |
        **Valid** - Will return an object containing any matching ingredient foods. 
    400Error:
      description: |
        **Validation error** - Invalid parameters or request.
    401Error:
      description: |
        **Unauthorized** - Invalid API key, unauthorized access, or usage limits exceeded. ***[More information &raquo;](https://desk.zoho.com/portal/chompthis/kb/articles/what-is-a-rate-limit)***
    404Error:
      description: |
        **Not found** - No food items were found.
    500Error:
      description: |
        **Server error** - Internal server error, request failed, or base error. *Please **[contact us](https://chompthis.com/api/ticket-new.php)** if you see this.*
  schemas:
    BrandedFoodObject:
      description: Please read the description of each field in this API response object example. By default, the value of each field is **null**. This indicates an unknown state or that no data exists.
      properties:
        items:
          description: An array containing an object for each individual item returned by your API call.
          items:
            description: An object containing information for this specific item.
            properties:
              allergens:
                description: An array of ingredients in this item that may cause allergic reactions in people
                items:
                  type: string
                type: array
              barcode:
                description: EAN/UPC barcode
                type: string
              brand:
                description: The brand name that owns this item
                type: string
              brand_list:
                description: An array of brands we have associated with this item. Some items are sold by more than 1 brand.
                items:
                  type: string
                type: array
              categories:
                items:
                  description: An array of categories for this item
                  type: string
                type: array
              countries:
                description: An array of countries where this item is sold
                items:
                  type: string
                type: array
              country_details:
                description: An object containing additional information on the countries where this item is found
                properties:
                  english_speaking:
                    description: The number of countries where English is the country's primary language
                    type: integer
                  non_english_speaking:
                    description: The number of countries where English is not the country's primary language
                    type: integer
                type: object
              description:
                description: A description of this item
                type: string
              diet_flags:
                description: An array of ingredient objects that were flagged while grading this item for compatibility with each diet
                items:
                  description: An object containing information on an individual ingredient that was flagged as potentially not being compatible with a certain diet
                  properties:
                    compatibility_description:
                      description: A description of how we graded this ingredient for compatibility with the diet
                      type: string
                    compatibility_level:
                      description: A numeric representation of if we believe this ingredient is compatible with the diet. Higher values indicate more compatibility
                      type: integer
                    diet_label:
                      description: Name of the diet with which this ingredient may not be compatible
                      type: string
                    ingredient:
                      description: Ingredient name
                      type: string
                    ingredient_description:
                      description: Description of the ingredient
                      type: string
                    is_allergen:
                      description: Boolean representing if the ingredient is a known allergen
                      type: boolean
                    is_compatible:
                      description: A description of if we believe this ingredient is compatible with the diet
                      type: string
                  type: object
                type: array
              diet_labels:
                description: An object containing this item's compatibility grades for each supported diet
                properties:
                  gluten_free:
                    description: An object containing information on this item's compatibility with Gluten Free diets
                    properties:
                      compatibility_level:
                        description: Numeric representation of how compatible this item is with this diet. Higher values indicate more compatibility
                        type: integer
                      confidence:
                        description: Boolean that indicates if we are confident in how this item is graded for this diet
                        type: integer
                      confidence_description:
                        description: Description of our confidence that this item was graded correctly
                        type: string
                      is_compatible:
                        description: Boolean describing if this item is compatible with this diet
                        type: boolean
                      name:
                        description: Diet name
                        type: string
                    type: object
                  vegan:
                    description: An object containing information on this item's compatibility with the Vegan diets
                    properties:
                      compatibility_level:
                        description: Numeric representation of how compatible this item is with this diet. Higher values indicate more compatibility
                        type: integer
                      confidence:
                        description: Boolean that indicates if we are confident in how this item is graded for this diet
                        type: integer
                      confidence_description:
                        description: Description of our confidence that this item was graded correctly
                        type: string
                      is_compatible:
                        description: Boolean describing if this item is compatible with this diet
                        type: boolean
                      name:
                        description: Diet name
                        type: string
                    type: object
                  vegetarian:
                    description: An object containing information on this item's compatibility with Vegetarian diets
                    properties:
                      compatibility_level:
                        description: Numeric representation of how compatible this item is with this diet. Higher values indicate more compatibility
                        type: integer
                      confidence:
                        description: Boolean that indicates if we are confident in how this item is graded for this diet
                        type: integer
                      confidence_description:
                        description: Description of our confidence that this item was graded correctly
                        type: string
                      is_compatible:
                        description: Boolean describing if this item is compatible with this diet
                        type: boolean
                      name:
                        description: Diet name
                        type: string
                    type: object
                type: object
              has_english_ingredients:
                description: A boolean indicating if we have English ingredients for this item
                type: boolean
              ingredient_list:
                description: An array of this item's ingredients
                items:
                  type: string
                type: array
              ingredients:
                description: This food item's ingredients from greatest quantity to least
                type: string
              keywords:
                description: An array of keywords that can be used to describe this item
                items:
                  type: string
                type: array
              minerals:
                description: An array of minerals that this item contains
                items:
                  type: string
                type: array
              name:
                description: Item name as provided by brand owner or as shown on packaging
                type: string
              nutrients:
                description: An array containing nutrient informatio objects for this food item
                items:
                  description: An object containing information for a specific nutrient found in this food item
                  properties:
                    data_points:
                      description: Number of observations on which the value is based
                      type: integer
                    description:
                      description: Description of the nutrient source
                      type: string
                    measurement_unit:
                      description: The unit used for the measure of this nutrient
                      type: string
                    name:
                      description: Nutrient name
                      type: string
                    per_100g:
                      description: Amount of the nutrient per 100g of food
                      type: number
                    rank:
                      description: Nutrient rank
                      type: integer
                  type: object
                type: array
              package:
                description: An object containing basic packaging information about this item
                properties:
                  quantity:
                    description: Package quantity
                    type: integer
                  size:
                    description: Package size
                    type: string
                type: object
              packaging_photos:
                description: A object containing a collection of photos of this item's packaging
                properties:
                  front:
                    description: An object containing photos of the front of this item's packaging
                    properties:
                      display:
                        description: Full-sized photo of the front of this item's packaging
                        type: string
                      small:
                        description: Small photo of the front of this item's packaging
                        type: string
                      thumb:
                        description: Thumbnail photo of the front of this item's packaging
                        type: string
                    type: object
                  ingredients:
                    description: An object containing photos of the ingredients on this item's packaging
                    properties:
                      display:
                        description: Full-sized photo of the ingredients on this item's packaging
                        type: string
                      small:
                        description: Small photo of the ingredients on this item's packaging
                        type: string
                      thumb:
                        description: Thumbnail photo of the ingredients on this item's packaging
                        type: string
                    type: object
                  nutrition:
                    description: An object containing photos of this item's nutrition label
                    properties:
                      display:
                        description: Full-sized photo of this item's nutrition label
                        type: string
                      small:
                        description: Small photo of this item's nutrition label
                        type: string
                      thumb:
                        description: Thumbnail photo of this item's nutrition label
                        type: string
                    type: object
                type: object
              palm_oil_ingredients:
                description: An array of ingredients made from palm oil
                items:
                  type: string
                type: array
              serving:
                description: An object containing serving information for this item
                properties:
                  measurement_unit:
                    description: Measurement unit for each serving (e.g. if measure is 3 tsp, the unit is tsp)
                    type: string
                  size:
                    description: Serving size
                    type: string
                  size_fulltext:
                    description: Serving size description
                    type: string
                type: object
              traces:
                description: An array of trace ingredients that may be found in this item
                items:
                  type: string
                type: array
              vitamins:
                description: An array of vitamins that are found in this item
                items:
                  type: string
                type: array
            type: object
          type: array
      type: object
    IngredientObject:
      description: Please read the description of each field in this API response object example. By default, the value of each field is **null**. This indicates an unknown state or that no data exists.
      properties:
        items:
          description: An array containing an object for each individual item returned by your API call.
          items:
            description: An object containing information for this specific item.
            properties:
              calorie_conversion_factor:
                description: An object containing the multiplication factors to be used when calculating energy from macronutrients for a specific food.
                properties:
                  carbohydrate_value:
                    description: The multiplication factor for carbohydrates
                    type: number
                  fat_value:
                    description: The multiplication factor for fat
                    type: number
                  protein_value:
                    description: The multiplication factor for protein
                    type: number
                type: object
              categories:
                items:
                  description: An array of categories for this item
                  type: string
                type: array
              common_name:
                description: Common name associated with this item. These generally clarify what the item is (e.g. when the brand name is "BRAND's Spicy Enchilada" the common name may be "Chicken enchilada")
                type: string
              components:
                description: An array of objects containing the constituent parts of a food (e.g. bone is a component of meat)
                items:
                  description: An object containing information on a specific component of this food item
                  properties:
                    data_points:
                      description: The number of obersvations on which the measure is based
                      type: integer
                    gram_weight:
                      description: The weight of the component in grams
                      type: number
                    is_refuse:
                      description: Whether the component is refuse, i.e. not edible
                      type: boolean
                    name:
                      description: The kind of component, e.g. bone
                      type: string
                    pct_weight:
                      description: The weight of the component as a percentage of the total weight of the food
                      type: number
                  type: object
                type: array
              footnote:
                description: Comments on any unusual aspects of this item. Examples might include unusual aspects of the food overall
                type: string
              name:
                description: Item name as provided by brand owner or as shown on packaging
                type: string
              nutrients:
                description: An array containing nutrient informatio objects for this food item
                items:
                  description: An object containing information for a specific nutrient found in this food item
                  properties:
                    data_points:
                      description: Number of observations on which the value is based
                      type: integer
                    description:
                      description: Description of the nutrient source
                      type: string
                    footnote:
                      description: Comments on any unusual aspect of the food nutrient. Examples might include why a nutrient value is different than typically expected.
                      type: string
                    max:
                      description: Maximum nutrient value
                      type: number
                    measurement_unit:
                      description: The unit used for the measure of this nutrient
                      type: string
                    median:
                      description: Median nutrient value
                      type: number
                    min:
                      description: Minimum nutrient value
                      type: number
                    name:
                      description: Nutrient name
                      type: string
                    per_100g:
                      description: Amount of the nutrient per 100g of food
                      type: number
                    rank:
                      description: Nutrient rank
                      type: integer
                  type: object
                type: array
              portions:
                description: An array of objects containing information on discrete amounts of a food found in this item
                items:
                  description: An object containing information on a specific food portion found in this item
                  properties:
                    data_points:
                      description: The number of observations on which the measure is based
                      type: integer
                    description:
                      description: Comments that provide more specificity on the measure. For example, for a pizza measure the dissemination text might be 1 slice is 1/8th of a 14 inch pizza.
                      type: string
                    footnote:
                      description: Comments on any unusual aspects of the measure. Examples might includes caveats on the usage of a measure, or reasons why a measure gram weight is an unexpected value.
                      type: string
                    gram_weight:
                      description: The weight of the measure in grams
                      type: number
                    measurement_unit:
                      description: The unit used for measure (e.g. if mesure is 3 tsp, the unit is tsp)
                      type: string
                    modifier:
                      description: Qualifier of the measure (e.g. related to food shape or form) (e.g. melted, crushed, diced)
                      type: string
                  type: object
                type: array
              protein_conversion_factor:
                description: The multiplication factor used to calculate protein from nitrogen
                type: number
              score:
                description: A value that represents how similar the name of this food item is to the original search term. The lower the value the closer this item's name is to the original search term.
                type: string
              search_term:
                description: The original search term that found this food item
                type: string
            type: object
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: query
      name: api_key
      type: apiKey
