Selfridges APIselfridges.com ↗
Access Selfridges fragrance data including notes, scent tags, pricing in GBP, and product descriptions via 4 endpoints covering search, category, and brand browsing.
What is the Selfridges API?
The Selfridges Fragrance API provides 4 endpoints for retrieving detailed fragrance product data from selfridges.com, covering fields like fragrance_notes, scent_tags, price_gbp, brand_name, and product descriptions. The search_fragrances endpoint lets you query by keyword — from specific scents like 'Baccarat Rouge 540' to broad brand names — while companion endpoints support browsing by category slug or brand, and direct product lookup by URL.
curl -X GET 'https://api.parse.bot/scraper/08ffc2e9-34df-4cc7-91a6-8dc653718f5a/search_fragrances?limit=2&query=Tom+Ford' \ -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 selfridges-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.
"""Selfridges Fragrance API — search, browse by category/brand, get product details."""
from parse_apis.selfridges_fragrance_api import Selfridges, Category, NotFound
client = Selfridges()
# Search for fragrances by keyword, capped at 3 results.
for frag in client.fragrances.search(query="Baccarat Rouge 540", limit=3):
print(frag.brand_name, frag.product_name, frag.price_gbp)
# Browse a category using the typed enum.
first = client.fragrances.by_category(category=Category.BEAUTY_FRAGRANCE_WOMENS_PERFUME, limit=1).first()
if first:
print(first.product_name, first.scent_tags, first.fragrance_notes.top)
# Get full details for a specific product by URL.
try:
detail = client.fragrances.get(url=first.source_url)
print(detail.brand_name, detail.product_name, detail.size, detail.price_gbp)
except NotFound as exc:
print(f"Product not found: {exc}")
# Browse by brand name.
for frag in client.fragrances.by_brand(brand="LE LABO", limit=3):
print(frag.brand_name, frag.product_name, frag.fragrance_notes.heart)
print("exercised: fragrances.search / fragrances.by_category / fragrances.get / fragrances.by_brand")
Search for fragrance products by keyword on Selfridges. Returns a list of detailed product objects with fragrance notes, scent tags, pricing, and more. Each result requires fetching the individual product page, so response time scales with the limit parameter.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of products to fetch details for. |
| queryrequired | string | Search query (e.g. 'Baccarat Rouge 540', 'Tom Ford', 'Chanel No 5'). |
{
"type": "object",
"fields": {
"items": "array of product objects each containing id, brand_name, product_name, category, main_image_url, description, fragrance_notes, scent_tags, price_gbp, size, source_url, and timestamp"
},
"sample": {
"data": {
"items": [
{
"id": "8ba22e0c-0061-45eb-a410-a227c1d7344e",
"size": null,
"category": "perfume",
"price_gbp": 345,
"timestamp": "2026-06-11T04:16:56.577287",
"brand_name": "TOM FORD",
"scent_tags": [
"warm",
"fresh"
],
"source_url": "https://www.selfridges.com/GB/en/product/tom-ford-ft13045352a-square-acetate-sunglasses_R04556495/",
"description": "Tom Ford acetate sunglasses.",
"product_name": "FT13045352A Square Acetate Sunglasses",
"main_image_url": "https://images.selfridges.com/is/image/selfridges/R04556495_DARKHAVANASMOKE_M",
"fragrance_notes": {
"top": [],
"base": [],
"heart": []
}
}
]
},
"status": "success"
}
}About the Selfridges API
What the API Returns
Each product object returned across all four endpoints shares a consistent shape: id, brand_name, product_name, category, main_image_url, description, fragrance_notes, scent_tags, price_gbp, and sizing information. The fragrance_notes field captures structured note data (top, middle, base where available), and scent_tags reflect Selfridges' own categorization labels — useful for building faceted filters or recommendation logic without parsing free-text descriptions yourself.
Endpoints and Parameters
search_fragrances accepts a required query string and an optional limit integer. Response time scales with limit since each result requires individual product resolution, so keep limit low when latency matters. list_fragrances_by_category takes a category slug such as beauty/fragrance/womens-perfume or beauty/fragrance/mens-aftershave and returns the first page of matching products. list_fragrances_by_brand accepts a brand string — results are most accurate when using the brand name exactly as Selfridges displays it, for example LE LABO, TOM FORD, or MAISON FRANCIS KURKDJIAN. get_product_details takes a full Selfridges product URL and returns the complete product object for that specific item.
Coverage and Limitations
All endpoints focus exclusively on fragrances. Pricing is returned in GBP (price_gbp), reflecting Selfridges' UK storefront. Category browsing returns only the first page of results; there is no pagination parameter to retrieve subsequent pages. Invalid category slugs return an input_not_found error rather than an empty result set, so slug values should be validated before use. The limit parameter controls how many items are fully resolved, not how many are fetched from the category listing.
The Selfridges API is a managed, monitored endpoint for selfridges.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when selfridges.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 selfridges.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 fragrance recommendation engine using
scent_tagsandfragrance_notesto match user preferences. - Track GBP price changes over time for specific brands using
list_fragrances_by_brandwith brands like 'DIOR' or 'CHANEL'. - Populate a fragrance comparison tool with structured note data (top, middle, base) from
get_product_details. - Aggregate womens and mens fragrance catalogs by querying known category slugs with
list_fragrances_by_category. - Feed a product database with Selfridges fragrance imagery via
main_image_urlalongside brand and pricing data. - Audit a brand's Selfridges fragrance range by fetching all products with
list_fragrances_by_brandand inspecting category and description fields.
| 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 Selfridges have an official public developer API?+
What does `get_product_details` return that the search and browse endpoints don't?+
get_product_details takes a specific product URL and returns the same core fields — fragrance_notes, scent_tags, price_gbp, description, sizing — as the other endpoints. Its value is targeting a single known product precisely, without going through a search or category listing. This is useful when you already have a Selfridges product URL and want to refresh or verify its data directly.Can I paginate through all products in a category?+
list_fragrances_by_category returns only the first page of results for a given category slug. There is no page or offset parameter to retrieve subsequent pages. You can fork the API on Parse and revise it to add pagination support for deeper category traversal.Does the API cover non-fragrance Selfridges product categories like beauty, fashion, or homeware?+
Are prices returned in currencies other than GBP?+
price_gbp, reflecting the UK storefront. Currency conversion or international pricing (EUR, USD) is not included in the response. You can fork the API on Parse and revise it to query a different regional storefront or add conversion logic.