Caratlane APIcaratlane.com ↗
Access Caratlane jewelry data: search products, browse categories, get detailed specs, pricing in INR, gold purity, and customer reviews via 4 API endpoints.
What is the Caratlane API?
The Caratlane API provides 4 endpoints covering product search, category listings, individual product details, and homepage featured collections from caratlane.com. The get_product_detail endpoint returns full product data including SKU, gold purity, material composition, INR pricing, a media gallery, and a customer review array — all from a single product URL slug passed as input.
curl -X GET 'https://api.parse.bot/scraper/4d96531c-c3a6-4177-bc3f-31c2fe9455d9/search_products?limit=5&query=diamond+ring&offset=0' \ -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 caratlane-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: Caratlane jewellery SDK — search, browse by category, drill into details."""
from parse_apis.caratlane_jewellery_api import Caratlane, Category, ProductNotFound
client = Caratlane()
# Search for diamond rings — limit caps total items fetched.
for product in client.products.search(query="diamond ring", limit=3):
print(product.name, product.formatted_price, product.purity)
# Browse earrings category using the Category enum.
earring = client.products.list_by_category(category=Category.EARRINGS, limit=1).first()
if earring:
print(earring.sku, earring.name, earring.metal)
# Drill into full product detail (reviews, extended media).
if earring:
try:
detail = earring.details()
print(detail.name, detail.reviews_summary.count, detail.reviews_summary.rating)
except ProductNotFound as exc:
print(f"Product gone: {exc.product_url}")
# Homepage featured sections — each section has typed banners.
for section in client.featuredsections.list(limit=2):
print(section.name, section.section_type)
for banner in section.banners[:2]:
print(" ", banner.name, banner.url)
print("exercised: products.search / products.list_by_category / product.details / featuredsections.list")
Full-text search across Caratlane's jewellery catalogue. Returns paginated product summaries including pricing, media gallery URLs, and material/metal details. Pagination via offset; each page returns up to `limit` items.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of products to return per page. |
| queryrequired | string | Search keyword (e.g. 'diamond ring', 'earrings', 'gold necklace'). |
| offset | integer | Results offset for pagination. |
{
"type": "object",
"fields": {
"count": "total number of matching products",
"products": "array of product summaries with sku, name, price, special_price, formatted_price, formatted_special_price, url, media, purity, metal, and material"
},
"sample": {
"data": {
"count": 10999,
"products": [
{
"sku": "JE03565-1YP5SS",
"url": "/jewellery/royal-gemstone-stud-earrings-je03565-1yp5ss.html",
"name": "Royal Gemstone Stud Earrings",
"media": [
{
"url": "https://cdn.caratlane.com/media/catalog/product/J/E/JE03565-YGP6SS_1_lar.jpg",
"type": ""
}
],
"metal": "14 KT Yellow",
"price": 56034,
"purity": "14 KT",
"material": [
"Diamond",
"Gemstone"
],
"special_price": 50924,
"formatted_price": "₹56,034",
"formatted_special_price": "₹50,924"
}
]
},
"status": "success"
}
}About the Caratlane API
Search and Category Browsing
The search_products endpoint accepts a query string (e.g. 'diamond ring', 'gold necklace') along with optional limit and offset integers for pagination. It returns a count of total matches plus a products array. Each product summary includes sku, name, price, special_price, formatted_price, formatted_special_price, url, media, purity, and met. The get_category_listings endpoint follows the same response shape but takes a category slug instead — valid values include 'rings', 'earrings', 'necklaces-pendants', and 'bangles-bracelets'.
Product Detail
Pass any relative product URL from search_products or get_category_listings results to get_product_detail via the product_url parameter. The response expands the summary into full product data: a media array with typed objects (image URLs and media type), a metal description, a material array listing stone and metal types (e.g. ['Diamond', 'Gold']), purity in KT format ('14 KT' or '18 KT'), a reviews array with per-review author, rating, body, and date fields, and a reviews_summary object with aggregate count and rating.
Homepage Featured Collections
The get_homepage_featured endpoint takes no inputs and returns an array of homepage section objects. Each section exposes an attributes object containing title, name, Section_Type, and s_4_banner_items — a nested structure with banner name, text, url, and desktop_image fields. This is useful for tracking which collections or promotions Caratlane is currently featuring.
The Caratlane API is a managed, monitored endpoint for caratlane.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when caratlane.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 caratlane.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 jewelry price comparison tool using
priceandspecial_pricefields from search results - Monitor Caratlane's current homepage promotions and featured collections with
get_homepage_featured - Filter diamond jewelry by purity using the
purityfield returned in category and search results - Aggregate customer review ratings across multiple products using
reviews_summary.ratingandreviews_summary.count - Sync a jewelry catalog with product names, SKUs, media URLs, and material types for a retail or affiliate site
- Track price changes on specific products over time by polling
get_product_detailwith saved URL slugs
| 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 Caratlane offer an official public developer API?+
What pricing data does the API return, and does it include metal weight or making charges?+
search_products, get_category_listings, and get_product_detail endpoints all return price, special_price, formatted_price, and formatted_special_price fields in INR. Granular pricing breakdown — such as metal weight, stone weight, making charges, or GST components — is not currently exposed. The API covers summary and display pricing. You can fork it on Parse and revise to add a dedicated pricing-breakdown endpoint if that structure is available on specific product pages.How does pagination work across search and category endpoints?+
search_products and get_category_listings accept limit and offset integer parameters. The response includes a count field representing total matching products, which you can use to calculate how many pages exist for a given query or category slug.Does the API cover product availability or stock status?+
Can I retrieve products filtered by metal type or stone type directly?+
search_products endpoint accepts a free-text query (e.g. 'gold earrings', 'diamond pendant'), and get_category_listings accepts a category slug. Once results are returned, each product includes purity and material fields you can use to filter client-side. You can fork this API on Parse and revise it to expose dedicated filter parameters if the underlying category pages support faceted filtering.