kohls-research

Kohl's research

Browse Kohl's own catalog taxonomy to list products with pricing and ratings, pull a specific product's customer reviews, find nearby store locations, and get search-box typeahead suggestions — all as normalized JSON from the Crawlora API, with no HTML scraping.

When to use this skill

• "What's in Kohl's [category], e.g. Room:Dorm or Department:Bedding?"
• "What would Kohl's suggest if someone starts typing '[partial query]'?"
• "Pull the reviews for this Kohl's product."
• "Find the nearest Kohl's to [city/state, ZIP, or address]."
• "Discover Kohl's subcategories under [department]."

Setup (one-time)

• Get a free Crawlora API key (2,000 credits/mo, no card) at https://crawlora.net.
• export CRAWLORA_API_KEY=sk_your_key_here
• All requests: x-api-key: $CRAWLORA_API_KEY against https://api.crawlora.net/api/v1. Missing/invalid key → 401.

How it works

1. Browse a category — /kohls/category (category) returns a category or curated campaign page's product grid (page 1 only) plus facets for discovering further category values. category is Kohl's own taxonomy string, e.g. "Room:Dorm" or "Department:Kitchen & Dining"; combine multiple dimensions with a literal +, percent-encoded as %2B so it survives as + rather than being decoded to a space, e.g. "Room%3ADorm%2BDepartment%3ABedding".
2. Discover the taxonomy — every facets[].options[].category value in a response is a ready-to-use category string for a follow-up call, so start from a known category and follow facets to enumerate related departments/rooms/brands rather than guessing strings. An unrecognized category value returns 404; a recognized dimension with no matching products returns a genuine zero-result response.
3. Get typeahead ideas — /kohls/suggest (query) returns Kohl's own search-box suggestions for a partial query as a flat list of phrases (no product data) — useful for finding a category to browse, not for pulling products directly.
4. Reviews — /kohls/product/reviews (web_id, optional page, 10 per page) pulls a specific product's reviews (title, text, rating, secondary ratings, reviewer, date, photos). web_id comes from a /kohls/category response's products[].web_id field.
5. Stores — /kohls/stores (search) finds nearby Kohl's locations by free-text city/state, ZIP, or address: address, phone, hours, distance, and badges/services.

Full endpoint list, methods, and params: reference/endpoints.md.

Calling the API

# Browse a category (product grid + facets for further categories):
scripts/crawlora.sh /kohls/category category="Room:Dorm" | jq '.'

# Combine two taxonomy dimensions (literal "+", percent-encoded as %2B):
scripts/crawlora.sh /kohls/category category="Room%3ADorm%2BDepartment%3ABedding" | jq '.'

# Reviews for a product found in a category response's products[].web_id:
scripts/crawlora.sh /kohls/product/reviews web_id=4739201 page=1 | jq '.'

# Nearby stores and typeahead suggestions:
scripts/crawlora.sh /kohls/stores search="Chicago, IL" | jq '.'
scripts/crawlora.sh /kohls/suggest query="dorm bedding" | jq '.'

Raw curl fallback:

curl -fsS -H "x-api-key: $CRAWLORA_API_KEY" \
  "https://api.crawlora.net/api/v1/kohls/category?category=Room%3ADorm" | jq '.'

Endpoint reference

See reference/endpoints.md for every Kohl's endpoint this skill uses (method, path, params, description).

Examples

• Category sweep with reviews: /kohls/category with category="Room:Dorm" to list products and pricing, pick a products[].web_id, then /kohls/product/reviews to summarize what buyers say before recommending it.
• Taxonomy discovery: /kohls/category on a known starting category, then follow facets[].options[].category values to find and browse related departments, rooms, or brand filters the user didn't name explicitly.
• Nearby store lookup: /kohls/stores with a city/state or ZIP to list nearby locations, hours, and services.

Notes & limits

• Credits / pay-on-success: billed only on 2xx; free tier 2,000 credits/mo. Key at https://crawlora.net.
• Public data only — public Kohl's category, review, store, and suggest pages; respect Kohl's terms.
• Security: key lives in CRAWLORA_API_KEY only — never hardcode, query-param, or commit it.
• No full-text product search or single-product lookup exists. Product discovery is only through /kohls/category taxonomy browsing (following facets[].options[].category values) and /kohls/suggest typeahead phrases — there is no /kohls/product or /kohls/search endpoint, so a free-text query has to be resolved to a category string (or a suggestion) before you can list products.
• /kohls/category only returns page 1 of a category's product grid — there is no page parameter for deeper pagination.
• web_id for reviews comes from a prior /kohls/category call's products[].web_id — there's no way to look up reviews from a bare product name or URL.