TheCocktailDB APIthecocktaildb.com ↗
Search cocktail recipes, filter by ingredient, category, or glass type, and look up ingredient details via TheCocktailDB API. 14 endpoints.
What is the TheCocktailDB API?
This API provides access to TheCocktailDB's cocktail database across 14 endpoints, covering recipe search, ingredient lookup, and filtering by category, glass type, or alcoholic classification. Endpoints like search_cocktails_by_name return up to 15 ingredient-measure pairs per drink alongside instructions, thumbnail URLs, and multi-language fields, while get_random_cocktail delivers a complete drink record with no parameters required.
curl -X GET 'https://api.parse.bot/scraper/94946c3a-8738-4b0d-b40e-96546f096c53/search_cocktails_by_name?name=Margarita' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace thecocktaildb-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.thecocktaildb_api import CocktailDB, AlcoholicFilter_
db = CocktailDB()
# Search cocktails by name
for cocktail in db.cocktails.search(name="Margarita"):
print(cocktail.name, cocktail.category, cocktail.glass)
# Filter by alcoholic classification using enum
for summary in db.cocktails.by_alcoholic(alcoholic=AlcoholicFilter_.NON_ALCOHOLIC):
print(summary.name, summary.id)
# Get full details from a summary
summaries = list(db.cocktails.by_ingredient(ingredient="Gin", limit=3))
for s in summaries:
for full in s.details():
print(full.name, full.instructions, full.ingredient1)
# List categories
for cat in db.categories.list():
print(cat.name)
# Search ingredients
for ing in db.ingredients.search(name="Vodka"):
print(ing.name, ing.abv, ing.alcohol)
Search for cocktails by name or partial name. Returns full cocktail details including instructions, ingredients (strIngredient1–15), measures (strMeasure1–15), category, glass type, and thumbnail URL for all matching cocktails. An unmatched query returns an empty results array.
| Param | Type | Description |
|---|---|---|
| namerequired | string | Cocktail name or partial name to search for. |
{
"type": "object",
"fields": {
"total": "integer — number of matching cocktails",
"results": "array of cocktail objects with full details"
},
"sample": {
"data": {
"total": 6,
"results": [
{
"idDrink": "11007",
"strDrink": "Margarita",
"strGlass": "Cocktail glass",
"strCategory": "Ordinary Drink",
"strMeasure1": "1 1/2 oz ",
"strMeasure2": "1/2 oz ",
"strMeasure3": "1 oz ",
"dateModified": "2015-08-18 14:42:59",
"strAlcoholic": "Alcoholic",
"strDrinkThumb": "https://www.thecocktaildb.com/images/media/drink/5noda61589575158.jpg",
"strIngredient1": "Tequila",
"strIngredient2": "Triple sec",
"strIngredient3": "Lime juice",
"strInstructions": "Rub the rim of the glass with the lime slice..."
}
]
},
"status": "success"
}
}About the TheCocktailDB API
Searching and Looking Up Cocktails
The search_cocktails_by_name endpoint accepts a full or partial cocktail name and returns an array of matching cocktail objects. Each object includes up to 15 ingredient slots (strIngredient1–strIngredient15) with corresponding measure fields (strMeasure1–strMeasure15), preparation instructions, glass type, drink category, a thumbnail URL, tags, and a modification date. search_cocktails_by_first_letter works the same way but matches on the first character of the cocktail name, useful for building alphabetical indexes. For direct access, lookup_cocktail_by_id fetches a single cocktail by its numeric idDrink and includes instructions in multiple languages when available.
Filtering and Discovery
Four filter endpoints return abbreviated cocktail entries — strDrink, strDrinkThumb, and idDrink only — suitable for building lists before fetching full details. filter_cocktails_by_ingredient accepts an ingredient name; filter_cocktails_by_category and filter_cocktails_by_glass accept values from their respective list endpoints. filter_cocktails_by_alcoholic narrows results by classification. Use list_categories, list_glasses, and list_alcoholic_filters to enumerate all valid filter values before querying — category and glass values require underscores in place of spaces.
Ingredient Data
search_ingredient_by_name returns structured ingredient records with strDescription, strType, strAlcohol (flag), and strABV (alcohol by volume percentage). lookup_ingredient_by_id fetches the same fields by numeric ingredient ID. list_ingredients returns the full set of ingredient names stored in the database, each as an object with a strIngredient1 field — note the field name differs from the ingredient detail objects returned by the search and lookup endpoints.
Random and Enumerating the Catalog
get_random_cocktail requires no parameters and returns one complete cocktail record per call, selected randomly from the full database. All filter and list endpoints return a total integer alongside a results array, making it straightforward to check match counts before iterating over results.
The TheCocktailDB API is a managed, monitored endpoint for thecocktaildb.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when thecocktaildb.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official thecocktaildb.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a cocktail recipe app that searches drinks by name and displays full ingredient lists with measures
- Generate a random drink suggestion widget using
get_random_cocktailwithout any user input - Filter drinks by glass type (e.g., 'Highball_glass') to recommend cocktails for specific barware
- Display ingredient detail pages including ABV and type classification from
search_ingredient_by_name - Create an alphabetical cocktail browser using
search_cocktails_by_first_letteracross a–z - Segment a cocktail menu by alcoholic versus non-alcoholic using
filter_cocktails_by_alcoholic - Populate ingredient autocomplete by enumerating all available ingredients via
list_ingredients
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TheCocktailDB have an official developer API?+
What fields do the filter endpoints return, and when should I use lookup_cocktail_by_id instead?+
filter_cocktails_by_ingredient, filter_cocktails_by_category, filter_cocktails_by_glass, and filter_cocktails_by_alcoholic — return only three fields per result: strDrink, strDrinkThumb, and idDrink. They do not include ingredients, measures, or instructions. Pass the returned idDrink to lookup_cocktail_by_id to get the full cocktail record.Can I filter cocktails by multiple ingredients at once?+
filter_cocktails_by_ingredient accepts a single ingredient name per call and returns all cocktails containing that ingredient. You can fork this API on Parse and revise it to add a multi-ingredient intersection endpoint.Are cocktail results paginated?+
results array. For broad queries like search_cocktails_by_first_letter with a common letter, this can mean large response payloads. The total field tells you how many objects are in the array.