Spoonacular Ingredients API

openapi: 3.0.0
info:
  title: spoonacular Ingredients API
  description: 'The spoonacular Nutrition, Recipe, and Food API allows you to access over thousands of recipes, thousands of ingredients, 800,000 food products, over 100,000 menu items, and restaurants. Our food ontology and semantic recipe search engine makes it possible to search for recipes using natural language queries, such as "gluten free brownies without sugar" or "low fat vegan cupcakes." You can automatically calculate the nutritional information for any recipe, analyze recipe costs, visualize ingredient lists, find recipes for what''s in your fridge, find recipes based on special diets, nutritional requirements, or favorite ingredients, classify recipes into types and cuisines, convert ingredient amounts, or even compute an entire meal plan. With our powerful API, you can create many kinds of food and especially nutrition apps.


    Special diets/dietary requirements currently available include: vegan, vegetarian, pescetarian, gluten free, grain free, dairy free, high protein, whole 30, low sodium, low carb, Paleo, ketogenic, FODMAP, and Primal.'
  contact:
    name: David Urbansky
    email: mail@spoonacular.com
    url: https://spoonacular.com/contact
  version: 2.0.2
  x-codegen-settings:
    Nullify404: false
    GenerateAsyncCode: true
    UseMethodPrefix: true
    UseModelPostfix: false
    UseControllerPrefix: true
    UseEnumPostfix: true
    CollectParameters: false
    UseConstructorsForConfig: true
    UseCommonSDKLibrary: false
    iOSUseAppInfoPlist: true
    AndroidUseAppManifest: true
    BodySerialization: 0
    EnableAdditionalModelProperties: false
    PreserveParameterOrder: false
    AppendContentHeaders: true
    iOSGenerateCoreData: false
    GenerateInterfaces: false
    NodeHttpClient: NODE_REQUEST
    ValidateRequiredParameters: false
    JavaUsePropertiesConfig: false
    Timeout: 0
    StoreTimezoneInformation: false
    EnablePHPComposerVersionString: false
    EnableLogging: false
    ArraySerialization: Indexed
    ModelSerializationScheme: Json
    UseExceptionPrefix: true
    RunscopeEnabled: false
    JavaHttpClient: JAVA_OK
    ParameterArrayFormat: ParamArrayWithIndex
    SecurityProtocols:
    - Ssl3
    - Tls
    GenerateTravisConfig: false
    GenerateCircleConfig: false
    GenerateAppveyorConfig: false
    GenerateJenkinsConfig: false
    EnableHttpCache: false
    Retries: 0
    RetryInterval: 1
    GenerateAdvancedDocs: false
    UnderscoreNumbers: true
    UseSingletonPattern: true
    DisableLinting: false
    ApplyCustomizations: []
    SortResources: false
    AllowSkippingSSLCertVerification: false
    DoNotSplitWords: []
    EnableGlobalUserAgent: true
    ReturnCompleteHttpResponse: false
    GenerateModels: true
    GenerateExceptions: true
    IgnoreIfNullJson: false
    DisableDocs: false
    LiftParameterDescriptionFromCustomType: false
    ThrowForHttpErrorStatusCodes: true
    ResponseMapping:
      Type: Simple
    ForceKeywordArgsInRuby: false
    SymbolizeHashKeysInRuby: false
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
    - name: production
      servers:
      - name: default
        url: https://api.spoonacular.com
    parameters: []
  license:
    name: spoonacular API Terms
    url: https://spoonacular.com/food-api/terms
  termsOfService: https://spoonacular.com/food-api/terms
  x-apis-json-aid: spoonacular
  x-spec-source: https://github.com/ddsky/spoonacular-api-clients/blob/master/spoonacular-openapi-3.json
  x-last-validated: '2026-06-03'
  x-providerName: spoonacular.com
servers:
- url: https://api.spoonacular.com
  variables: {}
security:
- apiKeyScheme: []
tags:
- name: Ingredients
paths:
  /recipes/{id}/ingredientWidget.png:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            image/png:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: id
        description: The recipe id.
        schema:
          type: integer
          example: 1082038
        required: true
        style: simple
        explode: false
        in: path
        example: 1082038
      - name: measure
        description: Whether the the measures should be 'us' or 'metric'.
        schema:
          type: string
          example: metric
          enum:
          - us
          - metric
        required: false
        style: form
        explode: false
        in: query
        example: metric
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Ingredients-by-ID-Image
      summary: Ingredients by ID Image
      description: Visualize a recipe's ingredient list.
      operationId: ingredientsByIDImage
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /recipes/visualizeIngredients:
    post:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            text/html:
              schema:
                type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - ingredientList
              - servings
              properties:
                ingredientList:
                  type: string
                  description: The ingredient list of the recipe, one ingredient per line (separate lines with \n).
                servings:
                  type: number
                  description: The number of servings.
                measure:
                  type: string
                  enum:
                  - us
                  - metric
                  description: The original system of measurement, either 'metric' or 'us'.
                view:
                  type: string
                  enum:
                  - grid
                  - list
                  description: How to visualize the ingredients, either 'grid' or 'list'.
                defaultCss:
                  type: boolean
                  description: Whether the default CSS should be added to the response.
                showBacklink:
                  type: boolean
                  description: Whether to show a backlink to spoonacular. If set false, this call counts against your quota.
            example:
              ingredientList: 3 oz flour
              servings: 2
      parameters:
      - $ref: '#/components/parameters/language'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Ingredients-Widget
      summary: Ingredients Widget
      description: Visualize ingredients of a recipe. You can play around with that endpoint!
      operationId: visualizeIngredients
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/{id}/information:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngredientInformation'
              examples:
                GetIngredientInformation200Example:
                  summary: Default getIngredientInformation 200 response
                  x-microcks-default: true
                  value:
                    id: 9266
                    original: pineapples
                    originalName: pineapples
                    name: pineapples
                    amount: 1
                    unit: ''
                    unitShort: ''
                    unitLong: ''
                    possibleUnits:
                    - piece
                    - slice
                    - fruit
                    - g
                    - oz
                    - cup
                    - serving
                    estimatedCost:
                      value: 299
                      unit: US Cents
                    consistency: solid
                    shoppingListUnits:
                    - pieces
                    aisle: Produce
                    image: pineapple.jpg
                    meta: []
                    nutrition:
                      nutrients:
                      - name: Calories
                        amount: 452.5
                        unit: cal
                        percentOfDailyNeeds: 22.63
                      - name: Fat
                        amount: 1.09
                        unit: g
                        percentOfDailyNeeds: 1.67
                      - name: Saturated Fat
                        amount: 0.08
                        unit: g
                        percentOfDailyNeeds: 0.51
                      - name: Carbohydrates
                        amount: 118.74
                        unit: g
                        percentOfDailyNeeds: 39.58
                      - name: Net Carbohydrates
                        amount: 106.07
                        unit: g
                        percentOfDailyNeeds: 38.57
                      - name: Sugar
                        amount: 89.14
                        unit: g
                        percentOfDailyNeeds: 99.05
                      - name: Cholesterol
                        amount: 0
                        unit: mg
                        percentOfDailyNeeds: 0
                      - name: Sodium
                        amount: 9.05
                        unit: mg
                        percentOfDailyNeeds: 0.39
                      - name: Protein
                        amount: 4.89
                        unit: g
                        percentOfDailyNeeds: 9.77
                      - name: Vitamin C
                        amount: 432.59
                        unit: mg
                        percentOfDailyNeeds: 524.35
                      - name: Manganese
                        amount: 8.39
                        unit: mg
                        percentOfDailyNeeds: 419.47
                      - name: Fiber
                        amount: 12.67
                        unit: g
                        percentOfDailyNeeds: 50.68
                      - name: Vitamin B6
                        amount: 1.01
                        unit: mg
                        percentOfDailyNeeds: 50.68
                      - name: Copper
                        amount: 1
                        unit: mg
                        percentOfDailyNeeds: 49.78
                      - name: Vitamin B1
                        amount: 0.72
                        unit: mg
                        percentOfDailyNeeds: 47.66
                      - name: Folate
                        amount: 162.9
                        unit: µg
                        percentOfDailyNeeds: 40.73
                      - name: Potassium
                        amount: 986.45
                        unit: mg
                        percentOfDailyNeeds: 28.18
                      - name: Magnesium
                        amount: 108.6
                        unit: mg
                        percentOfDailyNeeds: 27.15
                      - name: Vitamin B3
                        amount: 4.53
                        unit: mg
                        percentOfDailyNeeds: 22.63
                      - name: Vitamin B5
                        amount: 1.93
                        unit: mg
                        percentOfDailyNeeds: 19.28
                      - name: Vitamin B2
                        amount: 0.29
                        unit: mg
                        percentOfDailyNeeds: 17.04
                      - name: Iron
                        amount: 2.62
                        unit: mg
                        percentOfDailyNeeds: 14.58
                      - name: Calcium
                        amount: 117.65
                        unit: mg
                        percentOfDailyNeeds: 11.77
                      - name: Vitamin A
                        amount: 524.9
                        unit: IU
                        percentOfDailyNeeds: 10.5
                      - name: Zinc
                        amount: 1.09
                        unit: mg
                        percentOfDailyNeeds: 7.24
                      - name: Phosphorus
                        amount: 72.4
                        unit: mg
                        percentOfDailyNeeds: 7.24
                      - name: Vitamin K
                        amount: 6.34
                        unit: µg
                        percentOfDailyNeeds: 6.03
                      - name: Selenium
                        amount: 0.91
                        unit: µg
                        percentOfDailyNeeds: 1.29
                      - name: Vitamin E
                        amount: 0.18
                        unit: mg
                        percentOfDailyNeeds: 1.21
                      properties:
                      - name: Glycemic Index
                        amount: 58.67
                        unit: ''
                      - name: Glycemic Load
                        amount: 62.23
                        unit: ''
                      caloricBreakdown:
                        percentProtein: 3.88
                        percentFat: 1.94
                        percentCarbs: 94.18
                      weightPerServing:
                        amount: 905
                        unit: g
                    categoryPath:
                    - tropical fruit
                    - fruit
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: id
        description: The ingredient id.
        schema:
          type: integer
          example: 9266
        required: true
        style: simple
        explode: false
        in: path
        example: 9266
      - name: amount
        description: The amount of this ingredient.
        schema:
          type: number
          example: 150
        required: false
        style: form
        explode: false
        in: query
        example: 150
      - name: unit
        description: The unit for the given amount.
        schema:
          type: string
          example: grams
        required: false
        style: form
        explode: false
        in: query
        example: grams
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Get-Ingredient-Information
      summary: Get Ingredient Information
      description: Use an ingredient id to get all available information about an ingredient, such as its image and supermarket aisle.
      operationId: getIngredientInformation
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/{id}/amount:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  amount:
                    type: number
                  unit:
                    type: string
                    minLength: 1
                required:
                - amount
                - unit
              examples:
                example-1:
                  value:
                    amount: 65.32
                    unit: oz
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: id
        description: The id of the ingredient you want the amount for.
        schema:
          type: integer
          example: 9266
        required: true
        style: simple
        explode: false
        in: path
        example: 9266
      - name: nutrient
        description: The target nutrient. See a list of supported nutrients.
        schema:
          type: string
          example: protein
        required: true
        style: form
        explode: false
        in: query
        example: protein
      - name: target
        description: The target number of the given nutrient.
        schema:
          type: integer
          example: 2
        required: true
        style: form
        explode: false
        in: query
        example: 2
      - name: unit
        description: The target unit.
        schema:
          type: string
          example: oz
        required: false
        style: form
        explode: false
        in: query
        example: oz
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Compute-Ingredient-Amount
      summary: Compute Ingredient Amount
      description: Compute the amount you need of a certain ingredient for a certain nutritional goal. For example, how much pineapple do you have to eat to get 10 grams of protein?
      operationId: computeIngredientAmount
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/autocomplete:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                type: array
                description: ''
                minItems: 0
                uniqueItems: true
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                    image:
                      type: string
                      minLength: 1
                    id:
                      type: integer
                    aisle:
                      type: string
                      minLength: 1
                    possibleUnits:
                      type: array
                      items:
                        type: string
                  required:
                  - name
                  - image
              examples:
                example-1:
                  value:
                  - name: apple
                    image: apple.jpg
                    id: 9003
                    aisle: Produce
                    possibleUnits:
                    - small
                    - large
                    - piece
                    - slice
                    - g
                    - extra small
                    - medium
                    - oz
                    - cup slice
                    - cup
                    - serving
                  - name: applesauce
                    image: applesauce.png
                    id: 9019
                    aisle: Canned and Jarred
                    possibleUnits:
                    - g
                    - oz
                    - cup
                    - serving
                    - tablespoon
                  - name: apple juice
                    image: apple-juice.jpg
                    id: 9016
                    aisle: Beverages
                    possibleUnits:
                    - g
                    - drink box
                    - fl oz
                    - oz
                    - teaspoon
                    - cup
                    - serving
                    - tablespoon
                  - name: apple cider
                    image: apple-cider.jpg
                    id: 1009016
                    aisle: Beverages
                    possibleUnits:
                    - g
                    - drink box
                    - fl oz
                    - oz
                    - teaspoon
                    - bottle NFS
                    - cup
                    - serving
                    - tablespoon
                  - name: apple jelly
                    image: apple-jelly.jpg
                    id: 10019297
                    aisle: Nut butters, Jams, and Honey
                    possibleUnits:
                    - g
                    - oz
                    - packet
                    - teaspoon
                    - cup
                    - serving
                    - tablespoon
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - $ref: '#/components/parameters/query'
        example: example
      - $ref: '#/components/parameters/number'
        example: example
      - name: metaInformation
        description: Whether to return more meta information about the ingredients.
        schema:
          type: boolean
          example: false
        required: false
        style: form
        explode: false
        in: query
        example: false
      - name: intolerances
        description: A comma-separated list of intolerances. All recipes returned must not contain ingredients that are not suitable for people with the intolerances entered. See a full list of supported intolerances.
        schema:
          type: string
          example: egg
        required: false
        style: form
        explode: false
        in: query
        example: egg
      - $ref: '#/components/parameters/language'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Autocomplete-Ingredient-Search
      summary: Autocomplete Ingredient Search
      description: Autocomplete the entry of an ingredient.
      operationId: autocompleteIngredientSearch
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/search:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 0
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                          minLength: 1
                        image:
                          type: string
                          minLength: 1
                      required:
                      - id
                      - name
                      - image
                  offset:
                    type: integer
                  number:
                    type: integer
                  totalResults:
                    type: integer
                required:
                - results
                - offset
                - number
                - totalResults
              examples:
                example-1:
                  value:
                    results:
                    - id: 19400
                      name: banana chips
                      image: banana-chips.jpg
                    - id: 93779
                      name: banana liqueur
                      image: limoncello.jpg
                    offset: 0
                    number: 2
                    totalResults: 13
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - $ref: '#/components/parameters/query'
        example: example
      - name: addChildren
        description: Whether to add children of found foods.
        schema:
          type: boolean
          example: true
        required: false
        style: form
        explode: false
        in: query
        example: true
      - name: minProteinPercent
        description: The minimum percentage of protein the food must have (between 0 and 100).
        schema:
          type: number
          example: 10
        required: false
        style: form
        explode: false
        in: query
        example: 10
      - name: maxProteinPercent
        description: The maximum percentage of protein the food can have (between 0 and 100).
        schema:
          type: number
          example: 90
        required: false
        style: form
        explode: false
        in: query
        example: 90
      - name: minFatPercent
        description: The minimum percentage of fat the food must have (between 0 and 100).
        schema:
          type: number
          example: 10
        required: false
        style: form
        explode: false
        in: query
        example: 10
      - name: maxFatPercent
        description: The maximum percentage of fat the food can have (between 0 and 100).
        schema:
          type: number
          example: 90
        required: false
        style: form
        explode: false
        in: query
        example: 90
      - name: minCarbsPercent
        description: The minimum percentage of carbs the food must have (between 0 and 100).
        schema:
          type: number
          example: 10
        required: false
        style: form
        explode: false
        in: query
        example: 10
      - name: maxCarbsPercent
        description: The maximum percentage of carbs the food can have (between 0 and 100).
        schema:
          type: number
          example: 90
        required: false
        style: form
        explode: false
        in: query
        example: 90
      - name: metaInformation
        description: Whether to return more meta information about the ingredients.
        schema:
          type: boolean
          example: false
        required: false
        style: form
        explode: false
        in: query
        example: false
      - name: intolerances
        description: A comma-separated list of intolerances. All recipes returned must not contain ingredients that are not suitable for people with the intolerances entered. See a full list of supported intolerances.
        schema:
          type: string
          example: egg
        required: false
        style: form
        explode: false
        in: query
        example: egg
      - name: sort
        description: The strategy to sort recipes by. See a full list of supported sorting options.
        schema:
          type: string
          example: calories
        required: false
        style: form
        explode: false
        in: query
        example: calories
      - name: sortDirection
        description: The direction in which to sort. Must be either 'asc' (ascending) or 'desc' (descending).
        schema:
          type: string
          example: asc
        required: false
        style: form
        explode: false
        in: query
        example: asc
      - $ref: '#/components/parameters/offset'
        example: example
      - $ref: '#/components/parameters/number'
        example: example
      - $ref: '#/components/parameters/language'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Ingredient-Search
      summary: Ingredient Search
      description: Search for simple whole foods (e.g. fruits, vegetables, nuts, grains, meat, fish, dairy etc.).
      operationId: ingredientSearch
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/substitutes:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  ingredient:
                    type: string
                    minLength: 1
                  substitutes:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
                    minLength: 1
                required:
                - ingredient
                - substitutes
                - message
              examples:
                example-1:
                  value:
                    ingredient: butter
                    substitutes:
                    - 1 cup = 7/8 cup shortening and 1/2 tsp salt
                    - 1 cup = 7/8 cup vegetable oil + 1/2 tsp salt
                    - 1/2 cup = 1/4 cup buttermilk + 1/4 cup unsweetened applesauce
                    - 1 cup = 1 cup margarine
                    message: Found 4 substitutes for the ingredient.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: ingredientName
        description: The name of the ingredient you want to replace.
        schema:
          type: string
          example: butter
        required: true
        style: form
        explode: false
        in: query
        example: butter
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Get-Ingredient-Substitutes
      summary: Get Ingredient Substitutes
      description: Search for substitutes for a given ingredient.
      operationId: getIngredientSubstitutes
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/{id}/substitutes:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  ingredient:
                    type: string
                    minLength: 1
                  substitutes:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
                    minLength: 1
                required:
                - ingredient
                - substitutes
                - message
              examples:
                example-1:
                  value:
                    ingredient: butter
                    substitutes:
                    - 1 cup = 7/8 cup shortening and 1/2 tsp salt
                    - 1 cup = 7/8 cup vegetable oil + 1/2 tsp salt
                    - 1/2 cup = 1/4 cup buttermilk + 1/4 cup unsweetened applesauce
                    - 1 cup = 1 cup margarine
                    message: Found 4 substitutes for the ingredient.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: id
        description: The id of the ingredient you want substitutes for.
        schema:
          type: integer
          example: 1001
        required: true
        style: simple
        explode: false
        in: path
        example: 1001
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Get-Ingredient-Substitutes-by-ID
      summary: Get Ingredient Substitutes by ID
      description: Search for substitutes for a given ingredient.
      operationId: getIngredientSubstitutesByID
      deprecated: false
      tags:
      - Ingredients
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /food/ingredients/map:
    post:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                type: array
                description: ''
                minItems: 0
                uniqueItems: true
                items:
                  type: object
                  propertie

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spoonacular/refs/heads/main/openapi/spoonacular-ingredients-api-openapi.yml