Shurfan APIshurfan.net ↗
Access Shurfan Perfumes product catalog via API. Retrieve names, prices in SAR, category tags, sales rank, and images for Saudi fragrance products.
What is the Shurfan API?
The Shurfan Perfumes API exposes one endpoint — list_products — that returns up to 10 fields per product from shurfan.net, a Saudi Arabian fragrance and perfume oil retailer. Each response includes product title, price in SAR, category tags, sales rank, image URL, and vendor, all sorted by best-selling order by default. Keyword search, category filtering, and page-based pagination are supported.
curl -X GET 'https://api.parse.bot/scraper/8b03ab38-84bd-4742-b46a-232de5e9b1aa/list_products?page=1&limit=5&query=musk' \ -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 shurfan-net-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.
"""Walkthrough: Shurfan Perfumes SDK — browse best-sellers and search by keyword."""
from parse_apis.shurfan_net_api import Shurfan, InputFormatInvalid
client = Shurfan()
# Browse top-selling products across all categories.
for product in client.products.list(limit=5):
print(f"{product.sales_rank}. {product.title} — {product.price} {product.currency}")
# Search for rose products filtered by category, drill into first result.
try:
hit = client.products.list(query="rose", category="flower", limit=1).first()
except InputFormatInvalid as e:
print(f"Invalid input: {e.message}")
hit = None
if hit is not None:
print(f"\nFound: {hit.title} (id={hit.product_id})")
print(f" In stock: {hit.in_stock}, Handle: {hit.handle}")
print(f" Categories: {', '.join(hit.category)}")
print("\nexercised: products.list (paginated browse + filtered search)")
List products from Shurfan Perfumes sorted by best-selling (highest sales first). Returns product name, category tags, price in SAR, and sales rank (1 = top seller). Supports keyword search, category/tag filtering, and pagination. Each page returns up to `limit` products; use `page` to paginate through results. The total number of matching products is returned in the response.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-indexed). |
| limit | integer | Number of products per page (1-100). |
| query | string | Search keyword to filter products by name or description. Omitting returns all products. |
| category | string | Filter by product category tag (e.g. musk, fruits, flower, acords, oriental, for him, for her, unisex, niche, new). Omitting returns all categories. |
{
"type": "object",
"fields": {
"page": "current page number",
"limit": "items per page",
"total": "total number of matching products",
"has_more": "whether more pages are available",
"products": "array of product objects, each containing product_id, title, category, price, currency, sales_rank, handle, image_url, vendor, and in_stock"
},
"sample": {
"data": {
"page": 1,
"limit": 5,
"total": 905,
"has_more": true,
"products": [
{
"price": 37,
"title": "Japanese Cherry",
"handle": "japanese-cherry",
"vendor": "Shurfan Perfumes",
"category": [
"fruits"
],
"currency": "SAR",
"in_stock": true,
"image_url": "https://cdn.shopify.com/s/files/1/0454/8909/4812/products/Japaneesecherry_large.jpg?v=1667296756",
"product_id": "5959659323548",
"sales_rank": 1
},
{
"price": 37,
"title": "Lavender Flower",
"handle": "lavender-flower",
"vendor": "Shurfan Perfumes",
"category": [
"acords",
"flower",
"fruits"
],
"currency": "SAR",
"in_stock": true,
"image_url": "https://cdn.shopify.com/s/files/1/0454/8909/4812/products/lavenderflower-_1_large.jpg?v=1667226034",
"product_id": "5959636746396",
"sales_rank": 2
}
]
},
"status": "success"
}
}About the Shurfan API
What the API Returns
The list_products endpoint returns a paginated array of products from Shurfan's catalog. Each product object includes product_id, title, category, price, currency (SAR), sales_rank, handle, image_url, vendor, and additional fields. The sales_rank field is 1-indexed, so rank 1 indicates the top-selling item on the site. Products are returned in ascending sales rank order by default.
Filtering and Pagination
You can narrow results using the query parameter to match product names or descriptions, or the category parameter to filter by tag. Supported category tags include musk, fruits, flower, acords, oriental, for him, for her, unisex, and niche, among others. Pagination is controlled by page (1-indexed) and limit (1–100 items per page). The response envelope includes total (matching product count), has_more (boolean), page, and limit, so you can walk the full catalog programmatically.
Coverage Notes
All prices are denominated in SAR (Saudi Riyal), reflecting Shurfan's Saudi market focus. The API covers publicly listed products on shurfan.net. Sales rank is derived from the site's own best-seller ordering, not a calculated external metric.
The Shurfan API is a managed, monitored endpoint for shurfan.net — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when shurfan.net 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 shurfan.net 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?+
- Track which Shurfan fragrances hold the top sales ranks over time using the
sales_rankfield - Build a price comparison tool for Saudi perfume oils by querying
pricein SAR across categories - Filter the catalog by category tags like
orientalornicheto populate curated fragrance collections - Monitor inventory breadth by paginating through the full catalog and counting products per category
- Pull product
image_urlandtitlefields to populate a fragrance discovery or recommendation interface - Search for specific scent profiles using the
queryparameter to match keywords in product names
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Shurfan have an official developer API?+
What does `sales_rank` represent and how is it assigned?+
sales_rank field reflects the product's position in Shurfan's best-seller ordering, where rank 1 is the top-selling item. Ranks are assigned based on the site's own sales data and ordering logic, not independently computed.Does the API return product reviews or customer ratings?+
list_products endpoint returns product metadata — title, price, category, sales rank, image URL, and vendor — but does not include customer reviews or star ratings. You can fork this API on Parse and revise it to add a reviews endpoint if that data becomes relevant to your use case.