diffordsguide.com APIdiffordsguide.com ↗
Search, list, and retrieve detailed cocktail recipes from Difford's Guide. Access ingredients, preparation steps, ratings, glass types, and garnish data via JSON.
curl -X GET 'https://api.parse.bot/scraper/20eec9e9-6f5e-4af3-9bfd-49aa28684d35/search_cocktails?query=margarita' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for cocktails by name or ingredient keyword. Returns matching cocktail names and URLs from Difford's Guide search results.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword such as a cocktail name or ingredient (e.g. 'margarita', 'vodka', 'negroni'). |
{
"type": "object",
"fields": {
"total": "integer count of results returned",
"results": "array of objects, each with 'name' (string) and 'url' (string)"
},
"sample": {
"data": {
"total": 2,
"results": [
{
"url": "https://www.diffordsguide.com/cocktails/recipe/5390/californian-margarita",
"name": "Californian Margarita"
},
{
"url": "https://www.diffordsguide.com/cocktails/recipe/1255/margarita-on-the-rocks-diffords-recipe",
"name": "Margarita on-the-rocks (Difford's recipe)"
}
]
},
"status": "success"
}
}About the diffordsguide.com API
The Difford's Guide API provides 3 endpoints for searching and retrieving cocktail recipe data from one of the most referenced cocktail databases online. Use search_cocktails to find drinks by name or ingredient keyword, get_cocktail_details to pull a full recipe including ingredients, preparation steps, rating, glass type, and garnish, or list_cocktails to page through the entire directory in reverse chronological order.
What the API Returns
The get_cocktail_details endpoint returns the most structured data: name, tags, glass, image, steps (ordered preparation instructions), rating, cuisine, garnish, category, and description. Pass the full Difford's Guide recipe URL as the url parameter. The steps field is an ordered array, so you can render preparation instructions directly without parsing free text.
Search and Discovery
The search_cocktails endpoint accepts a query string — a cocktail name like negroni or an ingredient like vodka — and returns a total count plus a results array of name and url pairs. Those URLs can be passed directly to get_cocktail_details to fetch full recipe data in a second call.
Paginating the Directory
list_cocktails returns cocktails in reverse chronological order. Each cocktail in the response includes name, description, url, image, and date. The response includes a next_cursor field (a Unix timestamp string) and a has_more boolean. Pass next_cursor back as the cursor parameter on the next call to advance through the directory. The limit parameter accepts up to 100 per page. Omit cursor or pass '0' to start from the beginning.
Coverage Notes
Difford's Guide covers thousands of cocktail recipes with editorial metadata including glass recommendations and garnish descriptions. The rating and cuisine fields may return null for some recipes where that metadata is not present on the source page.
- Build a cocktail search app that filters by ingredient using
search_cocktailsand displays full recipes viaget_cocktail_details - Populate a recipe database by iterating through the full directory with
list_cocktailsand storingname,image, andurlfields - Match cocktail
glassandgarnishfields to bar inventory data to suggest drinks based on available glassware - Aggregate
ratingvalues across recipes to rank and surface the highest-rated cocktails in a given category - Use
tagsandcategoryfields fromget_cocktail_detailsto power a faceted browse UI for cocktail discovery - Track newly added recipes by comparing
datefields from paginatedlist_cocktailsresponses over time - Pull
stepsarrays to feed a voice assistant or recipe card generator that reads preparation instructions aloud
| 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 | 250 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 Difford's Guide offer an official developer API?+
What does `get_cocktail_details` return beyond the ingredient list?+
steps (ordered preparation instructions as an array), glass, garnish, tags, category, cuisine, rating, image, and a short description. The rating and cuisine fields can be null if the source page does not include that metadata.How does pagination work in `list_cocktails`?+
next_cursor string (a Unix timestamp) and a has_more boolean. Pass the next_cursor value as the cursor parameter on your next request to fetch the following page. Set cursor to '0' or omit it to start from the most recent entries. Each page returns up to 100 cocktails.Does the API return individual ingredient quantities or structured ingredient objects?+
get_cocktail_details endpoint returns preparation instructions in the steps array, but does not currently break out ingredients as structured objects with separate quantity, unit, and ingredient-name fields. The API covers name, steps, glass, garnish, tags, rating, and category. You can fork this API on Parse and revise it to add a structured ingredients endpoint that parses those fields individually.Can I filter `list_cocktails` or `search_cocktails` results by spirit type, category, or rating?+
search_cocktails filters by keyword query only, and list_cocktails returns results in reverse chronological order without filter parameters. You can fork this API on Parse and revise it to add filtered listing endpoints using the category or tags fields available on individual recipe pages.