Alsharqiyah APIalsharqiyah.com ↗
Access Alsharqiyah Oud's full product catalog, category hierarchy, pricing in SAR, sale status, and stock availability via a simple 3-endpoint API.
What is the Alsharqiyah API?
The Alsharqiyah Oud API gives developers access to the complete product catalog of this Saudi Arabian perfume and oud retailer through 3 endpoints. The list_products endpoint returns product names, SAR pricing, sale prices, sold quantities, and availability across all categories, while get_product_details exposes per-product fields including SKU, image URL, stock status, and full description. A category hierarchy endpoint rounds out the coverage.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/d6ff139c-c24c-4dc5-9199-8e3b30a6ae63/list_categories' \ -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 alsharqiyah-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.
"""Walkthrough: Alsharqiyah Oud Store — browse categories, list products, view details."""
from parse_apis.alsharqiyah_com_api import Alsharqiyah, NotFoundError
client = Alsharqiyah()
# Browse available product categories.
for category in client.categories.list(limit=5):
print(category.id, category.name)
# Pick the first category and list its products.
cat = client.categories.list(limit=1).first()
if cat is not None:
for product in client.product_summaries.list(category_id=cat.id, limit=3):
print(product.name, product.price, product.currency, "sold:", product.sold_quantity)
# Drill into the first product's full details via navigation.
summary = client.product_summaries.list(category_id=cat.id, limit=1).first()
if summary is not None:
try:
detail = summary.details()
except NotFoundError:
print("product no longer available")
else:
print(detail.name, detail.price, detail.currency)
print("in stock:", detail.is_available, "max qty:", detail.max_quantity)
if detail.promotion_title:
print("promo:", detail.promotion_title)
print("exercised: categories.list / product_summaries.list / details()")
Returns all product categories with their hierarchical sub-categories. Each category includes its numeric ID, name, and URL. Categories with children include a sub_categories array. One API call, no pagination.
No input parameters required.
{
"type": "object",
"fields": {
"categories": "array of category objects with id, name, url, and optional sub_categories"
},
"sample": {
"data": {
"categories": [
{
"id": "1297918662",
"url": "https://alsharqiyah.com/ar/عرض-جميع-المنتجات/c1297918662",
"name": "عرض جميع المنتجات"
},
{
"id": "1222346297",
"url": "https://alsharqiyah.com/ar/عطور/c1222346297",
"name": "عطور"
},
{
"id": "1530056813",
"url": "https://alsharqiyah.com/ar/دهن-عود-وبخور-وهدايا/c1530056813",
"name": "دهن عود وبخور وهدايا",
"sub_categories": [
{
"id": "891289454",
"url": "https://alsharqiyah.com/ar/مبثوث/c891289454",
"name": "مبثوث"
}
]
}
]
},
"status": "success"
}
}About the Alsharqiyah API
Category and Product Discovery
The list_categories endpoint returns the full category tree in a single call with no pagination. Each category object includes a numeric id, a name, a url, and — where applicable — a sub_categories array for nested groupings. The numeric category ID is the key input for filtering product listings downstream.
Product Listings
The list_products endpoint accepts an optional page integer for pagination and an optional category_id string to narrow results to a specific branch of the category tree. Each product record includes id, name, price, regular_price, sale_price, currency (SAR), sold_quantity, category, and is_available. Omitting category_id returns the full catalog. The pagination object on every response includes current_page, next_page_url, and has_next so you can iterate through the full catalog programmatically.
Product Details
Passing a product_id from list_products to get_product_details returns a richer record: sku, canonical url, image_url, is_on_sale, sale_price, status (e.g. sale), and the full HTML product description. This is where you get the promotional context and rich content that the listing endpoint omits.
The Alsharqiyah API is a managed, monitored endpoint for alsharqiyah.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when alsharqiyah.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 alsharqiyah.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 price-tracking tool that monitors SAR prices and
sale_pricechanges across the oud catalog. - Sync Alsharqiyah Oud product data into an aggregator that compares Gulf perfume retailers.
- Display category-filtered product grids by passing
category_idfromlist_categoriestolist_products. - Identify best-selling oud products by sorting on the
sold_quantityfield returned bylist_products. - Alert customers when an out-of-stock product (
is_available) becomes available again. - Extract product SKUs and image URLs from
get_product_detailsto populate a product feed or catalog export.
| 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 Alsharqiyah Oud have an official developer API?+
How does pagination work in list_products, and how many products come back per page?+
pagination object in every response includes current_page, has_next (boolean), and next_page_url. Increment the page parameter and check has_next to iterate the full catalog. Filtering by category_id applies pagination within that category.Does get_product_details return customer reviews or ratings?+
Are product variants (e.g. different sizes or scent concentrations) exposed?+
get_product_details returns a single price, SKU, and availability state per product ID. You can fork this API on Parse and revise it to surface variant-level data if the source exposes it.What currency does pricing come back in?+
currency field on both list_products and get_product_details will read SAR. No currency conversion is applied.