openapi: 3.0.3

info:
  title: Shopping List API
  description: |-
    The *Shopping List API* provides aggregation of shopping item quantities over one or more ingredient lists, and
    optional referral to external shopping services.

    A `shopping-list` call may be issued on a recipe preparation plan, e.g. for recipes assigned to a meal plan's slots,
    to obtain total shopping quantities for the products involved.  Each recipe may be scaled individually for the
    shopping list by indicating the planned consumption as a number of servings; in the absence of such indication,
    consumption (and therefore preparation) of the complete output of the recipe will be assumed.

  version: 1.0 beta

servers:
  - url: https://api.edamam.com

tags:
  - name: shopping list
    description: Shopping list

paths:
  /api/meal-planner/v1/{app_id}/shopping-list:
    post:
      tags:
        - shopping list
      summary: Create shopping list from total meal quantities
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
        - name: Edamam-Account-User
          in: header
          schema:
            type: string
          description: ID of the account user. Should be used *only* if the account is configured for active user tracking.
        - name: beta
          in: query
          schema:
            type: boolean
          description: Turn on support for beta features
        - name: type
          in: query
          required: true
          explode: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - public
                - edamam-generic
          description: Types of recipes to choose from.
        - name: shopping-cart
          in: query
          required: false
          schema:
            type: boolean
          description: (BETA only) Generate a shopping cart page for the the foods aggregated in the shopping list
      requestBody:
        description: Meal quantities
        content:
          application/json:
            schema:
              properties:
                entries:
                  description: Recipe preparation plan, as product quantity required for each given recipe
                  type: array
                  items:
                    $ref: '#/components/schemas/RecipeEntry'
            examples:
              Recipe preparation plan, by servings:
                $ref: '#/components/examples/Recipe preparation plan, by servings'
              Recipe preparation plan, by total quantity:
                $ref: '#/components/examples/Recipe preparation plan, by total quantity'
      responses:
        200:
          description: Shopping list generated successfully
          content:
            application/json:
              schema:
                properties:
                  entries:
                    description: Aggregated ingredient quantities.
                    type: array
                    items:
                      $ref: '#/components/schemas/ShoppingEntry'
                  _links:
                    description: Links to resources related to the generated shopping list
                    type: object
                    properties:
                      shopping-cart:
                        allOf:
                          - description: (BETA only) Shopping cart link
                          - $ref: '#/components/schemas/LinkEntry'
              examples:
                Shopping list:
                  $ref: '#/components/examples/Shopping list'
        400:
          description: Malformed or invalid request

      security:
        - basic:
            - app_id

components:

  schemas:

    LinkEntry:
      type: object
      required: [href]
      properties:
        title:
          description: Human-readable link title
          type: string
        href:
          description: Target URL
          type: string

    RecipeEntry:
      type: object
      required: [quantity, recipe]
      properties:
        quantity:
          description: >
            Total quantity of the specified recipe's product that will be prepared, in given units of measure (see
            `measure`)
          type: number
        measure:
          description: >
            Unit of measure (URI) for the total quantity; if omitted, the unit is the total quantity of a single
            preparation of the given recipe
          type: string
          enum:
            - "http://www.edamam.com/ontologies/edamam.owl#Measure_serving"
        recipe:
          description: Recipe URI
          type: string

    ShoppingEntry:
      type: object
      properties:
        foodItem:
          description: (DEPRECATED; use Food ID) Food URI
          type: string
        foodId:
          description: Food ID
          type: string
        food:
          description: Food label
          type: string
        quantities:
          description: >
            Total quantity required of the specified food item for fulfillment of the requested quantities for the
            complete recipe preparation plan.  One sub-total is given per each specific shopping measure type.
          type: array
          items:
            type: object
            required: [quantity, measure]
            properties:
              quantity:
                description: Required quantity of the specified units of measure
                type: number
              measure:
                description: Unit of measure (URI)
                type: string
              qualifiers:
                description: Qualifiers applicable to the shopping item, e.g. "large", "small", etc.
                type: array
                items:
                  type: string

  examples:

    Recipe preparation plan, by servings:
      value:
        entries:
          - quantity: 1
            measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_serving"
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_1
          - quantity: 3
            measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_serving"
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_2
          - quantity: 2
            measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_serving"
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_3

    Recipe preparation plan, by total quantity:
      value:
        entries:
          - quantity: 1
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_1
          - quantity: 1
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_2
          - quantity: 2
            recipe: http://www.edamam.com/ontologies/edamam.owl#recipe_3

    Shopping list:
      value:
        entries:
          - foodId: food_abcdefghijklmnoprqstuvwxyzab
            food: ABC
            quantities:
              - quantity: 2
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_unit"
                qualifiers: [ large ]
              - quantity: 5
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_unit"
          - foodId: food_defghijklmnoprqstuvwxyzabcde
            food: DEF
            quantities:
              - quantity: 1500
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_milliliter"
          - foodId: food_ghijklmnoprqstuvwxyzabcdefgh
            food: GHI
            quantities:
              - quantity: 120
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_milliliter"
          - foodId: food_jklmnoprqstuvwxyzabcdefghijk
            food: JKL
            quantities:
              - quantity: 230
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_gram"
          - foodId: food_xyzabcdefghijklmnoprqstuvwxy
            food: XYZ
            quantities:
              - quantity: 300
                measure: "http://www.edamam.com/ontologies/edamam.owl#Measure_gram"

  securitySchemes:
    basic:
      type: http
      scheme: basic
