Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

リクエストパラメータ説明

リクエストデータについて説明します。詳しいAPIリクエスト方式は商品収集APIをご参照ください。 商品収集APIに関するリクエストパラメータの説明です。 Google Merchant API については、Google の公式ドキュメントをご参照ください。

共通データ構造

多言語テキストフィールド

商品名、ブランド名、カテゴリ名などのテキストフィールドは、3つの形式をサポートしています。

形式 1. 単純文字列

"name": "クラシックTシャツ"

形式 2. 言語指定オブジェクト

"name": {
  "@value": "クラシックTシャツ",
  "@language": "ja"
}

形式 3. 多言語配列

対応言語コード（ISO 639-1）：ko、en、ja

"name": [
  { "@value": "클래식 티셔츠", "@language": "ko" },
  { "@value": "Classic T-Shirt", "@language": "en" },
  { "@value": "クラシックTシャツ", "@language": "ja" }
]

言語指定オブジェクト（形式 2、3）を使用する場合、@valueと@languageはどちらも必須です。@languageを省略すると400エラーが返されます。すべての言語を必ず提供する必要はなく、必要な言語のみを送信できます。

データ入力ルール

  • 必須フィールドとnull：フィールド仕様表で必須（O）と表記されているフィールドには、必ず有効な値を含める必要があります。必須フィールドにnullを送信すると400エラーが返されます。任意（X）フィールドは省略するか、nullで送信できます。

  • 文字列（string）：特別なmaxLength制約はなく、適切な長さで送信することを推奨します。

  • 数値（number）：特別な小数点精度の規約はなく、通貨に合わせた一般的な桁数を使用します（例：JPYは整数、USDは小数点以下2桁）。

  • enum：許可される値が指定されているフィールドは、Enum値リファレンスセクションにまとめています。明示された値以外を送信すると400エラーが返されます。

  • フィールド間の依存関係：特定フィールドの値によって他のフィールドの必須可否が変わる条件付き必須ルールは適用されません。フィールド仕様表の必須可否のみを基準にデータを構成します。

  • @graph配列には、最小1件、最大1,000件の商品を含めることができます。

  • API仕様書に記載されたすべてのフィールドはnullを許容しません。

文字列・数値の推奨制約値

弊社システム側では以下の制約で受信・保存されます。設計時の参考としてご利用ください。

この値は推奨値であり、実際の値に制限はありません。

フィールド
型
制約

sku

string

最大 64 文字、半角英数字・ハイフン・アンダースコア

name

string

最大 200 文字

description.text

string

最大 5,000 文字

brand.name

string

最大 100 文字

category.name

string

最大 100 文字

url / mobileUrl

string

最大 2,048 文字、http(s) スキームのみ

price

number

小数点以下 4 桁まで（JPY/KRW は整数を推奨）

inventoryLevel.value

number

0 以上の整数

shippingDetails.weight.value

number

小数点以下 3 桁まで

gtin

string

GTIN-8 / 12 / 13 / 14（数字のみ）

priceCurrency

string

ISO 4217（例：JPY、KRW、USD）

availabilityStarts / Ends

string

ISO 8601 UTC（末尾 "Z" 必須）

Starts と Ends を両方指定する場合、Starts < Ends である必要があります。

推奨maxLength

以下は運用上の推奨値です。システム上の固定上限ではありませんが、検索・表示・照合品質を安定させるため、可能な限りこの範囲で送信してください。

対象フィールド
推奨maxLength
備考

sku、offers.sku

100

商品・オプションを一意に識別できる安定したコード

gtin

14

GTIN-8、GTIN-12、GTIN-13、GTIN-14を想定

mpn

100

メーカー品番

name、brand.name、category.name

200

表示名として読みやすい長さ

description.text

5000

HTMLではなく説明本文を推奨

url、mobileUrl、image.contentUrl

2048

https:// URLを推奨

color、size、material

100

オプション・素材名

additionalProperty.propertyID

100

属性を識別するキー

推奨数値精度

対象フィールド
推奨精度
備考

price、priceSpecification.price

通貨に準拠

JPY・KRWは整数、USDは小数点以下2桁を推奨

inventoryLevel.value

整数

在庫数量

shippingDetails.weight.value

小数点以下3桁まで

kg・gなどの重量表現

additionalProperty.platform_rate

小数点以下4桁まで

例：0.15

unit.unit_quantity

小数点以下3桁まで

梱包数量

unit.weight_quantity

小数点以下3桁まで

重量・容量値。数値型で送信

運用上の期待フォーマット

対象フィールド
期待フォーマット
備考

sku、offers.sku

英数字、ハイフン、アンダースコア推奨

例：PROD-001-WH-M。登録後は同一商品の識別子として継続使用してください。

gtin

数字のみ、8〜14桁

UPC（12桁）、EAN（13桁）、JAN（8・13桁）、ISBN（13桁）、ITF-14（14桁）に対応。 例：4901234567894

mpn

メーカーが管理する品番文字列

最大70文字の英数字。GTINがない商品の場合、送信を推奨。 例：GO12345OOGLE

availabilityStarts、availabilityEnds

UTC ISO 8601、末尾Z

例：2026-01-01T00:00:00Z

url、mobileUrl

アクセス可能な商品ページURL

https:// URLを推奨

image.contentUrl

外部から取得可能な画像URL

https:// URLを推奨。認証・期限付きURLは避けてください。

image.width.value、image.height.value

ピクセル値

正の数値を送信してください。

priceCurrency

ISO 4217、3桁大文字

例：JPY、KRW、USD

フィールド詳細仕様

イベントオブジェクト（CollectorProductsEvent）

フィールド
タイプ
必須
説明

@context

string

X

スキーマcontext。固定値："https://schema.org"

specversion

string

X

スペックバージョン。固定値："1.0"

id

string

X

イベント固有識別子。登録："EVT-CREATE-PRODUCT"、修正："EVT-UPDATE-PRODUCT"

type

string

X

イベントタイプ。登録："create_product"、修正："update_product"

agent

object

O

リクエスト元情報

@graph

array

O

商品データ配列（1〜1,000件）

agentオブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："Organization"

name

string

O

リクエスト企業名

商品オブジェクト（@graph）

@graph配列の各項目は1つの商品を表します。

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："Product"

sku

string

O

商品コード（一意の識別子）

name

string | object | array

O

商品名。多言語対応

description

object | array

O

商品説明

brand

object

O

ブランド情報

category

object | array

O

カテゴリ情報

positiveNotes

string | object | array

X

主な特徴・利点の要約。多言語対応

url

string | object | array

O

商品ページURL。多言語対応

mobileUrl

string | object | array

X

モバイル商品ページURL。多言語対応

itemCondition

string

X

商品状態。enum参照

hasAdultConsideration

string

X

成人向け商品区分。enum参照

countryOfOrigin

object

X

製造国情報

material

string | object | array

X

素材情報。多言語対応

additionalProperty

array

X

追加属性

offers

object | array

O

SKU別価格・在庫情報

countryOfOriginオブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："Country"

address

string

O

製造国コード（ISO 3166-1 alpha-2、例："JP"、"KR"、"US"）

ブランド（brand）

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："Brand"

@id

string

O

ブランド識別子

name

string | object | array

O

ブランド名。多言語対応

logo

array<string>

X

ブランドロゴURL一覧

カテゴリ（category）

単一オブジェクトまたは配列で送信します。配列を使用する場合、position値でカテゴリ階層レベルを表現します。

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："CategoryCode"

codeValue

string

O

カテゴリコード

name

object | array

O

カテゴリ名。多言語対応

position

integer

O

カテゴリ階層（1 = 大分類、2 = 中分類、...）

商品説明（description）

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："TextObject"

text

string

O

説明テキスト

inLanguage

string

O

言語コード（ISO 639-1）：ko、en、ja

image

object | array

X

説明に含まれる画像情報

additionalProperty

array

X

追加属性

description内の画像オブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："ImageObject"

contentUrl

string

X

画像URL

inLanguage

string

X

言語コード

価格・在庫情報（offers）

単一オブジェクトまたは配列で送信します。カラー・サイズなどのオプション別に個別のofferを構成します。

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："Offer"

sku

string

O

オプション別商品コード

gtin

string

X

国際標準バーコード（GTIN）。UPC（12桁）、EAN（13桁）、JAN（8・13桁）、ISBN（13桁）、ITF-14（14桁）に対応。 例：8801234567890

mpn

string

O

メーカー品番（MPN）。GTINがない商品の場合、送信を推奨。最大70文字の英数字。 例：GO12345OOGLE

price

number

O

価格

priceCurrency

string

O

通貨コード（ISO 4217、例："JPY"、"KRW"、"USD"）

priceSpecification

object | array

X

価格タイプ詳細

color

string

O

カラー

size

string

O

サイズ

availability

string

O

在庫状態。enum参照

availabilityStarts

string

O

販売開始日時（UTC ISO 8601）

availabilityEnds

string

O

販売終了日時（UTC ISO 8601）

inventoryLevel

object

X

在庫数量情報

shippingDetails

object

X

配送情報

image

object | array

O

商品画像

additionalProperty

array

X

追加属性

inventoryLevelオブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："QuantitativeValue"

value

number

O

在庫数量

shippingDetailsオブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："OfferShippingDetails"

weight

object

O

配送重量

shippingDetails.weightオブジェクト

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："QuantitativeValue"

value

number

O

重量値

unitCode

string

O

単位コード（例："KGM"、"GRM"）

価格タイプ（priceSpecification）

定価、販売価格、メーカー希望小売価格など、さまざまな価格タイプを表現します。

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："UnitPriceSpecification"

priceType

string

O

価格区分。enum参照

price

number

O

価格

priceCurrency

string

O

通貨コード（ISO 4217）

unitCode

string

O

単位コード

画像（image）

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："ImageObject"

representativeOfPage

boolean

X

代表画像かどうか（true = 代表画像）

contentUrl

string

O

画像URL

contentSize

string

X

ファイルサイズ

width

object

X

幅（{ "@type": "QuantitativeValue", "value": 800 }）

height

object

X

高さ（{ "@type": "QuantitativeValue", "value": 600 }）

画像の仕様

項目
仕様

対応フォーマット

jpg, jpeg, png, webp

最大ファイルサイズ

10 MB

推奨解像度

800×800 以上

width / height の単位

ピクセル（px）

contentSize の単位

バイト（byte）

追加属性（additionalProperty）

標準フィールドでは表現できない追加情報を格納するための拡張フィールドです。

商品オブジェクト（@graph[]）、商品説明（description）、価格情報（offers）内で使用できます。

フィールド
タイプ
必須
説明

@type

string

X

タイプ。固定値："PropertyValue"

propertyID

string

X

属性ID（属性を区別するキー）

value

any

X

値（string、number、boolean、arrayなど、すべてのタイプが使用可能）

商品オブジェクト（@graph[]）内に値を送信することを推奨します。

propertyID の拡張ポリシー

  • 上記の推奨 propertyID 一覧は、弊社が標準解析に利用する既知の属性です。

  • それ以外の propertyID を任意に追加することが可能です。ただし、標準解析の対象外となり、原文のまま保管されます。

  • 命名規則：英小文字・数字・アンダースコア（snake_case）を推奨。最大 64 文字。

  • value の最大サイズ：JSON シリアライズ後 8 KB 以内。

属性リファレンス

以下はadditionalPropertyで使用できる推奨属性の一覧です。許可値の例を参考にして、値のフォーマットを合わせて送信してください。

propertyID
valueタイプ
説明
許可値 / 例

gender

string

性別

Enum値リファレンスのgender参照

season

string[]

季節

Enum値リファレンスのseason参照

temperature

string

保管方法

自由値。例："Refrigerate"

platform_rate

number

プラットフォーム手数料

0.15

unit

object

梱包・重量情報

サブフィールド：unit、unit_quantity、weight_unit、weight_quantity

seller

object

販売者情報

サブフィールド：prefecture、seller_name

unitオブジェクト構造

サブフィールド
タイプ
説明
例

unit

string

梱包単位。自由値

"box"、"pack"、"ea"

unit_quantity

number

梱包数量

500

weight_unit

string

重量単位

"g"、"ml"

weight_quantity

number

重量値

500

sellerオブジェクト構造

サブフィールド
タイプ
説明
例

prefecture

string

産地・地域

"秋田県"、"済州島"など

seller_name

string

販売者名

"きのこ農園"、"ユースファーマー"など

使用例

unit属性のweight_unitはgまたはmlに統一して送信します。 元データがkgの場合はgに、Lの場合はmlに変換してください。

Enum値リファレンス

itemCondition

商品の物理的な状態を表します。

値
説明

NewCondition

新品

RefurbishedCondition

リファービッシュ品

UsedCondition

中古品

DamagedCondition

損傷品

hasAdultConsideration

成人向け商品かどうかを区分します。

値
説明

AlcoholConsideration

酒類

DangerousGoodConsideration

危険物

HealthcareConsideration

医薬品・医療機器

NarcoticConsideration

麻薬類

ReducedRelevanceForChildrenConsideration

児童不適切

SexualContentConsideration

アダルトコンテンツ

TobaccoNicotineConsideration

たばこ・ニコチン

UnclassifiedAdultConsideration

その他成人向け

ViolenceConsideration

暴力性

WeaponConsideration

武器類

availability

SKUの在庫・販売状態を表します。

値
説明

BackOrder

入荷予定（注文可能）

Discontinued

販売終了

InStock

在庫あり

InStoreOnly

店頭販売のみ

LimitedAvailability

数量限定

MadeToOrder

受注生産

OnlineOnly

オンライン限定

OutOfStock

在庫切れ

PreOrder

予約注文

PreSale

先行販売

Reserved

予約済み

SoldOut

完売

priceType

価格の性質を区分します。

値
説明

InvoicePrice

請求価格

ListPrice

定価

MSRP

メーカー希望小売価格

MinimumAdvertisedPrice

最低広告価格

RegularPrice

通常販売価格

SRP

推奨小売価格

SalePrice

セール価格

StrikethroughPrice

取消線価格（元の価格表示用）

gender

additionalPropertyのpropertyIDがgenderの場合に使用します。

値
説明

M

Men

W

Women

U

Unisex

season

additionalPropertyのpropertyIDがseasonの場合に使用します。複数指定する場合は文字列配列で送信してください。

値
説明

Spring

春

Summer

夏

Fall

秋

Winter

冬

weight_unit

additionalPropertyのpropertyIDがunitの場合、value.weight_unitで使用します。

値
説明

g

グラム

ml

ミリリットル

エラー応答リファレンス

主な 400 エラーの発生条件

条件
発生フィールド例

必須フィールドが null または欠落

sku, name, offers.price 等

enum 以外の値

availability, priceType, itemCondition

ISO 形式違反

priceCurrency, countryOfOrigin.address, availabilityStarts

@value または @language の欠落

多言語オブジェクト全般

文字数・数値範囲の超過

上記「推奨制約値」を参照

@graph が 0 件または 1,000 件超過

@graph 配列

参考：JSONスキーマ例

商品登録
商品修正
商品削除
Previous商品データ収集APINext商品データ収集API

Last updated