Skip to main content

​
Endpoint

GET /foods
Search foods in the database with support for text search, FODMAP filtering, category filtering, and pagination.

​
Query Parameters

​
search
string
Text search query to match food names (case-insensitive, partial matching supported)Constraints: 1-100 charactersExample: search=alho matches “Alho”, “Alho-poró”, etc.
​
level
string
Filter by FODMAP levelAllowed values: free, low, medium, high, allExample: level=low returns only low-FODMAP foods
​
category
string
Filter by category level 1 (main category)Constraints: 1-100 charactersExample: category=Frutas
​
category2
string
Filter by category level 2 (subcategory)Constraints: 1-200 charactersExample: category2=Frutas Frescas
​
category3
string
Filter by category level 3 (sub-subcategory)Constraints: 1-200 charactersExample: category3=Frutas Tropicais
​
hasFodmap
string
Filter by whether food has FODMAP informationAllowed values: true, falseExample: hasFodmap=true returns only foods with FODMAP data
​
hasNutrition
string
Filter by whether food has nutritional informationAllowed values: true, falseExample: hasNutrition=true returns only foods with nutrition data
​
source
string
Filter by data sourceConstraints: 1-50 charactersAllowed values: nutritional_table, user_contributed, ai_generated
​
sortBy
string
default:"name"
Field to sort results byAllowed values: name, energy, protein, carbs, fat
​
sortOrder
string
default:"asc"
Sort directionAllowed values: asc, desc
​
page
integer
default:"1"
Page number for paginationConstraints: Must be >= 1
​
limit
integer
default:"50"
Number of results per pageConstraints: 1-100Default: 50

​
Response

​
success
boolean
required
Indicates if the request was successful
​
data
array
required
Array of food objects matching the search criteria
​
id
integer
required
Unique numeric food identifier
​
name
string
required
Food name
​
source
string
required
Data source: nutritional_table, user_contributed, or ai_generated
​
category_level_1
string
required
Main category (e.g., “Frutas”, “Legumes”)
​
category_level_2
string
Subcategory (level 2)
​
category_level_3
string
Sub-subcategory (level 3)
​
image
string
URL to food image (if available)
​
fodmap
object
FODMAP information (if available)
​
level
string
required
FODMAP level: free, low, medium, or high
​
portion_note
string
Portion-specific notes (e.g., “1/2 cup”)
​
additional_notes
string
Additional FODMAP notes
​
search_information
object
required
Details about how FODMAP data was matched
​
match_type
string
required
single_ingredient or multiple_ingredients
​
category
string
FODMAP category (for single ingredient match)
​
name_english
string
English name (for single ingredient match)
​
detected_keyword
string
Keyword that triggered the match
​
nutrition
object
Nutritional information (if available)
​
energy_kcal
number
required
Energy in kilocalories
​
energy_kj
number
required
Energy in kilojoules
​
reference_portion
string
required
Reference portion (typically “100g”)
​
macronutrients
object
required
Macronutrient values
​
protein_g
string
required
Protein in grams
​
carbohydrates_g
string
required
Carbohydrates in grams
​
lipids_g
string
required
Fats (lipids) in grams
​
fiber_g
string
required
Fiber in grams
​
sugars_g
string
required
Sugars in grams
​
salt_g
string
Salt in grams
​
saturated_fatty_acids_g
string
Saturated fatty acids in grams
​
cholesterol_mg
string
Cholesterol in milligrams
​
vitamins
object
Vitamin content (key-value pairs)
​
minerals
object
Mineral content (key-value pairs)
​
searchCount
integer
required
Number of times this food has been searched
​
createdAt
string
required
ISO 8601 timestamp when the food was created
​
updatedAt
string
required
ISO 8601 timestamp when the food was last updated
​
pagination
object
required
Pagination metadata
​
page
integer
required
Current page number
​
limit
integer
required
Items per page
​
total
integer
required
Total number of items matching the query
​
totalPages
integer
required
Total number of pages

​
Examples

​
Search for low-FODMAP fruits

curl "https://api.ceboelha.com/foods?category=Frutas&level=low&page=1&limit=20"

​
Search by name with nutrition filter

curl "https://api.ceboelha.com/foods?search=banana&hasNutrition=true"

​
Get foods sorted by protein content

curl "https://api.ceboelha.com/foods?sortBy=protein&sortOrder=desc&limit=10"

​
Advanced filtering

curl "https://api.ceboelha.com/foods?level=low&hasFodmap=true&hasNutrition=true&sortBy=energy&sortOrder=asc&page=1&limit=50"

​
Response Example

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "id": 1234,
      "name": "Banana",
      "source": "nutritional_table",
      "category_level_1": "Frutas",
      "category_level_2": "Frutas Frescas",
      "category_level_3": "Frutas Tropicais",
      "image": null,
      "fodmap": {
        "level": "low",
        "portion_note": "1 unidade média (100g)",
        "additional_notes": null,
        "search_information": {
          "match_type": "single_ingredient",
          "category": "Fruits",
          "name_english": "Banana",
          "detected_keyword": "banana"
        }
      },
      "nutrition": {
        "energy_kcal": 89,
        "energy_kj": 372,
        "reference_portion": "100g",
        "macronutrients": {
          "protein_g": "1.1",
          "carbohydrates_g": "22.8",
          "lipids_g": "0.3",
          "fiber_g": "2.6",
          "sugars_g": "12.2",
          "salt_g": "0.01",
          "saturated_fatty_acids_g": "0.1",
          "cholesterol_mg": "0"
        },
        "vitamins": {},
        "minerals": {}
      },
      "data_sources": {
        "nutritional_data": "Portuguese Nutrition Table",
        "fodmap_data": "Monash University FODMAP Database"
      },
      "searchCount": 142,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-03-01T14:22:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 245,
    "totalPages": 13
  }
}

​
Notes

  • The search parameter uses case-insensitive partial matching (e.g., “alh” matches “alho”, “alface”)
  • Multiple filters can be combined for precise queries
  • Pagination limit is capped at 100 items per page
  • Foods without FODMAP or nutrition data will have those fields as null
  • Search count is incremented when foods are retrieved by ID (analytics)

Build docs developers (and LLMs) love

Get started for freeTalk to us