Shop.app research
Search, browse, and analyze products, variants, shops, and reviews on
Shop.app — Shopify's cross-store shopping/discovery app (not to be confused
with an individual Shopify storefront) — all as normalized JSON from the
Crawlora API, with no HTML scraping.
When to use this skill
- "Find X on Shop.app" / "search Shop.app for running shoes."
- "What's the price range / how many shops sell X on Shop.app?"
- "Look up this Shop.app shop" / "list a merchant's Shop.app catalog or collections."
- "Pull reviews for this Shop.app product or shop."
- "Get variants / options / availability for this Shop.app product."
- Cross-store discovery, market-snapshot, or merchant due-diligence research on Shop.app.
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
- Search / discover —
/shop-app/search (query, plus deep_search,
in_stock, on_sale, limit up to 50) to find candidate products by
keyword. /shop-app/suggestions returns autocomplete query ideas, and
/shop-app/categories lists public product categories to browse instead
of searching.
- Market snapshot —
/shop-app/analysis runs the same search but
returns an aggregated snapshot (price ranges, currencies, sale counts,
discounts, top shops) instead of raw listings — use it for "what's the
price range for X on Shop.app" without paginating results yourself.
- Product detail —
/shop-app/products/{id} for normalized product
details (add variant_id to pin a specific variant).
- Variants —
/shop-app/products/{id}/variant for the exact variant
matching selected_options, or /shop-app/products/{id}/variants for
adjacent variants, to compare options and prices.
- Related products & reviews —
/shop-app/products/{id}/related and
/shop-app/products/{id}/reviews.
- Resolve the shop —
/shop-app/products/{id}/shop finds the merchant
behind a product; /shop-app/shops/{handle} fetches the merchant profile
directly, and /shop-app/shops/{handle}/locations lists retail locations.
- Browse a shop's catalog —
/shop-app/shops/{handle}/products
(sortable via sort_by) or /shop-app/shops/{handle}/collections/{collection_id}/products
for one collection; /shop-app/shops/{handle}/typeahead searches inside a
single shop; /shop-app/shops/{handle}/reviews pulls merchant reviews.
Full endpoint list, methods, and params: reference/endpoints.md.
Calling the API
# Search Shop.app (GET, key=value params):
scripts/crawlora.sh /shop-app/search query="running shoes" in_stock=true | jq '.'
# Product detail:
scripts/crawlora.sh /shop-app/products/12345 | jq '{title,price}'
# Browse a shop's catalog, sorted low-to-high:
scripts/crawlora.sh /shop-app/shops/some-shop-handle/products sort_by=PRICE_LOW_TO_HIGH | jq '.'
Raw curl fallback:
curl -fsS -H "x-api-key: $CRAWLORA_API_KEY" \
"https://api.crawlora.net/api/v1/shop-app/search?query=running+shoes" | jq '.'
Endpoint reference
See reference/endpoints.md for every Shop.app
endpoint this skill uses (method, path, params, description).
Examples
- Market snapshot before buying:
/shop-app/analysis with query="wireless earbuds"
and on_sale=true to see the current price range, discounts, and top
shops selling discounted units.
- Merchant due-diligence:
/shop-app/shops/{handle} +
/shop-app/shops/{handle}/reviews to summarize a Shop.app merchant's
profile and recent reviews before recommending it.
- Collection audit:
/shop-app/shops/{handle}/products (paginate via
limit) or a specific /shop-app/shops/{handle}/collections/{collection_id}/products
to list a merchant's catalog with prices and flag items above/below a
threshold.
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 Shop.app product/shop pages; respect Shop.app's terms.
- Security: key lives in
CRAWLORA_API_KEY only — never hardcode, query-param, or commit it.
- Results are limited, not offset-paginated —
search, analysis, related,
reviews, shop/collection products, and suggestions/typeahead all cap
out via limit (each endpoint has its own max, from 20 up to 100 for variants).
selected_options is a JSON object, not flat key=value pairs — pass it
as a JSON string (e.g. selected_options='{"Color":"Black"}'), or use
repeated option.Name=value / option[Name]=value filters instead.sort_by on shop/collection product listings only accepts MOST_SALES,
PRICE_LOW_TO_HIGH, PRICE_HIGH_TO_LOW, or RELEVANCE.