# Vivino — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover wines across thousands of options while accessing detailed information like user reviews, pricing, winery profiles, and food pairing recommendations. Explore grape varieties, compare wines side-by-side, and find the perfect bottle based on ratings and availability.

**Category:** Food & Dining | **Website:** [vivino.com/](https://vivino.com/) | **Docs:** [parse.bot/marketplace/45a5703b-2808-49ff-b11b-d7714c3b5dcd/vivino-com-api](https://parse.bot/marketplace/45a5703b-2808-49ff-b11b-d7714c3b5dcd/vivino-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### explore_wines

Browse the wine catalog ordered by popularity. Returns a paginated list of wines without any search filter applied. Useful for discovering trending or highly-rated wines.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/explore_wines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_food_pairings

Find wines related to a food keyword by searching the wine index. Results include wines whose names or associated metadata (winery name, vintage name) match the food term. Useful for discovering wines branded or associated with specific foods.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `food_name` | string | Yes | Food name to find wine pairings for (e.g. 'steak', 'chicken', 'pasta'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/get_food_pairings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"food_name":"<string>"}'
```

### get_wine_details

Retrieve full details for a single wine by its numeric ID or SEO slug. Returns wine name, region, winery, vintages, description, grape IDs, food pairing IDs, alcohol percentage, and aggregate statistics. Exactly one of wine_id or wine_slug must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `wine_id` | string | No | Vivino wine ID (e.g. '1135067'). Either wine_id or wine_slug is required. |
| `wine_slug` | string | No | Wine SEO slug (e.g. 'reserve-malbec'). Either wine_id or wine_slug is required. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/get_wine_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wine_id":"<string>","wine_slug":"<string>"}'
```

### get_winery_details

Retrieve full details for a winery by its SEO slug. Searches the wine index and extracts winery metadata including name, region, statistics, description, website, and winemaker. Falls back to the first matching result's winery if no exact slug match is found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `winery_slug` | string | Yes | Winery SEO slug (e.g. 'penfolds', 'opus-one', 'casillero-del-diablo'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/get_winery_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"winery_slug":"<string>"}'
```

### search_wineries

Search for wineries by name. Searches the wine index and extracts unique wineries from matching results. Each winery includes name, region, statistics, description, and website.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | Yes | Winery name to search for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/search_wineries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### search_wines

Full-text search over Vivino's wine catalog. Matches wine name, grape variety, region, and winery name. Returns paginated results ordered by relevance with full wine details including name, region, winery, vintages, ratings, and description.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results per page. |
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | Yes | Search keyword (wine name, grape variety, region, winery, etc.). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivino-com-api-45a5703b/search_wines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```