FrontPage

データAPI/カスタム食品文字列検索

※本API機能は追加オプションご契約の方のみがご利用になれるもので、レスポンス項目はご契約内容によって異なります。

NEW: extargetobjオプションをお客様のご希望により標準追加しました (June 2022) ※ご利用希望の方はご連絡下さい
NEW: unlimited オプションについて、標準提供サービスに変更致しました (June 2022) ※ご利用希望の方はご連絡下さい
Info: nozero,及び wordfilterwith オプションの利用により、更なる検索性能向上を実現しました (June 2022)
NEW: カスタム検索APIにおいて文言フィルターの対象に関連語を含める検索に対応しました (Feb 2022)
NEW: カスタム検索APIにおいて食材を参照した検索精度改善に対応した検索結果に対応しました (Jan 2021)
NEW: カスタム検索APIにおいて指定統合タグ食品群を優先上位表示することに対応しました (Oct 2020)

API情報

名称カスタム食品文字列検索
APIバージョン2
認証タイプなし
URLhttps://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/検索語1 検索語2 ... 検索語N/
https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/検索語1 検索語2 ... 検索語N/開始位置/表示個数/
MethodGET
データ更新頻度目安4週間(新商品追加は約12時間毎、任意検索語の検索結果更新はオペレーターによる対応可能)

概要

文字列によって食品を検索し、カスタムフィルター及びカスタムソートを実施する。検索は 食品文字列検索+ に準じた処理(検索語結合モードがANDの場合)か、食品文字列検索 の処理を全て結合する処理(検索語結合モードがORの場合)が実施される。文字列の比較対象は、名前、よみ、三階層カテゴリー名となる。
従来(本カスタム食品文字列検索以外を含む)、検索文字列は全角相当の先頭6文字のみ有効であったが、フィルタ機能の充実と unlimited オプションの実現により、同条件は撤廃し、フルネームの食品・商品名やカテゴリ、メーカー・社名で検索することが望ましいとする。

カスタムフィルター

フィルター処理は、文言除外フィルター、栄養素値フィルターの各処理が実施される。

通常の検索結果に他の検索結果を追加するオプション(withnewfood_and,withnewfood,withmm)の使用時は、検索結果の付加が行われた後に、フィルターの適用が実施される。

カスタムソート

指定された栄養素について、昇順または降順によって、結果をソートする。

オプション、カスタムフィルター、カスタムソートの処理順

オプション、カスタムフィルター、カスタムソートのいずれか又は全てが同時に指定された場合、処理の順は以下の通り。

オプション指定の追加位置が先頭又は末尾となっているものについて、カスタムソートを実施した場合は、カスタムソート結果が優先される。

アクセス手順

クエリー

https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/(検索文字列)/?(カスタムフィルター・カスタムスロット条件)
(検索文字列) で検索した結果にカスタムフィルター・カスタムスロット条件を適用して返却する。

https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/(検索文字列)/(開始位置)/(表示個数)/?(カスタムフィルター・カスタムスロット条件)
(検索文字列) で検索した結果にカスタムフィルター・カスタムスロット条件を適用し、0から始まるインデックスの(開始位置)番目から、(表示個数)個のアイテムを返却する。

検索文字列がマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。

クエリー (GET) の最大値は 8192 Byte(8KB) とする。

カスタムフィルター条件

カスタムフィルターは、検索結果を条件によって絞り込む。パラメータはクエリー文字列としてクエリー末尾に付加する。 文字列パラメータがマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。 カスタムフィルター条件は省略可能であり、省略されたものは実施されない。

パラメータ名内容形式省略可否
exword文言除外フィルター指定文字列
複数指定時は半角スペースで区切る
文字列省略可・未指定時非実施
excond文言除外フィルター除外条件OR条件=or AND条件=andexword指定時必須
exstuff_idN栄養素値フィルター指定栄養素ID
Nは1から始まる添字。Nは1ずつ増加しなければならない。
栄養素コード
※shopnameを例外的対象としexstuff_existNによる判定に対応
省略可・未指定時非実施
exstuff_upperN栄養素値フィルター範囲最大値
Nはexstuff_idに対応する添字。
数値exstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須
exstuff_lowerN栄養素値フィルター範囲最小値
Nはexstuff_idに対応する添字。
数値exstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須
exstuff_existN栄養素値フィルター存在指定
Nはexstuff_idに対応する添字。
存在時除外=exclude 非存在時除外=includeexstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須
sort_idカスタムソート指定栄養素ID
※本ソート指定を行うと、標準ソート(検索文字列の完全合致を最優先)は解除されます。
栄養素コード省略可・未指定時非実施
sort_dirカスタムソート順序昇順=asc 降順=descsort_id指定時必須
concat検索語結合モード指定AND条件=and 各検索語の結果のうち全ての検索語を含むもののを対象にフィルターを実施する
OR条件=or 各検索語の結果のうちいずれかの検索語を含むものを対象にフィルターを実施する
省略時and
nozero先頭検索語の文字数を減数して再検索
フィルターにかける検索結果数が0の時、1番目の検索語の文字数が3文字になるまで1文字ずつ減らして再検索するオプション
※検索結果の精度を高めるものではありません
実施する=1任意
wordfilterwith文言フィルターの対象に関連語を追加して合致対象を拡大
※検索マッチ数や精度に大きく影響するため、標準では実施しない設定です。
実施する=rword任意
extargetobj検索結果から指定された食品を除外する。(2022/6 標準追加)食品オブジェクトID 半角スペース区切り任意
unlimited検索対象拡大オプション
メーカー名、カテゴリ名、大分類カテゴリ名など4千件超の主要語と本検索語が合致した場合、検索母体数を最大 2 万件まで拡大し検索する。(通常は 500 件)
※制限事項:フィルタ後の最終検索結果数は最大 500 件に制限されます。
※注意事項:検索語によっては処理時間が長くなる場合があります。
実施する=1任意
withnewfood【OPTIONS A】
検索対象に新商品を追加します
各検索語のいずれかが、新商品の「品名・名称、よみ(平仮名)、検索語、三階層カテゴリ名」内に存在する場合、検索対象(検索母集団)に追加する
追加する=1任意
withnewfood_and【OPTIONS A】
検索対象に新商品を追加します
全検索語が同時に、新商品の「品名・名称、よみ(平仮名)、検索語、三階層カテゴリ名」内に存在する場合、検索対象(検索母集団)に追加する
追加する=1任意
SearchTarget【OPTIONS C】月額 4 万円
検索する対象の範囲を限定する。
対象範囲には、「M&Mメニュー」が指定できる。
※M&Mメニューとは、メジャー&マイナーメニューの略語でメジャー(約800品)及びマイナー(約300品)で構成される、IMD独自基準で選別した「主たる食品群」であり、原則としてその他全ての食品(商品や外食を含む)は、構成食材や品種・種目などを基準として、このM&Mに関連付けされている。
M&Mメニュー=mm任意
withmm【OPTIONS C】SearchTarget=mm と同じ検索を実施し
その検索結果を通常の検索結果の前に付加します。
withmm=1 で有効任意
TargetExampleOID【OPTIONS C】
検索結果を指定したオブジェクトID食品が持つM&Mメニュー食品と同一のものに限定する。
文字列(オブジェクトID)任意
filtersn【OPTIONS D】月額 3 万円
メーカー名フィルター
shopnameフィールドに対して指定された文字列でフィルターする
文字列任意
filtersn_match【OPTIONS D】
メーカー名フィルターマッチ方式
完全一致=full 部分一致=part省略時part
flagsn【OPTIONS D】
メーカー名付きフラグ
メーカー名付きのみ=yes メーカー名なしのみ=no 両方=both省略可・省略時both
filtercatN【OPTIONS E】月額 3 万円
カテゴリー階層マッチ
caregorytreeフィールド内のいずれかに対して指定された文字列でフィルターする
Nは1~3を半角数値で指定。完全一致で判定される。
文字列任意
reordering【OPTIONS F】月額 4 万円
検索結果並べ替えオプション
検索結果を独自ルールに基づいて並べ替える。
※slot4方式として右記の検索方式で定義されているものである
食品文字列検索++=slot4任意
singular【OPTIONS G】月額 4 万円
検索対象に特異的取扱食品を追加
別途定義する特異的取扱食品を検索し、検索結果の先頭に追加する。
実施する=1任意
exelement構成素材による除外指定
構成素材の情報を含む食品について、指定の構成要素を含むものを結果から除外する。
構成素材の情報を持たない食品は、その食品自身が比較対象となる。
文字列(オブジェクトID) 複数の場合は半角スペース区切り任意
inelement構成素材による含有指定
構成素材の情報を含む食品について、指定の構成要素を含むものを結果に含む。
構成素材の情報を持たない食品は、その食品自身が比較対象となる。
文字列(オブジェクトID) 複数の場合は半角スペース区切り任意

カスタムスロット条件

カスタムスロットは、検索結果のうち指定したものを上位に挿入する。パラメータはクエリー文字列としてクエリー末尾に付加する。 カスタムスロット条件は省略可能であり、省略されたものは実施されない。

パラメータ名内容形式省略可否
slotprioスロットプライオリティ文字列省略可・未指定時非実施

スロットプライオリティ書式

スロットプライオリティは、各スロット間の優先順位と、個別スロット定義(各スロットの抽出条件及びスロット数)を指定する。
個別スロット定義は、半角カンマで区切って列挙する。左に記述したものが優先される。

個別スロットは、パラメータを半角コロンで区切って記述する。 食品属性を指定した場合、指定された属性を持つ食品がスロットに抽出される。 栄養素コードを指定した場合、指定された栄養素が最も多い順または少ない順に抽出される。

slotprio=(個別スロット1),(個別スロット2),...(個別スロットN)

個別スロット=
 attr:(食品属性):-:(スロット数) または
 member:(栄養素コード):(ソート方向):(スロット数)

食品属性は、newfood=新商品/mmtagged=M&Mメニュー/material=基本素材食品 のうち、提供される検索のものが使用可能。
栄養素コードは、提供される栄養素が使用可能。
ソート方向は、desc=降順/asc=昇順、食品属性指定の場合は項目は無視される。
スロット数は、数値。

例: 最初にM&Mメニューを3スロット、次にカロリーの多い順に2スロット、糖質の少ない順に2スロット
slotprio=attr:mmtagged:-:3,member:stuff_e:desc:2,member:carbo:asc:2

カスタムフィルター排他条件

以下のカスタムフィルター条件は、いずれか1つのみ指定できる。いずれかのグループに属する条件を指定した場合、それ以外のグループに属する条件は無効となる。複数グループにまたがって指定された場合は、優先度の小さいものが有効となる。

グループパラメータ名優先度
M&MメニューSearchTarget1
新商品withnewfood,withnewfood_and2

特異的取扱食品の指定

特異的取扱を行う食品を、objectid単位で設定できる。指定された食品は、singular=1 が指定された検索の時、検索結果の先頭に配置される。 (※使用に際し弊社が設定します。指定する食品をお知らせ下さい。)

特異的取扱食品の追加位置

本来の検索結果に追加して特異的取扱食品の結果を返す時、特異的取扱食品の結果は、本来の結果の先頭に追加される。 以下の検索が対象となる。

パラメータ名追加データ
singular特異的取扱食品として指定タグを付与された食品群 (EAPITOP_xxx)

※singular食品群は弊社API全体で有効な食品に対し、専有食品(弊社API全体では無効、任意APIでのみ有効)の指定としてownerexclusiveの用意がある。 ※カテゴリー指定でAPI全体で無効とする場合には「API検索除外設定」がある。(弊社判断による処理)

副検索結果の追加位置

本来の検索結果に追加して副検索の結果を返す時、副検索の結果は、本来の結果の後尾に追加され、以下の副検索が対象となる。

パラメータ名追加データ
withnewfood新商品
withnewfood_and新商品

※純粋な結果としては後尾に追加されるが、新商品も栄養素フィルタ対象になり、且つ、ソートした場合には必ずしも後尾とは限らない。

複数検索語による検索(画像認識支援等用途)

引数に multiplexer=1 を追加することで本機能を利用する。2番目以降の検索語を、_M(番号)needle=検索語 として追加する。番号は1から始まり、0番はURL中の標準検索語となる。

結果を混合するとき、各検索番からN個ずつ取る指定。省略時はN=1

結果を混合する順番。xxx=roundrobin の場合、0番から順番に取る。xxx=random の場合、ランダムに取る。(省略時はroundrobin)

obj.foods 従来と同じフォーマットの検索結果
obj.foods.(配列の添字).multiplex_index 発生源として各検索番に対応した番号
obj.multiplex 複数検索語の情報

※結果数は最大500とし、その他の引数はcustomと同じ。全ての検索番に共通してパラメータが適用される。そのため、検索結果指定数×multiplexer設定数の結果が原則レスポンスされる。

検索文字列ルール

検索文字列ルール に従う。

(2022/7頃から適用)
検索結果の候補は、半角英字の大小を区別せず用意されるが、半角英字の大小を区別して検索文字列にマッチしない結果は除外される。
(demo06にのみ適用)
但し次の場合を除く。
検索文字列が全て英数字であって、且つ文字数が3文字以上の場合、半角英字の大小を区別せず検索文字列にマッチしない結果は除外される。

入力される検索文字列の取り扱い

検索文字列は、半角スペース(" ")で区切られた複数の語によって構成される。
入力された各検索語は、先頭から全角6文字相当(半角12文字相当)までが採用され、それ以降の部分は切り捨てて使用される。

クエリー例

https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/%E3%82%AB%E3%83%AC%E3%83%BC%20%E3%83%81%E3%82%AD%E3%83%B3/
?exword=%E3%82%AD%E3%83%A3%E3%83%99%E3%83%84%20%E3%83%88%E3%83%9E%E3%83%88&excond=or
&exstuff_id1=stuff_e&exstuff_upper1=800.0&exstuff_lower1=400.0
&exstuff_id2=stuff_p&exstuff_upper2=20.0&exstuff_lower2=15.0
&exstuff_id3=shopname&exstuff_exist3=exclude
&sort_id=stuff_e&sort_dir=asc

レスポンス

レスポンスコードは200を返し、レスポンスはjson形式である。レスポンスされる食品数の最大値は 500 である。 検索結果が存在しない場合は長さ0の配列が返される。クエリー書式誤り等の場合はレスポンスコード404が返される。

{
  foods :[
    {
      "name" : 食品名,
      "yomi" : 食品名読み,
      "objectid" : オブジェクトID,
      "unit" : 分量,
      "stuff_e" : エネルギー,
      "stuff_p" : たんぱく質,
      "stuff_f" : 脂質,
      "stuff_c" : 炭水化物,
      "categorytree" : [
        第1階層カテゴリー名,
        第2階層カテゴリー名,
        第3階層カテゴリー名
      ],
      "subsubattr" : {
        "gaishoku" : 外食フラグ 0 or 1,
        "kakou" : 加工食品フラグ 0 or 1,
        "takeout" : テイクアウトフラグ 0 or 1,
      },
      "shopname" : メーカー名,
    },
    {
      (食品データ)
    },
    :
  ]
}

レスポンス例

{
  "foods":[
    {
      "name":"\u30aa\u30fc\u30eb\u30a2\u30ba\u30ad(1\u679a)(\u6771\u30cf\u30c8)",
      "yomi":"\u304a\u30fc\u308b\u3042\u305a\u304d\u3044\u3061\u307e\u3044\u3068\u3046\u306f\u3068",
      "objectid":"FOd6e9f772488019ac014f6f5b",
      "unit":8,
      "stuff_e":29,
      "stuff_p":0.5,
      "stuff_f":0.6,
      "stuff_c":5.5,
      "categorytree":[
        "\u305d\u306e\u4ed6",
        "\u83d3\u5b50\u985e",
        "\u30af\u30c3\u30ad\u30fc\u30fb\u30d3\u30b9\u30b1\u30c3\u30c8\u30fb\u30d1\u30a4"
      ],
      "shopsubattr":{
        "gaishoku":0,
        "kakou":1,
        "takeout":0
      },
      "shopname":"\u6771\u30cf\u30c8"
    },
    {
      "name":"\u30aa\u30fc\u30eb\u30a2\u30c3\u30d7\u30eb(1\u679a)(\u6771\u30cf\u30c8)",
      "yomi":"\u304a\u30fc\u308b\u3042\u3063\u3077\u308b \u3044\u3061\u307e\u3044 \u3068\u3046\u306f\u3068",
      "objectid":"FOe30783f5474d2d7228624ecc",
      "unit":7.6,
      "stuff_e":29,
      "stuff_p":0.3,
      "stuff_f":0.6,
      "stuff_c":5.5,
      "categorytree":[
        "\u305d\u306e\u4ed6",
        "\u83d3\u5b50\u985e",
        "\u30af\u30c3\u30ad\u30fc\u30fb\u30d3\u30b9\u30b1\u30c3\u30c8\u30fb\u30d1\u30a4"
      ],
      "shopsubattr":{
        "gaishoku":0,
        "kakou":1,
        "takeout":0
      },
      "shopname":"\u6771\u30cf\u30c8"
    }
  ]
}

考慮事項

本APIの返却するデータは、クライアント側で適切にキャッシュ等を行い、アクセス量を低減させることが望ましい。 ※但し、特に新商品の更新は常時行われているので、必要に応じて対処願いたい。

バージョン

仕様変更履歴 

2022/9/15 flagsn について、例外的メーカー名「商品」「外食」「テイクアウト」はメーカー名無しとして扱うのを削除 2022/10/15 特異的取扱食品の追加位置 について、ownerexclusive の説明を追加

このドキュメントのバージョン情報

Version1
Revision1
EditorIMD

トップ   差分 履歴 リロード   一覧 検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2022-12-02 (金) 09:06:09