# Fragrantica — 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 perfumes with detailed information including fragrance notes, accords, and ratings, while exploring curated brands and note collections. Browse Fragrantica's comprehensive perfume catalog to find scents based on specific characteristics and community feedback.

**Category:** E-commerce | **Website:** [fragrantica.com/](https://fragrantica.com/) | **Docs:** [parse.bot/marketplace/366d90c1-f1bc-44ac-acb4-d21d2575ee6c/fragrantica-com-api](https://parse.bot/marketplace/366d90c1-f1bc-44ac-acb4-d21d2575ee6c/fragrantica-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-fragrantica-com-api-366d90c1/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_perfume_details

Get detailed information for a specific perfume by its full Fragrantica URL. Returns name, brand, fragrance notes pyramid (top/middle/base), main accords with intensity, rating, and description. Requires the complete URL path including the numeric perfume ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the perfume page on Fragrantica (e.g. 'https://www.fragrantica.com/perfume/Chanel/Chanel-No-5-Eau-de-Parfum-40069.html') |

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

### list_brands

List perfume brands/designers filtered by first letter. Returns an array of brand names and their Fragrantica URLs for the given letter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | No | Single letter A-Z to filter brands by first character |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fragrantica-com-api-366d90c1/list_brands \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"letter":"<string>"}'
```

### list_notes

List all fragrance notes categorized by group (e.g. Citrus, Flowers, Woods). Returns categories each containing an array of notes with name, URL, and image. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fragrantica-com-api-366d90c1/list_notes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_perfumes

Full-text search over Fragrantica's perfume database via Algolia. Returns paginated results with perfume name, designer, year, rating, gender, and thumbnail. The API key is fetched dynamically from the site on first call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page (max 100) |
| `page` | integer | No | Page number (0-based) |
| `query` | string | Yes | Search keyword (e.g. 'chanel', 'rose', 'dior') |

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