關聯式商品目錄結構定義

這個頁面說明你提供給 Google 的訂購端到端資料動態饋給 (餐飲目錄規格) 格式。 如需機器可讀取的資訊版本，您可以下載 JSON 結構定義。

一般規定

實體必須以結構化方式呈現，在動態饋給中每個實體一行 (實體以換行字元分隔)。為方便閱讀，本頁的 JSON 範例並未遵循該結構。不過，你必須在傳送動態饋給時遵循該結構。舉例來說，選單實體的結構必須像以下程式碼一樣：

{"@type": "Menu","name": "Coffee Shop A","@id": "1535"}

每個 `Restaurant` 實體可能有兩個 Service 實體 (分別對應 `DELIVERY` 和 `TAKEOUT` 服務類型)。每個 `Service` 實體只能有一個 `Menu` 實體。

任何子實體都可以在多家餐廳重複使用。

JSON 值規範

類型強制轉換

只要值可強制轉換為必要類型，JSON 值的類型就可能與結構定義中定義的類型不同。舉例來說，字串屬性可接受字串和整數值做為輸入內容。同樣地，只要字串可解析為有效的整數，整數屬性就能接受字串值。

類型強制轉換也適用於重複的屬性。重複屬性可接受值做為輸入內容，不必放在括號 [] 內。舉例來說，OperationHours.serviceId 屬性會同時接受 "service_id" 和 ["service_id"] 做為有效輸入內容。

DateTime 和時間值

DateTime 是以 schema.org 類型為依據，除非另有說明，否則必須遵循 ISO 8601 格式，並包含日期、時間和時區。請使用下列語法設定 DateTime：

// DateTime format:
YYYY-MM-DDTHH:MM:SS[∓HH:MM|Z]

例如：

2017-05-01T06:30:00-07:00 // UTC minus 7 hours
2017-05-01T06:30:00Z  // UTC time zone. The optional "Z" suffix represents the UTC time zone.

Time 是特定餐廳或服務地點的時區當地時間，也以 schema.org 類型為依據，且必須遵循 ISO 8601 格式。時間使用以下語法：

// Time format:
THH:MM:SS

例如：

T08:08:00 // 8:08 AM

指定 DateTime 或 Time 時，請注意下列事項：

  • 時間前方的「T」字元為格式一部分，且為必填項目。
  • 您必須為 DATETIME 指定時區。TIME 不需要這項資訊。
  • 時間必須以餐廳或服務的當地時間指定。

餐廳資料

餐廳 (必填)

實作所需的實體。描述餐廳。

下表列出 Restaurant 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Restaurant
@id String

必填。

餐廳或外送服務供應商的專屬 ID。

範例：restaurant_1
name String

必填。

餐廳名稱。

範例：Foo
description String

餐廳說明。

範例：Best seafood in town
url 網址

代表餐廳的網址。餐廳網域優先於集結網站網域。

範例：http://www.provider.com/somerestaurant
sameAs 網址

餐廳的官方網站。

範例：http://www.provider2.com/somerestaurant
telephone String

餐廳的電話號碼。

範例：+12345665898
streetAddress String

必填。

餐廳的街道地址。

範例：12345 Bar Avenu
addressLocality String

必填。

縣市或城市。

範例：San Francisco
addressRegion String

必填。

區域或州/省。

範例：CA
postalCode String

必填。

郵遞區號。

範例：94124
addressCountry String

必填。

由兩個英文字母組成的 ISO 3166-1 alpha-2 國家/地區代碼。

範例：US
latitude Number

緯度度數。值的範圍限制為 [[-90, 90]]。精確度至少要達第 5 位小數。

範例：35.7392607
longitude Number

經度度數。值的範圍限制為 [[-180, 180]]。 精確度至少要達第 5 位小數。

範例：-120.3895522
dealId List<String>

餐廳適用的 Deal。
imprint String

餐廳資訊欄是餐廳的其他資訊，例如法定名稱、法定地址和登記號碼。您可以使用「<%>」格式設定這項資訊。

範例：

Three Brothers Tacos
123 FooSt
Mountain View
CA 94041, United States
email: contact@threebrotherstacos.com

Commercial Register: 123456789
economicOperator String

與餐廳相關的經濟運營商資訊 (如適用)。這項資訊會顯示在「交易商資訊」部分。您可以使用「""」設定文字格式。

範例：

XYZ Corp
123 Main Street
555-555-5555
dateModified ISO 時間戳記

餐廳實體動態饋給的上次修改日期和時間，採 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 Restaurant 元素：

範例

{
  "@type": "Restaurant",
  "@id": "10824",
  "name": "Pronto Wood Fired Pizzeria",
  "url": "https://www.provider.com/pronto-wood-fired-pizzeria",
  "telephone": "+16503659978",
  "streetAddress": "2560 El Camino Real",
  "addressLocality": "Palo Alto",
  "addressRegion": "CA",
  "postalCode": "94061",
  "addressCountry": "US",
  "latitude": 37.472842,
  "longitude": -122.217144
}

交易

可套用至購物車的折扣類型。

下表列出 Deal 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Deal
@id String

必填。

交易的專屬 ID。

範例：FREEDELIVERY
dealCode String

必填。

每個合作夥伴的每筆交易專屬 ID。這組 ID 必須專門用來識別促銷系統中的特惠。Google 會在 CheckoutRequest 的 promotions.coupon 欄位中傳送這個 ID 供你驗證。

範例：ADETRE23
applicableServiceType List<ServiceType>

這筆交易適用的服務。預設會假設交易適用於所有人。
eligibleMaxOrders 整數

只有在使用者過去成功下單次數少於或等於這項數值時，這筆交易才符合資格。
availabilityId List<String>

可用性實體的 @id 值，可提供選單部分可用時間的詳細資料。

範例：[ "availability_1" ]
isDisabled 布林值

這會覆寫其他有效性檢查。
dealType DealType

必填。

要套用折扣的優惠類別。這個類別可以是整個購物車的總金額、服務費或運費。
priceCurrency String

discount is defined 為必要屬性。

eligibleTransactionVolumeMin is defined 為必要屬性。

折扣的幣別 (以 3 個英文字母組成，採 ISO 4217 格式)。

範例：USD
eligibleTransactionVolumeMin Number

這項促銷活動適用的交易金額。
termsOfServiceUrl 網址

必填。

可供人類閱讀的服務條款說明文件。
dateModified ISO 時間戳記

交易實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00
必須提供下列其中一個屬性組合。
discount 群組 1 Number

折扣的值，以數字表示。
discountPercentage 群組 2 Number

折扣占原價的百分比。

以下範例顯示 Deal 元素：

範例 1

{
  "@type": "Deal",
  "@id": "ONEDOLLARFEE",
  "dealCode": "THREEDOLLARFEE",
  "dealType": "CART_OFF",
  "availabilityId": [
    "availability_may2020"
  ],
  "termsOfServiceUrl": "http://www.provider.com/onedollardeal",
  "applicableServiceType": [
    "TAKEOUT"
  ],
  "discount": 3,
  "priceCurrency": "USD"
}

範例 2

{
  "@type": "Deal",
  "@id": "10PERCOFF",
  "dealCode": "10PERCOFF",
  "dealType": "CART_OFF",
  "availabilityId": [
    "availability_weekdays_evening"
  ],
  "termsOfServiceUrl": "http://www.provider.com/deal",
  "discountPercentage": 10,
  "priceCurrency": "USD"
}

範例 3

{
  "@type": "Deal",
  "@id": "FREEDELIVERY",
  "dealCode": "FREEDELIVERY",
  "dealType": "DELIVERY_OFF",
  "availabilityId": [
    "availability_may"
  ],
  "applicableServiceType": [
    "DELIVERY"
  ],
  "termsOfServiceUrl": "http://www.provider.com/free_delivery_deal",
  "discountPercentage": 100,
  "eligibleTransactionVolumeMin": 25,
  "priceCurrency": "USD"
}

服務資料

服務 (必填)

說明餐廳的訂餐服務詳細資料。Service 是實作所需的實體。

下表列出 Service 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Service
@id String

必填。

執行服務的 ID。

範例：service_1
serviceType ServiceType

必填。

提供的服務類型。可能的值為「DELIVERY」或「TAKEOUT」。

範例：DELIVERY
restaurantId String

必填。

與這項服務實體相關聯的餐廳實體 @id 值。

範例：restaurant_1
menuId String

必填。

與此服務實體相關聯的 Menu 實體的 @id 值。

範例：menu_1
dateModified ISO 時間戳記

服務實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式。

範例：2017-01-02T00:00:00-07:00
isDisabled 布林值

指出實體是否已停用。只有在因意外事件而必須停用實體，且不知道服務何時會重新啟用時，才使用這類型 (例如，不要在假日期間使用)。

範例：true
servingConfig ServingConfig

服務的供應設定，用於控制各種功能，例如停用宣傳小工具等。
actionLinkUrl String

包含外送/外帶服務的網址，會在從端對端餐點訂購體驗遷移至重新導向時使用。

以下範例顯示 Service 元素：

範例 1

{
  "@type": "Service",
  "@id": "10824/takeout",
  "serviceType": "TAKEOUT",
  "menuId": "10824",
  "restaurantId": "10824",
  "actionLinkUrl": "https://www.rwgpartnerwebsite.com/foodorderpickup/merchant_foepa_3"
}

範例 2

{
  "@type": "Service",
  "@id": "10824/delivery",
  "serviceType": "DELIVERY",
  "menuId": "10824",
  "restaurantId": "10824",
  "actionLinkUrl": "https://www.rwgpartnerwebsite.com/foodorderdelivery/merchant_foepa_3"
}

ServiceArea

說明可送餐的地理區域。如果相關聯的 Service 實體將 serviceType 設為「DELIVERY」，就必須實作這個實體。

下表列出 ServiceArea 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：ServiceArea
@id String

必填。

服務區域的專屬 ID。

範例：service_area_1
serviceId List<String>

必填。

與這個 ServiceArea 實體相關聯的 Service 實體 @id 值。

範例：[ "service_1" ]
dateModified ISO 時間戳記

ServiceArea 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00
exclude 布林值

將這個服務範圍從總運送區域中排除。舉例來說，您可以將郵遞區號排除在較大的多邊形區域之外。
必須提供下列其中一個屬性組合。
polygon 群組 1 List<String>

多邊形或多邊形集合，以一系列以空格分隔的三個或更多點表示。建議第一個和最後一個點相同，但這並非必要。 多邊形或多邊形集合中的每個點都由緯度點和經度點定義。您也必須以逆時針方向指定點。

範例：[ "37.806000 -122.425592 37.775849 -122.419043 37.795547 -122.394046 37.808747" ]
geoMidpointLatitude 群組 2 Number

表示圓形區域中心的緯度座標。

範例：37.806000
geoMidpointLongitude 群組 2 Number

表示圓形區域中心的經度座標。

範例：-122.425592
geoRadius 群組 2 整數

表示 CIRCLE 區域的半徑 (以公尺為單位)。

範例：10000
postalCode 群組 3 String

表示郵遞區號。

範例：91234
addressCountry 群組 3 String

表示由兩個英文字母組成的 ISO 3166-1 alpha-2 國家/地區代碼

範例：US

以下範例顯示 ServiceArea 元素：

範例

{
  "@type": "ServiceArea",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "polygon": [
    "37.4818562 -122.25801303 37.48247836 -122.25801303 37.48434484 -122.25621319 37.48621133 -122.25424681 37.49181077 -122.24704744 37.49305509 -122.24541414 37.49429942 -122.2436143 37.49803238 -122.23821477 37.49803238 -122.21285044 37.49367726 -122.15885517 37.49056645 -122.15722187 37.48621133 -122.15542202 37.48558917 -122.15525548 37.4818562 -122.15525548 37.43191387 -122.17865343 37.43191387 -122.23444854"
  ]
}

OperationHours (必填)

說明使用者可以存取流程並下達即時或未來訂單的訂購時段。必須實作 OperationHours，預設值為代表所有日子和時段的運作狀態。

OperationHours opens 和 closes 屬性可指定線上系統的營業時間，讓使用者下單。在這些線上系統營業時間內，請使用 ServiceHours 指定開店和打烊時間，以便處理使用者的訂單。

時間必須以服務的當地時間指定。請勿在 opens 值中加入時區。如果指定時區，Google 會忽略這項資訊。詳情請參閱「日期時間和時間格式」。

下表列出 OperationHours 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：OperationHours
@id String

必填。

實體的專屬 ID，描述使用者可以存取流程並下達即時/未來訂單的訂購時段。

範例：operation_hour_1
serviceId List<String>

必填。

與此 OperationHours 實體相關聯的 Service 實體 @id 值。

範例：[ "service_1" ]
opens ISO 時間 (本地)

以 ISO 格式表示特定時間，從這個時間開始，使用者就能下單。

範例：T00:00
closes ISO 時間 (本地)

以 ISO 格式表示特定時段，超過該時段後，使用者就無法下單。

範例：T16:00
dayOfWeek List<DayOfWeek>

列出這些營業時間適用的星期幾。可接受的值包括「MONDAY」、「TUESDAY」、「WEDNESDAY」、「THURSDAY」、「FRIDAY」、「SATURDAY」和「SUNDAY」。

範例：[ "MONDAY", "TUESDAY" ]
validFrom ISO 時間戳記

isSpecialHour = true 為必要屬性。

ISO 時間戳記，指出使用者可存取流程並下達立即/未來訂單的訂購時段開始時間。

範例：2017-01-01T00:00:00-07:00
validThrough ISO 時間戳記

isSpecialHour = true 為必要屬性。

ISO 時間戳記，表示訂購時段的結束時間，超過這個時間，使用者就無法存取流程並下達立即/未來訂單。

範例：2017-01-02T00:00:00-07:00
isSpecialHour 布林值

布林值，指出是否要使用特殊營業時間。可接受的值為「false」和「true」。

範例：False
dateModified ISO 時間戳記

OperationHours 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 OperationHours 元素：

範例 1

{
  "@type": "OperationHours",
  "@id": "10824/deliveryOh",
  "serviceId": [
    "10824/delivery"
  ],
  "isSpecialHour": false
}

範例 2

{
  "@type": "OperationHours",
  "@id": "10824/takeoutOh",
  "serviceId": [
    "10824/takeout"
  ],
  "isSpecialHour": false
}

ServiceHours (必填)

說明使用者可選擇履行時段 (盡快或未來時段) 的履行時間。必須實作 ServiceHours。

OperationHours opens 和 closes 屬性可指定線上系統的營業時間，讓使用者下單。在這些線上系統營業時間內，請使用 ServiceHours 指定開店和打烊時間，以便處理使用者的訂單。

時間必須以服務的當地時間指定。請勿在 opens 值中加入時區。如果指定時區，Google 會忽略這項資訊。詳情請參閱「日期時間和時間格式」。

下表列出 ServiceHours 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：ServiceHours
@id String

必填。

實體的專屬 ID，用於說明使用者可選擇的服務時段，例如盡快或未來時段。

範例：service_hour_1
orderType OrderType

必填。

字串，指出服務時段是否適用於 ASAP 或提前訂單。可接受的值為「ASAP」和「ADVANCE」。

範例：ASAP
serviceId List<String>

必填。

與這個 ServiceHours 實體相關聯的 Service 實體 @id 值。

範例：[ "service_1" ]
operationHoursId List<String>

isSpecialHour = false 為必要屬性。

與這個 ServiceHours 實體相關聯的 OperationHours 實體 @id 值。

範例：[ "operation_hour_1" ]
opens ISO 時間 (本地)

以 ISO 格式表示特定時間，從這個時間開始，系統即可開始處理使用者的訂單。

範例：T00:00
closes ISO 時間 (本地)

以 ISO 格式表示特定時間，超過該時間就無法處理使用者的訂單。

範例：T16:00
dayOfWeek List<DayOfWeek>

這些營業時間適用的星期幾清單。

範例：[ "MONDAY", "TUESDAY" ]
validFrom ISO 時間戳記

isSpecialHour = true 為必要屬性。

ISO 時間戳記，指出使用者可存取流程並下達立即/未來訂單的訂購時段開始時間。

範例：2017-01-01T00:00:00-07:00
validThrough ISO 時間戳記

isSpecialHour = true 為必要屬性。

ISO 時間戳記，表示訂購時段的結束時間，超過這個時間，使用者就無法存取流程並下達立即/未來訂單。

範例：2017-01-02T00:00:00-07:00
isSpecialHour 布林值

布林值，指出是否要使用特殊營業時間。可接受的值為「false」和「true」。

範例：False
leadTimeMin 整數

下單後，預估最快送達/取件時間 (以分鐘為單位)。強烈建議您設定這個屬性。

範例：60
leadTimeMax 整數

下單後，預估送達/取件時間的上限 (以分鐘為單位)。我們強烈建議您設定這個屬性。

範例：70
advanceBookingRequirementMin 整數

orderType = "ADVANCE" 為必要屬性。

提前訂單可執行的時間，從下單時間起算的最短分鐘數。 舉例來說，如果提前預訂的訂單需要至少 60 分鐘才能完成，則 advanceBookingRequirementMin 為 60。

範例：15
advanceBookingRequirementMax 整數

orderType = "ADVANCE" 為必要屬性。

從下單時間算起，提前訂單可執行的時間上限 (分鐘)。 舉例來說，如果預訂訂單的履行時間不得超過 2 天，則 advanceBookingRequirementMax 的值為 2880。

範例：10080
advanceBookingSlotInterval String

orderType = "ADVANCE" 為必要屬性。

兩個連續提前預訂時段之間的間隔時間。 舉例來說，如果營業時間為上午 8 點和晚上 8 點，而 advanceBookingSlotInterval 為 15 分鐘，使用者就能選擇上午 8 點、上午 8 點 15 分、上午 8 點 30 分、上午 8 點 45 分，以此類推，直到晚上 8 點。播放時間必須指定為 ISO 時段時間長度。例如：「PT15M」表示每 15 分鐘一次。

範例：PT15M
dateModified ISO 時間戳記

ServiceHours 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 ServiceHours 元素：

範例 1

{
  "@type": "ServiceHours",
  "@id": "613741/delivery",
  "orderType": "ASAP",
  "serviceId": [
    "10824/delivery"
  ],
  "opens": "T00:00",
  "closes": "T00:00",
  "isSpecialHour": true,
  "validFrom": "2017-12-25T00:00:00-07:00",
  "validThrough": "2017-12-25T23:59:00-07:00"
}

範例 2

{
  "@type": "ServiceHours",
  "@id": "10824/takeoutSh_0",
  "orderType": "ASAP",
  "serviceId": [
    "10824/takeout"
  ],
  "operationHoursId": [
    "10824/takeoutOh"
  ],
  "opens": "11:00",
  "closes": "21:00",
  "dayOfWeek": [
    "MONDAY",
    "TUESDAY",
    "WEDNESDAY",
    "THURSDAY"
  ],
  "isSpecialHour": false
}

費用

說明費用。如果相關聯的 Service 實體將 serviceType 設為「DELIVERY」，則必須使用 Fee，並將 feeType 設為「DELIVERY」。

下表列出 Fee 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Fee
@id String

必填。

描述費用的實體專屬 ID。

範例：service_fee_1
serviceId List<String>

必填。

與此費率實體相關聯的服務實體 @id 值。

範例：[ "service_1" ]
feeType FeeType

必填。

字串，指出費用是否適用於運送或服務訂單。可接受的值為「DELIVERY」和「SERVICE」。

範例：DELIVERY
priceCurrency String

必填。

包含 3 個英文字母的 ISO 4217 貨幣代碼。

範例：USD
basePrice Number

費用的底價，適用於使用 percentageOfCart 或 pricePerMeter 時。

範例：2.0
minPrice Number

使用 percentageOfCart 或 pricePerMeter 時的最低費率和費率上限值。

範例：2.0
maxPrice Number

使用 percentageOfCart 或 pricePerMeter 時的最高費用，可限制費用值。

範例：10.0
eligibleRegion List<String>

費用適用的地理/政治區域的 ServiceArea @id。只有在運費因地區而異時，才需要使用這項屬性。

範例：[ "service_area_1" ]
eligibleTransactionVolumeMin Number

這項費用規範適用的最低交易量，以貨幣單位表示。

範例：50
eligibleTransactionVolumeMax Number

此費率規格適用的最高交易量，以貨幣單位表示。舉例來說，如果訂單量超過特定數量，就不會收取費用。

範例：10
validFrom ISO 時間戳記

表示費用生效開始時間的 ISO 時間戳記。

範例：2017-01-01T00:00:00-07:00
validThrough ISO 時間戳記

表示結束時間的 ISO 時間戳記，超過這個時間後費用就會失效。

範例：2017-01-02T00:00:00-07:00
dateModified ISO 時間戳記

費率實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00
priority Number

正值，非零值。如果使用者的購物車適用多項費用，優先順序最高的費用會優先於較低的費用。如果提供這個欄位，系統一律會優先採用計算出的優先順序，而非這個欄位。

範例：3
必須提供下列其中一個屬性組合。
price 群組 1 Number

費用價格。如果價格並非固定值，可以提供 minPrice 和 maxPrice 取代 price。

範例：1.5
percentageOfCart 群組 2 Number

以購物車價值百分比計算的費用。可接受的值是介於 0 和 100 之間的浮點值 (含 0 和 100)。

範例：9.00
pricePerMeter 群組 3 Number

與使用者之間的距離每公尺費用。舉例來說，如果與使用者的距離為 5 公里，費率為 $0.001 美元，則使用者費用為 $5 美元。

範例：0.001

以下範例顯示 Fee 元素：

範例 1

{
  "@type": "Fee",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "feeType": "DELIVERY",
  "priceCurrency": "USD",
  "eligibleRegion": [
    "28427"
  ],
  "eligibleTransactionVolumeMin": 20,
  "price": 5
}

範例 2

{
  "@type": "Fee",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "feeType": "DELIVERY",
  "priceCurrency": "USD",
  "eligibleRegion": [
    "28427"
  ],
  "eligibleTransactionVolumeMin": 20,
  "pricePerMeter": 0.0005,
  "basePrice": 4
}

範例 3

{
  "@type": "Fee",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "feeType": "DELIVERY",
  "priceCurrency": "USD",
  "eligibleRegion": [
    "28427"
  ],
  "eligibleTransactionVolumeMin": 20,
  "pricePerMeter": 0.0005,
  "basePrice": 4,
  "minPrice": 5,
  "maxPrice": 50
}

示例 4

{
  "@type": "Fee",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "feeType": "DELIVERY",
  "priceCurrency": "USD",
  "eligibleRegion": [
    "28427"
  ],
  "eligibleTransactionVolumeMin": 20,
  "percentageOfCart": 5,
  "basePrice": 4
}

範例 5

{
  "@type": "Fee",
  "@id": "28427",
  "serviceId": [
    "10824/delivery"
  ],
  "feeType": "DELIVERY",
  "priceCurrency": "USD",
  "eligibleRegion": [
    "28427"
  ],
  "eligibleTransactionVolumeMin": 20,
  "percentageOfCart": 5,
  "basePrice": 4,
  "minPrice": 5,
  "maxPrice": 50
}

實作所需的實體。說明選單。

下表列出 Menu 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Menu
@id String

必填。

選單的專屬 ID。

範例：menu_1
name String

使用者瀏覽選單時，可識別選單的文字。

範例：Foo
disclaimer String

免責事項。例如營養資訊揭露和過敏原揭露。

範例：Items may contain peanuts.
disclaimerUrl 網址

指向免責事項詳細資料頁面的網址。
dateModified ISO 時間戳記

菜單實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 Menu 元素：

{
  "@type": "Menu",
  "@id": "10824"
}

要實作的選用實體。說明選單中的特定部分。

下表列出 MenuSection 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：MenuSection
@id String

必填。

選單部分的專屬 ID。

範例：menu_section_1
menuId List<ReverseReference>

與此 MenuSection 實體相關聯的 Menu 實體 @id 值。

範例：[ { "@id": "menu_id", "displayOrder": 4 } ]
menuSectionId List<String>

與此 MenuSection 實體相對應的子 MenuSection 實體的 @id 值清單。

重要事項：您只能使用 menuSectionId 或 parentMenuSectionId(in child) 參照。

範例：[ "child_menu_section_1", "child_menu_section_2" ]
parentMenuSectionId List<ReverseReference>

與此 MenuSection 實體相關聯的父項 MenuSection 實體的 @id 值。

重要事項：您只能使用 parentMenuSectionId 或 menuSectionId(in parent) 參照。

範例：[ { "@id": "parent_menu_section_id", "displayOrder": 4 } ]
name String

必填。

使用者瀏覽選單時，可識別 MenuSection 的文字。

範例：Foo
description String

菜單專區的說明。

範例：Example menu section description that helps users.
image 網址

選單專區圖片的網址。

範例：https://provider.com/someimage
menuItemId List<String>

與此 MenuSection 實體相對應的 MenuItem 實體 @id 值清單。

重要事項：您只能使用 menuItemId 或 MenuItem.parentMenuSectionId 參照。

範例：[ "menu_item1", "menu_item2" ]
parentMenuItemId List<ReverseReference>

與此 MenuSection 實體相對應的父項 MenuItem 實體的 @id 值清單。

重要事項：您只能使用 parentMenuItemId 或 MenuItem.menuAddOnId 參照。

範例：[ { "@id": "parent_menu_item_id", "displayOrder": 4 } ]
parentMenuItemOptionId List<ReverseReference>

與此 MenuSection 實體相對應的父項 MenuItemOption 實體的 @id 值清單。

重要事項：您只能使用 parentMenuItemOptionId 或 MenuItemOption.menuAddOnId 參照。

範例：[ { "@id": "parent_menu_item_option_id", "displayOrder": 4 } ]
eligibleQuantityMax 整數

可在外掛程式部分選取的外掛程式數量上限。

範例：5
eligibleQuantityMin 整數

在外掛程式部分中應選取的外掛程式數量下限。

範例：1
defaultItemId List<String>

這是一個 @id 參照 MenuItem 實體的清單，系統會預設為 MenuSection 外掛程式的使用者預先選取這些實體。使用者可以變更最終選項。如果未指定 defaultItemId，系統不會預先選取任何 MenuItem。

範例：[ "item1", "item2" ]
availabilityId List<String>

可用性實體的 @id 值，可提供選單部分可用時間的詳細資料。

範例：[ "menu_availability_1" ]
numberOfFreeAddOns 整數

表示使用者可免費選取的加購項目數量。僅適用於加購選單專區。

範例：3
dateModified ISO 時間戳記

MenuSection 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00
applicableServiceType List<ServiceType>

適用於此 MenuSection 的服務。預設會假設 MenuSection 適用於所有人。
offeredById List<String>

這個 MenuSection 可用的 Restaurant 實體的 @id 值。預設會假設 MenuSection 可在所有位置使用。

範例：[ "restaurant_id_1", "restaurant_id_55" ]

以下範例顯示 MenuSection 元素：

{
  "@type": "MenuSection",
  "@id": "853705",
  "menuId": [
    {
      "@id": "10824",
      "displayOrder": 853705
    }
  ],
  "menuSectionId": [
    12345,
    43645
  ],
  "name": "Pasta",
  "applicableServiceType": [
    "TAKEOUT"
  ],
  "offeredById": [
    "italian_restaurant_location_1"
  ]
}
 
{
  "@type": "MenuSection",
  "@id": "427484",
  "menuId": [
    {
      "@id": "4287",
      "displayOrder": 964376
    }
  ],
  "menuItemId": [
    46784,
    42728
  ],
  "name": "Burger",
  "applicableServiceType": [
    "TAKEOUT",
    "DELIVERY"
  ]
}
 
{
  "@type": "MenuSection",
  "@id": "3138486",
  "name": "Choose a side:",
  "parentMenuItemId": [
    {
      "@id": "6680295",
      "displayOrder": 3138486
    }
  ],
  "eligibleQuantityMax": "5",
  "numberOfFreeAddOns": "2"
}
 
{
  "@type": "MenuSection",
  "@id": "3138482",
  "name": "Additional Pizza Toppings",
  "parentMenuItemId": [
    {
      "@id": "6680246",
      "displayOrder": 3138482
    }
  ],
  "eligibleQuantityMax": "3"
}

可用性

要實作的選用實體。說明 MenuSection 實體的服務時間範圍。

下表列出 Availability 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：Availability
@id String

必填。

描述選單部分可用性的實體專屬 ID。

範例：menu_section_avail_1
availabilityStarts ISO 時間 (本地)

ISO 時間戳記，表示可用選單區段的開始時間。

範例：T00:00
availabilityEnds ISO 時間 (本地)

ISO 時間戳記，表示結束時間，超過這個時間後，菜單區塊的供應狀態就會失效。

範例：T16:00
availableDay List<DayOfWeek>

列出菜單區塊供應時間的星期幾。

範例：[ "MONDAY", "TUESDAY" ]
validFrom ISO 時間戳記

ISO 時間戳記，指示選單部分供應時間的開始時間。

範例：2017-01-01T00:00:00-07:00
validThrough ISO 時間戳記

ISO 時間戳記，表示結束時間，超過這個時間，菜單區塊的供應狀態就會失效。

範例：2017-01-02T00:00:00-07:00
dateModified ISO 時間戳記

供應情形實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 Availability 元素：

範例

{
  "@type": "Availability",
  "@id": "85343705",
  "availabilityStarts": "06:00",
  "availabilityEnds": "22:30",
  "availableDay": [
    "SATURDAY",
    "SUNDAY"
  ]
}

實作所需的實體。說明 Menu 實體中的項目。

下表列出 MenuItem 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：MenuItem
@id String

必填。

選單項目的專屬 ID。

範例：menu_item_1
name String

必填。

使用者瀏覽選單時，可識別 MenuItem 的文字。

範例：Foo
description String

選單項目的說明。

範例：Foo
image 網址

菜單項目圖片的網址。

範例：http://someprovider.com/someimage
parentMenuSectionId List<ReverseReference>

與此 MenuItem 實體相對應的父項 MenuSection 實體的 @id 值清單。

重要事項：您只能使用 parentMenuSectionId 或 MenuSection.menuItemId 參照。

範例：{ "@id": "menu_section_parent_id", "displayOrder": 4 }
menuAddOnId List<String>

來自附加內容區段的 MenuSection 實體 @id 值清單，對應至此 MenuItem 實體。

重要事項：您只能使用 menuAddOnId 或 MenuSection.parentMenuItemId 參照。

範例：menu_addon_1
nutrition NutritionInformation

餐點的營養資訊，尤其是卡路里。

範例：{ "calories": "120-150 Cal" }
allergen List<Allergen>

這個 MenuItem 的過敏原。

範例：[ { "allergenType": "PEANUTS", "levelOfContainment": "MAY_CONTAIN" } ]
additive List<Additive>

此 MenuItem 的加成物。

範例：[ { "additiveName": "Sodium nitrite", "levelOfContainment": "CONTAINS" } ]
suitableDiet List<RestrictedDiet>

菜餚符合所述飲食限制。

範例：[ "DIABETIC", "GLUTEN_FREE" ]
depositInfo DepositInfo

這個 MenuItem 的包裝和回收資訊。

範例：{ "depositCode": "RECYCLABLE", "depositValue": "0.05", "depositValueCurrency": "USD" }
numberOfServings 整數

特定選單項目的份量數量。

範例：2
dateModified ISO 時間戳記

MenuItem 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 MenuItem 元素：

{
  "@type": "MenuItem",
  "@id": "18931508",
  "name": "Sauteed Baby Spinach",
  "parentMenuSectionId": [
    {
      "@id": "3138479",
      "displayOrder": 18931508
    }
  ]
}
 
{
  "@type": "MenuItem",
  "@id": "18931508",
  "name": "Hamburger",
  "parentMenuSectionId": [
    {
      "@id": "4645747",
      "displayOrder": 12345
    }
  ],
  "nutrition": {
    "calories": "400 cal"
  },
  "allergen": [
    {
      "allergenType": "GLUTEN",
      "levelOfContainment": "CONTAINS"
    }
  ],
  "additive": [
    {
      "additiveName": "Sodium nitrite",
      "levelOfContainment": "CONTAINS"
    }
  ],
  "suitableDiet": [
    "DIABETIC",
    "LOW_FAT"
  ]
}

要實作的選用實體。說明使用者在選擇餐點/套餐時必須做出的選擇。使用者必須選取選項，否則系統會將訂單視為無效 (例如使用者必須選擇小、中或大披薩)。

下表列出 MenuItemOption 類型的屬性：

屬性 類型 說明
@type Const

值：MenuItemOption
@id String

必填。

選單項目選項的專屬 ID。

範例：menu_item_1_option
menuItemId ReverseReference

必填。

與這個 MenuItemOption 實體相關聯的 MenuItem 實體的 @id 值。

範例：{ "@id": "menu_item_1", "displayOrder": 4 }
optionType OptionType

字串，指出選單項目選項是否依尺寸、選項或披薩配料分類。可接受的值包括「SIZE」、「OPTION」和「PIZZA_SIDE」。"SIZE"：MenuItemOption 的大小。例如小、中或大。「OPTION」：除了尺寸以外的任何變化版本 (例如沙拉或三明治)。如果您無法區分「SIZE」和「OPTION」，請使用「OPTION」。「PIZZA_SIDE」：專屬於披薩：例如這個 MenuItemOption 只適用於部分/整個披薩 (例如左側、右側或整個披薩的蘑菇配料)。

範例：SIZE
value 字串或 PizzaSide

optionType is defined 為必要屬性。

字串值或列舉值。列舉值專屬於 PIZZA_SIDE 選項類型。
applicableParentOptionValue String

字串，其中包含可使用此選項的父項選項值。

範例：Small
menuAddOnId List<String>

來自附加內容區段的 MenuSection 實體 @id 值清單，對應至此 MenuItemOption 實體。

重要事項：您只能使用 menuAddOnId 或 MenuSection.parentMenuItemId 參照。

範例：menuAddOnId
nutrition NutritionInformation

餐點的營養資訊，尤其是卡路里。

範例：{ "calories": "120-150 Cal" }
allergen List<Allergen>

這個 MenuItem 的過敏原。

範例：{ "allergenType": "PEANUTS", "levelOfContainment": "MAY_CONTAIN" }
additive List<Additive>

此 MenuItem 的加成物。

範例：{ "additiveName": "Sodium nitrite", "levelOfContainment": "CONTAINS" }
depositInfo DepositInfo

這個 MenuItem 的包裝和回收資訊。

範例：{ "depositCode": "RECYCLABLE", "depositValue": "0.05", "depositValueCurrency": "USD" }
numberOfServings 整數

特定選單項目選項中可供選擇的份量數量。

範例：2
dateModified ISO 時間戳記

MenuItemOption 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00

以下範例顯示 MenuItemOption 元素：

{
  "@type": "MenuItemOption",
  "@id": "56177944",
  "menuItemId": {
    "@id": "18930213",
    "displayOrder": 1234
  },
  "optionType": "PIZZA_SIDE",
  "value": "PIZZA_SIDE_LEFT"
}
 
{
  "@type": "MenuItemOption",
  "@id": "56177944",
  "menuItemId": {
    "@id": "18930213",
    "displayOrder": 1234
  },
  "applicableParentOptionValue": "Small Pizza"
}

實作所需的實體。說明 MenuItem 或 MenuItemOption 實體的優惠。

下表列出 MenuItemOffer 類型的屬性：

屬性 類型 說明
@type Const

必填。

值：MenuItemOffer
@id String

必填。

選單項目商品的專屬 ID。

範例：menu_item_offer
sku String

必填。

菜單商品的 ID。在多個餐點商品實體中，sku 值可能相同，也可能不同。我們會在向你發出 API 呼叫時，依序設定 SKU 值。

範例：Menu_item_offer_sku
price Number

必填。

菜單商品的價格。

範例：2.5
priceCurrency String

必填。

包含 3 個英文字母的 ISO 4217 貨幣代碼。

範例：USD
availabilityId List<String>

可用性實體的 @id 值，可提供菜單商品可供供應的詳細資訊。

範例：[ "menu_availability_1" ]
eligibleQuantityMin Number

MenuItemOffer 有效的最低訂購數量。

範例：1
eligibleQuantityMax Number

MenuItemOffer 有效的訂購數量上限。

範例：25
inventoryLevel Number

與此 MenuItemOffer 相對應的商品目前的商品目錄水準。

範例：10
dateModified ISO 時間戳記

MenuItemOffer 實體動態饋給的上次修改日期和時間，採用 ISO 時間戳記格式，但類型為字串。

範例：2017-01-02T00:00:00-07:00
applicableServiceType List<ServiceType>

適用於此 MenuItemOffer 的服務。預設會假設 MenuItemOffer 適用於所有人。
offeredById List<String>

這個 MenuItemOffer 可用的 Restaurant 實體的 @id 值。預設會假設 MenuItemOffer 可在所有位置使用。

範例：[ "restaurant_id_5", "restaurant_id_26" ]
必須提供下列其中一個屬性組合。
menuItemId 群組 1 String

與這個 MenuItemOffer 實體相關聯的 MenuItem 實體的 @id 值。

範例：menu_item_1
menuItemOptionId 群組 2 String

與這個 MenuItemOffer 實體相關聯的 MenuItemOption 實體的 @id 值。

範例：menu_item_option_1

以下範例顯示 MenuItemOffer 元素：

{
  "@type": "MenuItemOffer",
  "@id": "6680262",
  "sku": "offer-mediterranean-bagel",
  "menuItemId": "896532",
  "price": 15.5,
  "priceCurrency": "USD",
  "applicableServiceType": [
    "DELIVERY"
  ],
  "offeredById": [
    "bagel_shop_location_5"
  ]
}

通用

ReverseReference

下表列出 ReverseReference 類型的屬性：

屬性 類型 說明
@id String

必填。

父系實體的 @id。
displayOrder 整數

必填。

父項中項目的顯示順序。

NutritionInformation

下表列出 NutritionInformation 類型的屬性：

屬性 類型 說明
description String

營養資訊以自由文字格式呈現。例如「含防腐劑」。
calories String

卡路里數量，以 Cal、kcal 或 kJ 為單位，格式如下：值 Cal 或 最小值-最大值 Cal

範例：120.34 Cal
sodiumContent String

鈉含量 (以毫克或公克為單位)，格式如下：值 g 或 最小-最大 g

範例：1200 mg

以下範例顯示 NutritionInformation 元素：

範例

{
  "calories": "120-150 Cal",
  "sodiumContent": "100 mg"
}

過敏原

下表列出 Allergen 類型的屬性：

屬性 類型 說明
allergenType AllergenType

必填。

過敏原類型。
levelOfContainment ContainmentLevel

選單項目中特定過敏原的含量。

以下範例顯示 Allergen 元素：

範例

{
  "allergenType": "PEANUTS",
  "levelOfContainment": "MAY_CONTAIN"
}

加法

下表列出 Additive 類型的屬性：

屬性 類型 說明
additiveName String

必填。

添加物的名稱。
levelOfContainment ContainmentLevel

菜單項目中特定添加物的濃度。

以下範例顯示 Additive 元素：

範例

{
  "additiveName": "Sodium nitrite",
  "levelOfContainment": "CONTAINS"
}

DepositInfo

下表列出 DepositInfo 類型的屬性：

屬性 類型 說明
depositCode DepositCode

存款代碼。
depositValue Number

商品押金的數值，例如回收時的押金。
depositValueCurrency String

訂金價值的幣別

以下範例顯示 DepositInfo 元素：

範例

{
  "depositCode": "RECYCLABLE",
  "depositValue": 0.05,
  "depositValueCurrency": "USD"
}

ServingConfig

服務的供應設定，用於控制各種功能，例如停用宣傳小工具等。

下表列出 ServingConfig 類型的屬性：

屬性 類型 說明
disableOrderInstructions 布林值

隱藏指定訂單操作說明的功能。
disableMenuItemSpecialInstructions 布林值

隱藏在選單項目上指定特殊指示的功能。
disableTipWidget 布林值

隱藏訂購流程中「Place Order」頁面的小費小工具。
disablePromoWidget 布林值

隱藏訂購流程中「下單」頁面的促銷活動小工具。
menuItemSpecialInstructionsMaxLength Number

指定可用於特殊選單項目指令的字元數量上限。
orderInstructionsMaxLength Number

指定訂單指示可包含的字元數量上限。

以下範例顯示 ServingConfig 元素：

範例 1

{
  "disableMenuItemSpecialInstructions": true
}

範例 2

{
  "disableTipWidget": true,
  "disablePromoWidget": true
}

範例 3

{
  "menuItemSpecialInstructionsMaxLength": 250,
  "orderInstructionsMaxLength": 1000
}

列舉

DayOfWeek

DayOfWeek 類型可用的值如下：

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY

ServiceType

ServiceType 類型可用的值如下：

  • DELIVERY
  • TAKEOUT

OrderType

OrderType 類型可用的值如下：

  • ASAP
  • ADVANCE

FeeType

FeeType 類型可用的值如下：

  • DELIVERY
  • SERVICE

OptionType

OptionType 類型可用的值如下：

  • SIZE
  • OPTION
  • PIZZA_SIDE

PizzaSide

PizzaSide 類型可用的值如下：

  • PIZZA_SIDE_LEFT
  • PIZZA_SIDE_RIGHT
  • PIZZA_SIDE_WHOLE

AllergenType

根據 gs1:AllergenTypeCode 所指定的過敏原類型。

AllergenType 類型可用的值如下：

  • ALMONDS
  • ALPHA_ISOMETHYL_IONONE
  • ALCOHOL
  • AMYL_CINNAMAL
  • ANISE_ALCOHOL
  • BARLEY
  • BENZYL_ALCOHOL
  • BENZYL_BENZOATE
  • BENZYL_CINNAMATE
  • BENZYL_SALICYLATE
  • BRAZIL_NUTS
  • BUTYLPHENYL_METHYLPROPIONATE
  • CARROTS
  • CASHEW_NUTS
  • CELERY
  • CEREALS_CONTAINING_GLUTEN
  • CINNAMAL
  • CINNAMYL_ALCOHOL
  • CITRAL
  • CITRONELLOL
  • COCOA
  • CORIANDER
  • CORN
  • COUMARIN
  • CRUSTACEANS
  • EGGS
  • EUGENOL
  • EVERNIA_FURFURACEA
  • EVERNIA_PRUNASTRI
  • FARNESOL
  • FISH
  • GERANIOL
  • GLUTEN
  • HAZELNUTS
  • HEXYL_CINNAMAL
  • HYDROXYCITRONELLAL
  • HYDROXYISOHEXYL_3_CYCLOHEXENE_CARBOXALDEHYDE_ISOEUGENOL_LIMONENE_LINAL
  • KAMUT
  • LACTOSE
  • LUPINE
  • MACADAMIA_NUTS
  • METHYL_2_OCTYNOATE
  • MILK
  • MOLLUSCS
  • MUSTARD
  • NO_DECLARED_ALLERGENS
  • OAT
  • PEANUTS
  • PEAS
  • PECAN_NUTS
  • PISTACHIOS
  • POD_FRUITS
  • QUEENSLAND_NUTS
  • RYE
  • SESAME_SEEDS
  • SOYBEANS
  • SPELT
  • SULPHUR_DIOXIDE
  • TREE_NUTS
  • TREE_NUT_TRACES
  • WALNUTS
  • WHEAT

ContainmentLevel

ContainmentLevel 類型可用的值如下：

  • CONTAINS
  • FREE_FROM
  • MAY_CONTAIN

DepositCode

DepositCode 類型可用的值如下：

  • REUSABLE
  • RECYCLABLE

DealType

要套用折扣的優惠類別。類別可以是整個購物車總金額或運費。

DealType 類型可用的值如下：

  • CART_OFF
  • DELIVERY_OFF

RestrictedDiet

根據 schema.org:RestrictedDiet 的限制飲食類型。

RestrictedDiet 類型可用的值如下：

  • DIABETIC
  • GLUTEN_FREE
  • HALAL
  • HINDU
  • KOSHER
  • LOW_CALORIE
  • LOW_FAT
  • LOW_LACTOSE
  • LOW_SALT
  • VEGAN
  • VEGETARIAN