關聯庫存結構定義

本頁面說明你提供給 Google 的訂購端對端資料動態饋給 (Food Catalog 規格) 格式。 如需機器可讀取的版本，您可以下載 JSON 結構定義。

一般規定

實體的結構必須列入動態饋給中每個實體的一行 (以換行字元分隔)。為了方便閱讀，本頁中的 JSON 範例與這個結構不符。不過，傳送動態饋給時必須遵守這個結構。例如，選單實體的結構必須如以下程式碼：

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

每個「餐廳」實體可能包含兩個 Service 實體，分別用於「DELIVERY」和「TAKEOUT」服務類型。每個「服務」實體只能有一個「Menu」實體。

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

JSON 值規範

類型強制轉換

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

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

日期和時間值

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 缺點

這是必填欄位。

值：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 缺點

這是必填欄位。

值：Deal
@id String

這是必填欄位。

交易的專屬 ID。

範例：FREEDELIVERY
dealCode String

這是必填欄位。

每個夥伴每筆交易的專屬交易 ID。這個 ID 必須可用來識別促銷活動系統中的交易。Google 會將這個 ID 傳送給 CheckoutRequest 的 promotions.coupon 欄位，以供驗證。

範例：ADETRE23
applicableServiceType 清單<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 缺點

這是必填欄位。

值：Service
@id String

這是必填欄位。

執行要求的 ID。

範例：service_1
serviceType ServiceType

這是必填欄位。

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

範例：DELIVERY
restaurantId String

這是必填欄位。

與這個 Service 實體相關的餐廳實體 @id 值。

範例：restaurant_1
menuId String

這是必填欄位。

與這個 Service 實體相關聯的菜單實體 @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 缺點

這是必填欄位。

值：ServiceArea
@id String

這是必填欄位。

服務範圍的專屬 ID。

範例：service_area_1
serviceId List<String>

這是必填欄位。

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

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

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

範例：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 組 整數

指出社交圈區域的近似半徑 (以公尺為單位)。

範例：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 缺點

這是必填欄位。

值：OperationHours
@id String

這是必填欄位。

實體的專屬 ID，用於描述訂購視窗；使用者可存取流程並放置盡快/未來訂單。

範例：operation_hour_1
serviceId List<String>

這是必填欄位。

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

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

以 ISO 格式指出使用者訂單可在哪個時段 (從這個時間點開始訂購)。

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

以 ISO 格式表示使用者在一天中的哪些時段無法下訂單。

範例：T16:00
dayOfWeek 清單<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 布林值

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

範例：False
dateModified ISO 時間戳記

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

範例：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
}

服務時間 (必填)

說明執行要求視窗，使用者可以在其中選擇執行要求運算單元 (ASAP 或未來的運算單元)。必須實作 ServiceHours。

OperationHours opens 和 closes 屬性可指定線上系統的開始和打烊時間，讓使用者下單。在線上系統小時內，使用 ServiceHours 指定能履行使用者訂單的開始和打烊時間。

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

下表列出 ServiceHours 類型的屬性：

屬性 類型 說明
@type 缺點

這是必填欄位。

值：ServiceHours
@id String

這是必填欄位。

實體的專屬 ID，用於描述執行要求視窗，使用者可以選擇執行要求時段，例如「盡快」或「未來的運算單元」。

範例：service_hour_1
orderType OrderType

這是必填欄位。

字串，指出服務時間是否適用於「盡快」或進階訂單。可接受的值為「ASAP」和「ADVANCE」。

範例：ASAP
serviceId List<String>

這是必填欄位。

與這個 ServiceHours 實體相關聯的服務實體 @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 清單<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 布林值

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

範例：False
leadTimeMin 整數

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

範例：60
leadTimeMax 整數

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

範例：70
advanceBookingRequirementMin 整數

orderType = "ADVANCE" 時為必要欄位。

訂單完成訂單所需的最短時間。 舉例來說，如果預付訂單需要至少 60 分鐘出貨，則 preBookingRequirementMin 為 60。

範例：15
advanceBookingRequirementMax 整數

orderType = "ADVANCE" 時為必要欄位。

訂單出貨時間的長度上限 (以分鐘為單位)。 舉例來說，如果預付訂單無法於 2 天後履行，則 preBookingRequirementMax 的值為 2880。

範例：10080
advanceBookingSlotInterval String

orderType = "ADVANCE" 時為必要欄位。

兩個連續提前預訂時段之間的間隔。 舉例來說，如果營業時間為上午 8 點到晚上 8 點，而 preBookingSlotInterval 為 15 分鐘，使用者可以選擇在上午 8 點、上午 8 點 15 分、上午 8 點 30 分、上午 8 點 45 分 (以此類推) 到晚上 8 點。 時間長度必須以 ISO 經期長度的形式指定。例如：「PT15M」是指 15 分鐘的間隔。

範例：PT15M
dateModified ISO 時間戳記

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

範例：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 設為「放送」，則必須為 feeType 設為「DELIVERY」的 Fee。

下表列出 Fee 類型的屬性：

屬性 類型 說明
@type 缺點

這是必填欄位。

值：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

非零的正值。如果使用者的購物車收取超過 1 筆費用，則最高優先權的費用將優先於較低者。如果提供這個欄位，系統一律會優先採用其優先順序，而不是計算的優先順序。

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

手續費的價格。如未固定價格，可以提供 minPrice 和 maxPrice，而非價格。

範例：1.5
percentageOfCart 第 2 組 Number

購物車價值的百分比。可接受的值為介於 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 缺點

這是必填欄位。

值：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 缺點

這是必填欄位。

值：MenuSection
@id String

這是必填欄位。

菜單專區的專屬 ID。

範例：menu_section_1
menuId 清單<ReverseReference>

與這個 MenuSection 實體相關聯的選單實體 @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 清單<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 清單<ReverseReference>

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

重要事項：你只能使用其中一個 parentMenuItemId 或 MenuItem.menuAddOnId 參照。

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

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

重要事項：你只能使用其中一個 parentMenuItemOptionId 或 MenuItemOption.menuAddOnId 參照。

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

可在外掛程式專區中選取的外掛程式數量上限。

範例：5
eligibleQuantityMin 整數

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

範例：1
defaultItemId List<String>

系統預設為 MenuSection 外掛程式中的使用者預先選取 MenuItem 實體的 @id 清單。使用者可以變更最終選項。如未指定 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 清單<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 缺點

這是必填欄位。

值：Availability
@id String

這是必填欄位。

描述菜單專區供應情形的實體專屬 ID。

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

ISO 時間戳記，代表菜單部分供應情形有效的開始時間。

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

ISO 時間戳記，代表菜單區段供應情形無效的結束時間。

範例：T16:00
availableDay 清單<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 缺點

這是必填欄位。

值：MenuItem
@id String

這是必填欄位。

選單項目的專屬 ID。

範例：menu_item_1
name String

這是必填欄位。

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

範例：Foo
description String

選單項目的說明。

範例：Foo
image 網址

菜單項目圖片的網址。

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

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

重要事項：你只能使用其中一個 parentMenuSectionId 或 MenuSection.menuItemId 參照。

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

列出與此 MenuItem 實體對應的 MenuSection 實體的 @id 值清單，

重要事項：你只能使用其中一個 menuAddOnId 或 MenuSection.parentMenuItemId 參照。

範例：menu_addon_1
nutrition NutritionInformation

餐點的營養資訊，最主要的卡路里資訊。

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

這個 MenuItem 的過敏原。

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

這個 MenuItem 的補充項目。

範例：[ { "additiveName": "Sodium nitrite", "levelOfContainment": "CONTAINS" } ]
suitableDiet 清單<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 缺點

值：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>

列出與此 MenuItemOption 實體對應的 MenuSection 實體的 @id 值清單，

重要事項：你只能使用其中一個 menuAddOnId 或 MenuSection.parentMenuItemId 參照。

範例：menuAddOnId
nutrition NutritionInformation

餐點的營養資訊，最主要的卡路里資訊。

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

這個 MenuItem 的過敏原。

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

這個 MenuItem 的補充項目。

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

此 MenuItem 的包裝和回收資訊。

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

特定選單項目選項中可提供的放送量。

範例：2
dateModified ISO 時間戳記

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

範例：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 缺點

這是必填欄位。

值：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 清單<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

卡路里、大卡或千焦耳的卡路里數量，使用格式如下：value Cal 或 min-max Cal

範例：120.34 Cal
sodiumContent String

鈉的 mg 或 g 數量，格式如下：value g 或 min-max 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 布林值

在訂購流程的「下單」頁面中隱藏提示小工具。
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