# Raisin — 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 natural wine bars, restaurants, wine shops, winemakers, and events from the Raisin.digital guide. Browse venues on an interactive map to find natural wine experiences near you.

**Category:** Food & Dining | **Website:** [raisin.digital/](https://raisin.digital/) | **Docs:** [parse.bot/marketplace/7cadb756-9401-4174-a04d-e18124a4ed2f/raisin-digital-api](https://parse.bot/marketplace/7cadb756-9401-4174-a04d-e18124a4ed2f/raisin-digital-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/raisin/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get map venues

Get venues displayed on the map, filtered either by city_id or geographic bounding box. Optionally filter by venue category. Returns all matching venues with coordinates for map display. Each venue includes id, name, latitude, longitude, like count, comment count, type tags, and object_type. Use city_id from search results or provide north/south/east/west bounds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter by venue category. |
| `city_id` | string | No | Raisin city ID to get all venues in that city (e.g. '2988507' for Paris). Obtain from the search endpoint's city results. Either city_id or all four geographic bounds (north, south, east, west) are required. |
| `east` | string | No | Eastern longitude bound (decimal degrees). Required together with north, south, west when city_id is not provided. |
| `north` | string | No | Northern latitude bound (decimal degrees). Required together with south, east, west when city_id is not provided. |
| `south` | string | No | Southern latitude bound (decimal degrees). Required together with north, east, west when city_id is not provided. |
| `west` | string | No | Western longitude bound (decimal degrees). Required together with north, south, east when city_id is not provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/raisin/get-map-venues \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","city_id":"<string>","east":"<string>","north":"<string>","south":"<string>","west":"<string>"}'
```

### Search

Search for places, venues, winemakers, and events by keyword. Returns a mixed list of cities, districts, venues, winemakers, and events matching the query, ordered by relevance. Each result carries an object_type discriminator ('city', 'district', 'venue', 'winemaker', 'event') and fields vary per type. Paginates as a single page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lang` | string | No | Language code for results. |
| `query` | string | Yes | Search term (place name, country, city, winemaker, event name, etc.) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/raisin/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"lang":"<string>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.