Olive Young APIoliveyoung.co.kr ↗
Access Olive Young product listings, reviews, rankings, and categories via 6 endpoints. Search by keyword, browse by category ID, and fetch KRW prices in real time.
What is the Olive Young API?
The Olive Young API provides structured access to Korea's largest beauty and cosmetics marketplace through 6 endpoints covering product search, category browsing, product details, customer reviews, and popularity rankings. The search_products endpoint accepts Korean and English keywords alongside sort options, while get_product_detail returns KRW pricing, discount rates, brand names in both Korean and English, and availability status for any goods number.
curl -X GET 'https://api.parse.bot/scraper/b9d50b57-bfe1-42cc-adf4-f2745473ce06/search_products?page=1&sort=RANK&query=tint' \ -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 oliveyoung-co-kr-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.
"""Olive Young Korea — search products, drill into details and reviews, browse by category."""
from parse_apis.olive_young_api import OliveYoung, Sort, ProductNotFound
client = OliveYoung()
# Search for lip tint products sorted by popularity
for product in client.productsummaries.search(query="tint", sort=Sort.RANK, limit=5):
print(product.name, product.brand, product.sale_price)
# Take one product and drill into full details
item = client.productsummaries.search(query="serum", limit=1).first()
if item:
detail = item.details()
print(detail.name, detail.brand_eng, detail.prices.current, detail.prices.discount_rate)
# Read reviews for the product
if item:
for review in item.reviews.list(size=3, limit=3):
print(review.review_score, review.profile.nickname, review.content[:60])
# Browse a category's ranking
makeup = client.category(cat_no="10000010002")
for ranked in makeup.ranking(limit=5):
print(ranked.rank, ranked.name, ranked.brand, ranked.price)
# Fetch the full category tree
tree = client.categorytrees.get()
print(tree.pc_category.make_time, tree.pc_category.make_version)
# Typed error handling on a direct product lookup
try:
product = client.products.get(goods_no="A000000248951")
print(product.name, product.categories.middle)
except ProductNotFound as exc:
print(f"Product not found: {exc.goods_no}")
print("exercised: search / details / reviews.list / ranking / categorytrees.get / products.get")
Full-text search over Olive Young product listings by keyword. Returns paginated results with product name, brand, price, review count, and category info. Each page returns up to 24 results by default. Server-side sorting is limited to rank, price ascending/descending, and newest.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| sort | string | Sort order for results |
| queryrequired | string | Search keyword (e.g. 'tint', 'serum', '립틴트') |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"items": "array of product objects with GOODS_NO, GOODS_NM, ONL_BRND_NM, SALE_PRC, SUP_PRC, IMG_PATH_NM, PRMUM_GDAS_TOT_CNT, MID_CAT_NM",
"total_count": "integer, total number of matching products"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"SUP_PRC": 18000,
"GOODS_NM": "[NEW] 퓌 로즈 옵세션 스테이핌 틴트",
"GOODS_NO": "A000000248951",
"SALE_PRC": 12500,
"MID_CAT_NM": "메이크업",
"IMG_PATH_NM": "10/0000/0024/A00000024895125ko.jpg?l=ko",
"ONL_BRND_NM": "퓌",
"BEST_GOODS_YN": "Y",
"ONL_BRND_NM_EN": "FWEE",
"PRMUM_GDAS_TOT_CNT": 4310
}
],
"total_count": 237
},
"status": "success"
}
}About the Olive Young API
Product Search and Category Browsing
The search_products endpoint accepts a query string — including Korean characters like '립틴트' — and an optional sort parameter with four accepted values: RANK, SALE_PRC, SALE_PRC_DESC, and DATE. Results are paginated (1-based) and return a TotalCount, page-level Count, and a Result array per page. The list_category_products endpoint mirrors this structure but scopes results to a specific category_id, such as 10000010002 for Makeup or 10000010001 for Skincare. Category IDs for both endpoints are discoverable via get_category_list.
Product Detail and Pricing
get_product_detail takes a goods_no string (e.g., A000000230581) obtained from search or category results and returns a normalized product record. Price fields are grouped in a prices object with original, current, and maxBenefit values in KRW integers, plus a discountRate percentage. The response also includes brandEng for the English-language brand name, a supplier field, and a categories object with four hierarchy levels: upper, middle, lower, and leaf.
Reviews and Rankings
get_product_reviews uses cursor-based pagination via nextCursorId and nextCursorScore fields. The hasNext boolean signals whether additional pages exist. Each entry in goodsReviewList includes a score, review text, photos, and reviewer profile data. The get_makeup_ranking endpoint returns an ordered array of products with integer rank, name, brand, price (KRW), goodsNo, and image fields for a given category_id, defaulting to the Makeup category when no ID is supplied.
Category Tree
get_category_list requires no inputs and returns the full hierarchical category structure under pcCategories. Each node carries a catNo (the ID used by other endpoints) and catNm. The response also includes makeTime and makeVersion metadata, which indicate when the category tree was last generated.
The Olive Young API is a managed, monitored endpoint for oliveyoung.co.kr — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when oliveyoung.co.kr 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 oliveyoung.co.kr 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 K-beauty price tracker by polling
get_product_detailfor KRWcurrentprice anddiscountRatechanges over time - Aggregate customer sentiment by fetching
goodsReviewListscores across multiple products withget_product_reviews - Generate a ranked product feed for a beauty app using
get_makeup_rankingacross multiple category IDs fromget_category_list - Index Olive Young's catalog for search by iterating
list_category_productsacross all leaf category IDs - Monitor new product launches by sorting
search_productswithsort=DATEfor a given keyword - Map brand presence across categories by extracting
brandandbrandEngfields from category product listings - Compare supplier diversity across Makeup vs Skincare categories using the
supplierfield fromget_product_detail
| 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 Olive Young have an official public developer API?+
What does `get_product_detail` return that search results don't include?+
get_product_detail returns fields not present in search listings: a full prices object with original, current, maxBenefit, and discountRate; the supplier company name; brandEng for the English brand name; a status field for availability; and a four-level categories hierarchy (upper, middle, lower, leaf). Search and category endpoints return summary data suited for listing pages, not individual product records.How does pagination work for reviews, and does it differ from product search pagination?+
get_product_reviews uses cursor-based pagination: each response includes nextCursorId, nextCursorScore, and a hasNext boolean to determine whether more pages exist. The page parameter is 0-based for reviews. Product search and category endpoints use standard 1-based page integers with a TotalCount in the response.Does the API expose product ingredients or detailed skin-type attributes?+
Is ranking data available for categories other than Makeup?+
get_makeup_ranking defaults to Makeup (10000010002) but accepts any category_id from get_category_list. This means you can retrieve rankings for Skincare, Hair, or any other top-level or sub-category by passing the corresponding catNo. If a specific sub-category ranking isn't returning results, the category may not have a dedicated ranking feed, and you can fork the API on Parse to handle that case separately.