# Cigar Aficionado — 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 premium cigars with detailed reviews and ratings, browse the latest industry news, and explore Cigar Aficionado's prestigious Top 25 lists. Get comprehensive information about specific cigars including their ratings and reviews to find your next favorite smoke.

**Category:** Reviews & Ratings | **Website:** [cigaraficionado.com/](https://cigaraficionado.com/) | **Docs:** [parse.bot/marketplace/2837ed45-329b-4e5e-a7ab-4a9e81b78278/cigaraficionado-com-api](https://parse.bot/marketplace/2837ed45-329b-4e5e-a7ab-4a9e81b78278/cigaraficionado-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-cigaraficionado-com-api-2837ed45/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_brands

List all brand names available in the Cigar Aficionado ratings database. These are the values usable in the search_cigars brands filter. Returns over 2700 brands.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/get_brands \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_cigar_detail

Fetch the full review page of a specific cigar. Returns tasting notes, score, detailed specifications (size, filler, binder, wrapper, country, price, box date, issue), and physical dimensions (length in inches and ring gauge). The url parameter should come from search_cigars results[*].url.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the cigar review page (e.g. 'https://www.cigaraficionado.com/ratings/26602/name/montecristo-no-4-petit-corona'). Obtain from search_cigars results[*].url. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/get_cigar_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_cigar_details_bulk

Fetch full cigar detail records for multiple cigars in a single API call. Accepts a comma-separated list of cigar detail URLs (from search_cigars results[*].url) and returns the same data as get_cigar_detail for each. Limited to 25 URLs per call. Fetches concurrently for lower latency. Returns both successful results and per-URL errors.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `urls` | string | Yes | Comma-separated list of cigar detail URLs (e.g. from search_cigars results[*].url). Maximum 25 URLs per call. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/get_cigar_details_bulk \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":"<string>"}'
```

### get_countries

List all country names available in the Cigar Aficionado ratings database. These are the values usable in the search_cigars countries filter.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/get_countries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_news_list

Get latest cigar industry news articles. Returns a list of article titles and URLs. Summary and date fields are included when available on the page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

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

### get_top25_cigars

Retrieve the Top 25 Cigars list for a given year. Returns all 25 ranked cigars with name, rank, optional summary, and a detail URL. Available years range from 2004 to 2025.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | Year of the Top 25 list (e.g. 2024, 2023). Available from 2004 to 2025. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/get_top25_cigars \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### search_cigars

Search the cigar ratings database with optional filters for brand, country, size, strength, price, and issue year. Returns paginated results sorted by relevance. Each source page contains up to 20 results. The limit parameter fetches across multiple source pages (up to 5 pages, max 100 results). Use next_page from the response to retrieve the next non-overlapping batch of source records. Pagination advances by source records consumed (not deduplicated count), so dedupe=true does not cause records to be skipped. When include_dimensions is true, each result's detail page is fetched to add length and ring_gauge (adds one request per result). Use year_from/year_to for year range filtering (applied client-side to the issue_date field).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brands` | string | No | Comma-separated list of brand names to filter by (e.g. 'Montecristo,Cohiba'). Use get_brands to see all available values. |
| `countries` | string | No | Comma-separated list of countries to filter by (e.g. 'Cuba,Nicaragua'). Use get_countries to see all available values. |
| `dedupe` | boolean | No | When true, returns one entry per cigar name (case-insensitive) rather than every historical review. Pagination still advances by source records consumed, not deduplicated count. |
| `include_dimensions` | boolean | No | When true, fetches each result's detail page to add length (inches) and ring_gauge fields. Adds one HTTP request per result, so use with limit for efficiency. |
| `issue_year` | string | No | Filter results by issue/review year (e.g. '2024'). Available years: 2000-2026. |
| `limit` | integer | No | Maximum number of results to return. Fetches across source pages if needed (max 100, up to 5 source pages per call). When omitted, returns up to 20 results from the requested page. |
| `page` | integer | No | Starting source page number. Use next_page from a previous response to continue pagination without overlap. |
| `price` | string | No | Price range filter. |
| `query` | string | No | Search query string (e.g. 'Montecristo'). |
| `sizes` | string | No | Comma-separated list of sizes to filter by (e.g. 'Toro,Churchill'). |
| `strengths` | string | No | Comma-separated list of strengths to filter by (e.g. 'Medium,Full'). |
| `year_from` | integer | No | Filter results to those with issue year >= this value (e.g. 2010). Applied client-side to the issue_date field. Can be combined with year_to for a range. |
| `year_to` | integer | No | Filter results to those with issue year <= this value (e.g. 2020). Applied client-side to the issue_date field. Can be combined with year_from for a range. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigaraficionado-com-api-2837ed45/search_cigars \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brands":"<string>","countries":"<string>","dedupe":"<boolean>","include_dimensions":"<boolean>","issue_year":"<string>","limit":"<integer>","page":"<integer>","price":"<string>","query":"<string>","sizes":"<string>","strengths":"<string>","year_from":"<integer>","year_to":"<integer>"}'
```