API
Public Wine List
Retrieve published wine lists as JSON from your website or app. No login, API key, access token, or Authorization header is required. This API is read-only.
Base URL:https://api.v2.winecode.app
Start with your public URL
If your public URL is https://winecode.app/example-shop, use example-shop as the API groupKey. Both the public URL alias and the original group key are accepted. Unpublished groups cannot be retrieved.
curl 'https://api.v2.winecode.app/group/example-shop'example-shop is a placeholder. Replace it with the value from your public URL and encode path parameters with encodeURIComponent or an equivalent function.
View wine list publication settingsEndpoints
Public wine list
GET https://api.v2.winecode.app/group/:groupKeyAn array of eligible public wines, sorted by display price in ascending order. Returns an empty array [] when no wines match.
Wine details
GET https://api.v2.winecode.app/group/:groupKey/:threadIdOne wine. Returns HTTP 200 with an empty body for wines outside the group, drafts, hidden wines, or wines without a display price. Nonexistent IDs return 403. Wines with zero stock may be returned.
Tags
GET https://api.v2.winecode.app/group/tags/:groupKeyAn array with tagId, label, typeId, isSecret, useQty, and hasThread.
Shop information and display settings
GET https://api.v2.winecode.app/group/description/:groupKeyReturns shop contact information, a description, priceType, wine type display names, and other settings.
threadId is an integer from the list response. There are no pagination, search, or sorting query parameters. Filter the returned array in your application.
Eligibility for lists and details
The list excludes drafts and returns wines belonging to the group with positive stock (qty), a positive public display price (price.sell), and no individual hide setting. Results are sorted by display price in ascending order.
const groupKey = encodeURIComponent('example-shop');
const response = await fetch(`https://api.v2.winecode.app/group/${groupKey}/12345`);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.text();
const wine = body === '' ? null : JSON.parse(body);Wine fields
These are representative fields. Responses also contain other fields. The example is an excerpt using fictional data.
[
{
"threadId": 12345,
"type": "RED",
"name": "サンプル・ピノ・ノワール",
"label": "Sample Pinot Noir",
"year": 2022,
"area": "フランス ブルゴーニュ",
"producer": "サンプル生産者",
"variety": "ピノ・ノワール",
"tastingNote": "赤い果実の香り。",
"qty": 3,
"price": {
"sell": 8800,
"suggest": 11000,
"glass": 1500
},
"currencyCode": {
"sell": "JPY",
"suggest": "JPY",
"glass": "JPY"
},
"enableSecondPrice": false,
"images": [],
"attachments": []
}
]| Field | Description |
|---|---|
threadId | Wine (thread) ID |
type | RED / WHITE / SPARKLING / CHAMPAGNE / ROSE / ORANGE / OTHER |
name / label | Wine name and foreign-language label. Includes group-specific name overrides. |
year | Vintage year. 0 means non-vintage. |
area / producer / appellation / variety | Region, producer, appellation, and grape variety |
tastingNote / tastingTags | Tasting notes and tasting tags. Notes include group-specific overrides. |
qty | Stock quantity within the group |
price | Amounts for sell / suggest / glass. Unset values may be null. |
currencyCode | Currency codes retain their original price-type keys. For the display price, use sell when priceType is 0, glass when 1, and suggest when 2. |
enableSecondPrice | Whether to display a second price |
attachments / images | Public image metadata and URLs. Hidden images are excluded. |
The public wine response excludes price.purchase, memo, groupId, purchaseDate, place, and history. Hidden images are also excluded.
Display prices and shop information
Shop information includes groupId, groupKey, groupAlias, type, shopName, shopAddress, shopPhone, shopUrl, shopInstagram, shopReservationUrl, description, priceType, threadTypeSettings, and threadTypes. Contact fields and the description may be null.
priceType is 0 for the selling price, 1 for the glass price, and 2 for the suggested retail price. price.sell contains the selected display price. currencyCode keys retain their original price types.
When enableSecondPrice is true and priceType is not 0, price.glass contains the original selling price for use as a second price. threadTypeSettings is DEFAULT or CUSTOM. threadTypes maps wine types to display names, with null for unset names.
Tags
Tags include tagId, label, typeId, isSecret, useQty, and hasThread. An unset typeId becomes 0; hasThread may be null. useQty counts threads using the tag and may differ from the public wine list count. Exclude tags with isSecret set to true from public interfaces.
Errors and caching
- 403: Unknown or unpublished groupKey, or nonexistent or deleted threadId.
- 400: threadId is not an integer.
- 503: Temporarily unavailable, for example during maintenance.
This is an example 403 response for an unknown or unpublished groupKey. A nonexistent threadId returns a different error message.
{"statusCode":403,"message":"正常なリクエストではありません"}Lists and nonempty wine detail responses return Cache-Control: public, max-age=60, s-maxage=60. Caching may delay changes to stock, prices, and publication settings. Tags, shop information, and empty details do not receive this 60-second cache setting.
Browser requests also work without authentication headers. Reuse cached responses when polling and avoid unnecessarily frequent requests.