Diffordsguide APIdiffordsguide.com ↗
Search, list, and retrieve structured cocktail recipes from Difford's Guide. Get ingredients, steps, ratings, glass type, and garnish for thousands of drinks.
What is the Diffordsguide API?
The Difford's Guide API gives developers access to thousands of cocktail recipes across 3 endpoints, covering structured recipe data including ingredients, preparation steps, glass type, garnish, and ratings. Use search_cocktails to find drinks by name or ingredient keyword, get_cocktail_details to pull full recipe metadata for a single cocktail page, or list_cocktails to paginate through the directory in reverse chronological order.
curl -X GET 'https://api.parse.bot/scraper/20eec9e9-6f5e-4af3-9bfd-49aa28684d35/search_cocktails?query=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 diffordsguide-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.
"""Difford's Guide Cocktail API — search, browse, and get full recipes."""
from parse_apis.difford_s_guide_cocktail_api import DiffordsGuide, CocktailNotFound
client = DiffordsGuide()
# Search for cocktails by keyword — single-page results, capped by limit
for summary in client.cocktailsummaries.search(query="negroni", limit=3):
print(summary.name, summary.url)
# Drill into the first search hit for the full recipe
hit = client.cocktailsummaries.search(query="margarita", limit=1).first()
if hit:
cocktail = hit.details()
print(cocktail.name, cocktail.rating, cocktail.rating_count)
for ingredient in cocktail.ingredients:
print(" ", ingredient)
# Browse the directory in reverse chronological order
for item in client.cocktailsummaries.list(limit=3):
print(item.name, item.date)
# Direct point-lookup by URL
try:
detail = client.cocktails.get(url="https://www.diffordsguide.com/cocktails/recipe/1255/margarita-on-the-rocks-diffords-recipe")
print(detail.name, detail.cuisine, detail.glass)
except CocktailNotFound as exc:
print(f"Recipe removed: {exc.url}")
print("exercised: cocktailsummaries.search / cocktailsummaries.list / hit.details / cocktails.get")
Full-text search over Difford's Guide cocktail directory by name or ingredient keyword. Returns all matching results in a single page. Each result carries a name and URL suitable for drilling into full recipe details via get_cocktail_details.
| 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 cocktail summary objects, each with 'name' (string) and 'url' (string)"
},
"sample": {
"data": {
"total": 24,
"results": [
{
"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 API
What the API Covers
The Difford's Guide API exposes cocktail directory data across three endpoints. search_cocktails accepts a query string — a cocktail name like negroni or an ingredient like vodka — and returns a flat list of matching results, each with a name and url. The total field tells you how many matches came back. These URLs feed directly into get_cocktail_details.
Recipe Detail Fields
get_cocktail_details takes a full cocktail page URL and returns a structured object with up to 14 fields: name, tags (array of keyword strings), glass, image, steps (ordered preparation instructions), rating, cuisine, garnish, category, and url. Fields like glass, rating, cuisine, and garnish are nullable — not every recipe on the site specifies all of them. The steps array preserves preparation order, which matters for drinks with multiple build phases.
Browsing and Pagination
list_cocktails lets you paginate the full cocktail directory in reverse chronological order. Each page returns summary objects with name, description, url, image, and date. Set limit up to 100 per page. Pagination is cursor-based using a Unix timestamp string: the next_cursor field from one response becomes the cursor param for the next. When has_more is false, you've reached the end of the directory.
The Diffordsguide API is a managed, monitored endpoint for diffordsguide.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when diffordsguide.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 diffordsguide.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 search tool that lets users query by ingredient and retrieve full recipes including steps and garnish
- Populate a drink database by paginating list_cocktails and storing name, image, date, and URL for each entry
- Generate ingredient-based cocktail recommendations using search_cocktails with spirit or mixer keywords
- Display recipe cards with glass type, garnish, and rating pulled from get_cocktail_details
- Track newly published cocktails by monitoring the date field from list_cocktails in reverse chronological order
- Filter cocktails by category or tags to power a themed menu builder for bar or event planning apps
| 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 Difford's Guide have an official developer API?+
What does get_cocktail_details actually return beyond the recipe steps?+
steps array, the endpoint returns glass (e.g. coupe, rocks), garnish, rating (a numeric average or null), tags (an array of keyword strings), category, cuisine, and the cocktail image URL. Fields that aren't specified on the source page come back as null.Does search_cocktails support filtering by spirit, flavor profile, or category?+
query string and returns all matches without additional filter parameters. You can search by ingredient keyword (e.g. rum, lemon juice), but server-side filtering by category, rating, or glass type is not supported. After fetching results, you can filter locally using the category or tags fields from get_cocktail_details. You can fork this API on Parse and revise it to add a dedicated filter endpoint.Does the API expose individual ingredient quantities and measurements?+
steps array as part of the preparation instructions rather than as a separate ingredients-with-quantities array. You can fork this API on Parse and revise it to parse and expose ingredients as a structured list with amounts.How does pagination work in list_cocktails, and is there a way to jump to a specific page?+
next_cursor string and a has_more boolean. Pass next_cursor as the cursor param in your next request to advance. To start from the beginning, omit cursor or pass '0'. Random-access pagination to a specific offset is not supported — you must walk the cursor chain sequentially.