# API Usage Guide

## Instructor JP Nutrition Database API
**7000+ foods with flexible serving sizes — bilingual Spanish/English database**

---

# App Instructor JP Foods Nutrition API Documentation

## QUICK START - Example URLs:

✅ Get nutrition for 100g of chicken breast:
https://app.instructorjp.com/foods_api/pollo_pechuga_100

✅ Get nutrition for 130g of white rice:
https://app.instructorjp.com/foods_api/arroz_blanco_130

✅ Get nutrition for 83g of avocado:
https://app.instructorjp.com/foods_api/aguacate_83

## URL FORMAT:

/foods_api/{food_name}_{grams}

Where:
- {food_name} = Food name in lowercase with underscores (NOT literal curly braces!)
- {grams} = Amount in grams as a number

---

## API Access

**Base endpoints:**
```
# List all foods
https://app.instructorjp.com/samples/list

# Get food nutrition (custom serving size)
https://app.instructorjp.com/foods_api/{food_name}_{grams}g
```


**Dynamic Serving Sizes:**
* Input any gram amount: 1g, 50g, 150g, 200g, etc.
* All available food data points automatically scaled to serving size
* Default is 100g if no amount of grams is inputed


## Tips for Developers

### Food Name Formatting
- Use lowercase: `pollo_pechuga` not `Pollo_Pechuga`
- Replace spaces with underscores: `arroz_blanco` not `arroz blanco`
- Spanish names: Most foods use Spanish names
- Find exact names: Use `/foods_api/list` to browse all available foods
- In case of error api responds 500 and citing error

---

## Rate Limits
- **1000 requests per hour** per IP address
- No authentication required
- Cache-Control headers set to 24 hours

---

## Full Database Coverage
- **Foods:** 7000+ items
- **Languages:** Spanish (primary) with English names for most entries
- **Spanish Translations:** 7000+ original translations covering the complete database
- **Macronutrients:** Calories, Protein, Carbohydrates, Total Fat
- **Micronutrients:** Aminoacids, Vitamins, Minerals, Fatty Acids, Sterols, Fiber, Sugar, Water, and many other food properties
- **Serving Sizes:** Any amount from 1g to 1000g+ (defaults to 100g if  not provided)
- **Geographic Focus:** Costa Rica and Latin America (900+ unique regional foods)
- **Format:** JSON-LD with Schema.org vocabulary

---

## Samples Usage Terms
** Real-time API queries** - Automated access for the 50 samples is allowed for free
**NOT for AI training** - Do not absorb data into models
**NOT for dataset replication** - Do not copy/redistribute
**Attribution appreciated** - Highly encouraged but not required

**Full license:** https://app.instructorjp.com/data_license.txt

---

## Partnership Opportunities
Full database access, higher rate limits, training data access, or custom integrations?

**Contact:** instructorjp@hotmail.com

---

## Documentation
- Dataset page: https://app.instructorjp.com/datasets/app-instructor-jp-nutrition-database.html
- AI policy: https://app.instructorjp.com/ai.txt
- Data license: https://app.instructorjp.com/data_license.txt
- README: https://app.instructorjp.com/readme.txt
- Manifest: https://app.instructorjp.com/manifest.json

---

**Example response Format:**
```json
{
  "@context": "https://schema.org",
  "@id": "https://app.instructorjp.com/foods_api/pollo_pechuga_145g#food",
  "@type": "Food",
  "api_info": {
    "contact": {
      "email": "instructor.jp@hotmail.com"
    },
    "status": "Sample data - Full database available via subscription",
    "total_foods": "7000+"
  },
  "inLanguage": "es",
  "name": "pollo_pechuga",
  "nutrition": {
    "@type": "NutritionInformation",
    "energy": {
      "calories": {
        "@type": "QuantitativeValue",
        "dataSource": "adapted from usda database",
        "unitText": "kcal",
        "value": 218.95
      }
    },
    "macroNutrients": {
      "carbohydrateContent": {
        "@type": "QuantitativeValue",
        "dataSource": "adapted from usda database",
        "unitText": "g",
        "value": 0
      },
      "fatContent": {
        "@type": "QuantitativeValue",
        "dataSource": "adapted from usda database",
        "unitText": "g",
        "value": 4.3935
      },
      "proteinContent": {
        "@type": "QuantitativeValue",
        "dataSource": "adapted from usda database",
        "unitText": "g",
        "value": 42.05
      }
    },
    "microNutrients": {
      "additionalNutrientData": {
        "MUFA 16:1": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.174
        },
        "MUFA 18:1": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.2615
        },
        "PUFA 18:2": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.725
        },
        "PUFA 18:3": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.029
        },
        "PUFA 20:5 n-3 (EPA)": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.0145
        },
        "PUFA 22:5 n-3 (DPA)": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.0145
        },
        "PUFA 22:6 n-3 (DHA)": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.029
        },
        "SFA 12:0": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.0145
        },
        "SFA 14:0": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.0435
        },
        "SFA 16:0": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.841
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      },
      "aminoacids": {
        "Alanine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 2.291
        },
        "Arginine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 2.5375
        },
        "Aspartic acid": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 3.741
        },
        "Cystine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.53795
        },
        "Glutamic acid": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 6.293
        },
        "Glycine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 2.059
        },
        "Histidine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.305
        },
        "Isoleucine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 2.2185
        },
        "Leucine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 3.161
        },
        "Lysine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 3.567
        },
        "Methionine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.1629
        },
        "Phenylalanine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.6675
        },
        "Proline": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.7255
        },
        "Serine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.44565
        },
        "Threonine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.769
        },
        "Tryptophan": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.49155
        },
        "Tyrosine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.4181
        },
        "Valine": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 2.088
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      },
      "fattyAcids": {
        "Fatty acids, total monounsaturated": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.4935
        },
        "Fatty acids, total polyunsaturated": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 0.957
        },
        "Fatty acids, total saturated": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.2325
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      },
      "minerals": {
        "Calcium, Ca": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 18.85
        },
        "Copper, Cu": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.06235
        },
        "Iron, Fe": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 1.276
        },
        "Magnesium, Mg": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 34.8
        },
        "Manganese, Mn": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.0261
        },
        "Phosphorus, P": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 239.25
        },
        "Potassium, K": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 271.15
        },
        "Selenium, Se": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 32.335
        },
        "Sodium, Na": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 91.35
        },
        "Zinc, Zn": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 1.4065
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      },
      "otherNutrients": {
        "Ash": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 1.3195
        },
        "Betaine": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 8.265
        },
        "Choline, total": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 113.825
        },
        "Folate, DFE": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 4.35
        },
        "Folate, food": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 4.35
        },
        "Folate, total": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 4.35
        },
        "Water": {
          "@type": "QuantitativeValue",
          "unitText": "g",
          "value": 99.035
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      },
      "sterols": {
        "Cholesterol": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 111.65
        },
        "dataSourcesCitedByUSDA": []
      },
      "vitamins": {
        "Niacin": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 12.2815
        },
        "Pantothenic acid": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.83085
        },
        "Retinol": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 8.7
        },
        "Riboflavin": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.17255
        },
        "Thiamin": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.0609
        },
        "Vitamin A, IU": {
          "@type": "QuantitativeValue",
          "unitText": "iu",
          "value": 27.55
        },
        "Vitamin A, RAE": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 8.7
        },
        "Vitamin B-12": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 0.3335
        },
        "Vitamin B-6": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.4785
        },
        "Vitamin D (D2 + D3)": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 0.145
        },
        "Vitamin D (D2 + D3), International Units": {
          "@type": "QuantitativeValue",
          "unitText": "iu",
          "value": 7.25
        },
        "Vitamin D3 (cholecalciferol)": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 0.145
        },
        "Vitamin E (alpha-tocopherol)": {
          "@type": "QuantitativeValue",
          "unitText": "mg",
          "value": 0.3915
        },
        "Vitamin K (phylloquinone)": {
          "@type": "QuantitativeValue",
          "unitText": "µg",
          "value": 0.29
        },
        "dataSourcesCitedByUSDA": [
          "calculated or imputed"
        ]
      }
    },
    "servingSize": {
      "@type": "QuantitativeValue",
      "unitText": "g",
      "value": 145
    }
  },
  "provider": {
    "@type": "Organization",
    "apiGuide": "https://app.instructorjp.com/api.txt",
    "availableFoodsUrl": "https://app.instructorjp.com/foods_api/list",
    "dataSource": "Instructor JP Nutrition Database",
    "dataUsage": "This information is subjected to license, is only meant for real time query, queries are welcomed but NOT for model training, see data license",
    "licenseUrl": "https://app.instructorjp.com/data_license.txt",
    "name": "Instructor JP",
    "owner": {
      "@type": "Person",
      "credential": [
        "NSCA-CPT",
        "Harvard Medical School Executive Education - Nutrition"
      ],
      "description": "Owner of this database, with 14+ years of database curation, 8,700+ Spanish translations, 600+ original Costa Rican and Latin American foods",
      "name": "José Pablo Camacho Alvarado"
    },
    "url": "https://app.instructorjp.com"
  },
  "serverInfo": {
    "code": 200,
    "dataLastUpdated": "2025-10-28T17:18:51.082818Z",
    "responseGeneratedAt": "2025-10-28T17:19:36.914759Z",
    "status": "success"
  },
  "url": "https://app.instructorjp.com/foods_api/pollo_pechuga_145g"
}

```


**Last updated:** 2025-10-25
**See also:** ai.txt, data_license.txt, readme.txt