Shop.app API endpoint
Returns search suggestions inside one Shop.app shop, for the shop `handle` and required `query`. `limit` defaults to 20, which is also the maximum. Suggestions are `type` term, product or collection, with text, position and a product or collection object where relevant. Unknown shops return not found.
/shop-app/shops/{handle}/typeaheadReturns public typeahead suggestions from a Shop.app merchant profile.
Path parameters:
handle: required. Shop.app shop handle. Example: marcnolan.Query parameters:
query: required string. Typeahead query. Example: loafer.limit: optional integer. Maximum suggestions to return. Default: 20; maximum: 20.Notable response behavior:
| Field | Filled in, of 13 checked | Values in the sample |
|---|---|---|
| type | 13 | term (10), product (3) |
| text | 13 | “loafer” and 12 other values |
| id | 13 | |
| position | 13 | 1 to 13, median 7 |
| url | 3 | marcnolan.com |
| product | 3 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| handle (path) | string | Yes | Shop handle | marcnolan | |
| query | string | Yes | Typeahead query | loafer | |
| limit | integer | No | 20 and supports up to 20 | Maximum suggestions, defaults to 20 and supports up to 20 | 20 |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/shop-app/shops/marcnolan/typeahead?query=loafer&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"shop_handle": "marcnolan",
"query": "loafer",
"suggestions": [
{
"type": "term",
"text": "loafer",
"position": 1
},
{
"type": "product",
"text": "Odell White Leather Belgian Loafer Sneakers",
"id": "7438827651151",
"position": 2
}
]
}
}Request schema
No body schema
Response schema
#/definitions/shopapp.shopTypeaheadResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | shopapp.ShopTypeaheadResponse | No | ||||
| data.limit | integer | No | 20 | Maximum number of suggestions requested. | ||
| data.query | string | No | loafer | Text that was searched for within the shop. | ||
| data.shop_handle | string | No | marcnolan | Shop.app handle of the shop. | ||
| data.shop_id | string | No | 186720 | Shop.app ID of the shop. | ||
| data.suggestions | array | No | Typeahead suggestions from the shop. | |||
| data.suggestions[].collection | object | No | Suggested collection. Set when `type` is `collection`. | |||
| data.suggestions[].collection.id | string | No | 292518002767 | Shop.app collection ID. | ||
| data.suggestions[].collection.slug | string | No | mens-dress-shoes | URL slug of the collection. | ||
| data.suggestions[].collection.title | string | No | Mens Dress Shoes | Collection title, for example `Mens Dress Shoes`. | ||
| data.suggestions[].collection.url | string | No | Shop.app page URL of the collection. | |||
| data.suggestions[].id | string | No | 7438827651151 | ID of the suggested product, collection or term. | ||
| data.suggestions[].position | integer | No | 1 | Position of the suggestion in the list, starting at 1. | ||
| data.suggestions[].product | object | No | Suggested product. Set when `type` is `product`. | |||
| data.suggestions[].product.currency | string | No | USD | Currency code of `price` and `original_price`. | ||
| data.suggestions[].product.group_query | string | No | kids' athletic sneakers | Search query of the product group this item belongs to. | ||
| data.suggestions[].product.group_title | string | No | kids' athletic sneakers | Title of the product group this item belongs to. | ||
| data.suggestions[].product.id | string | No | 8075903107261 | Shop.app product ID. | ||
| data.suggestions[].product.image | string | No | https://cdn.shopify.com/s/files/1/1145/5784/files/example.jpg | URL of the product's first image. | ||
| data.suggestions[].product.image_alt | string | No | Black sneaker side view | Alt text of the product's first image. | ||
| data.suggestions[].product.on_sale | boolean | No | `true` when the original price is higher than the current price. | |||
| data.suggestions[].product.original_price | number | No | 120 | Price before the discount, in `currency`. | ||
| data.suggestions[].product.position | integer | No | 1 | Position of the product in the results, starting at 1. | ||
| data.suggestions[].product.price | number | No | 100 | Current price of the product, in `currency`. | ||
| data.suggestions[].product.shop_id | string | No | 62696 | Shop.app ID of the shop selling the product. | ||
| data.suggestions[].product.shop_name | string | No | BILLY Footwear | Name of the shop selling the product. | ||
| data.suggestions[].product.title | string | No | Black/Black/Gum BILLY Sport Inclusion DZ1 | Product title as shown on the Shop.app card. | ||
| data.suggestions[].product.url | string | No | https://billyfootwear.com/products/black-black-gum-billy-sport-inclusion-dz1-zipper-shoes?utm_source=shop_app | Link to the product page. | ||
| data.suggestions[].product.variant_id | string | No | 46242960965821 | ID of the product variant shown on the card. | ||
| data.suggestions[].text | string | No | loafer | Text of the suggestion, such as a term or product title. | ||
| data.suggestions[].type | string | No | product | Kind of suggestion: `product`, `collection` or `term`. | ||
| data.suggestions[].url | string | No | Shop.app URL of the suggested product or collection. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/shop-app/shops/marcnolan/typeahead?query=loafer&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"