![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
#author("2024-04-09T07:03:02+09:00","","") #author("2024-04-09T07:03:44+09:00","","") [[FrontPage]] &size(24){データAPI/カスタム食品文字列検索}; ※本API機能は追加オプションご契約の方のみがご利用になれるもので、レスポンス項目はご契約内容によって異なります。&br; NEW: extargetobjオプションをお客様のご希望により標準追加しました (June 2022) ※ご利用希望の方はご連絡下さい&br; NEW: unlimited オプションについて、標準提供サービスに変更致しました (June 2022) ※ご利用希望の方はご連絡下さい&br; Info: nozero,及び wordfilterwith オプションの利用により、更なる検索性能向上を実現しました (June 2022)&br; NEW: カスタム検索APIにおいて文言フィルターの対象に関連語を含める検索に対応しました (Feb 2022)&br; NEW: カスタム検索APIにおいて食材を参照した検索精度改善に対応した検索結果に対応しました (Jan 2021)&br; NEW: カスタム検索APIにおいて指定統合タグ食品群を優先上位表示することに対応しました (Oct 2020)&br; * API情報 [#q6190828] |~名称|カスタム食品文字列検索| |~APIバージョン|2| |~認証タイプ|なし| |~URL|https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/検索語1 検索語2 ... 検索語N/ &br;https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/検索語1 検索語2 ... 検索語N/開始位置/表示個数/| |~Method|GET| |~データ更新頻度目安|4週間（新商品追加は約12時間毎、任意検索語の検索結果更新はオペレーターによる対応可能）| * 概要 [#jfe13a2c] 文字列によって食品を検索し、カスタムフィルター及びカスタムソートを実施する。検索は [[食品文字列検索＋>データAPI/食品文字列検索＋]] に準じた処理(検索語結合モードがANDの場合)か、[[食品文字列検索>データAPI/食品文字列検索]] の処理を全て結合する処理(検索語結合モードがORの場合)が実施される。文字列の比較対象は、名前、よみ、三階層カテゴリー名となる。&br; 従来(本カスタム食品文字列検索以外を含む）、検索文字列は全角相当の先頭６文字のみ有効であったが、フィルタ機能の充実と unlimited オプションの実現により、同条件は撤廃し、フルネームの食品・商品名やカテゴリ、メーカー・社名で検索することが望ましいとする。 ** カスタムフィルター [#qcf1465c] フィルター処理は、文言除外フィルター、栄養素値フィルターの各処理が実施される。 - 文言フィルターの対象となるのは、名前、読み、カテゴリーの各文字列である。(複数可) - オプションwordfilterwith=rwordが指定された場合、文言フィルターの対象に関連語を追加する。 - 文言除外フィルターは、名前、読み、カテゴリーに指定文字列を全てまたはいずれかを含むものは結果から除外される。 - 栄養素値フィルターは範囲指定の場合、指定された栄養素について、指定された範囲を外れたものは結果から除外される。(全栄養素対象に、複数栄養素に対応) - 栄養素値フィルターは存在指定の場合（shopname項目の指定時）、指定された栄養素または項目について、存在しているものまたは存在していないものは結果から除外される。 （商品又は一般料理かの区分に対応） 通常の検索結果に他の検索結果を追加するオプション（withnewfood_and,withnewfood,withmm）の使用時は、検索結果の付加が行われた後に、フィルターの適用が実施される。 ** カスタムソート [#c0b91488] 指定された栄養素について、昇順または降順によって、結果をソートする。 ** オプション、カスタムフィルター、カスタムソートの処理順 [#la7bb58a] オプション、カスタムフィルター、カスタムソートのいずれか又は全てが同時に指定された場合、処理の順は以下の通り。 - オプション指定の処理結果の末尾（または先頭）に追加 - カスタムフィルターを適用 - カスタムソートを実施 オプション指定の追加位置が先頭又は末尾となっているものについて、カスタムソートを実施した場合は、カスタムソート結果が優先される。 ** 補助処理 [#c0b91488] 出力結果に対して補助的に実行する処理。 * アクセス手順 [#ya59d11f] ** クエリー [#l9016c71] https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/(検索文字列)/?(カスタムフィルター・カスタムスロット条件) &br; (検索文字列) で検索した結果にカスタムフィルター・カスタムスロット条件を適用して返却する。 https://(APIサーバー名)/services/api2/(アクセスコード)/search/(カスタムコード)/json/(検索文字列)/(開始位置)/(表示個数)/?(カスタムフィルター・カスタムスロット条件) &br; (検索文字列) で検索した結果にカスタムフィルター・カスタムスロット条件を適用し、0から始まるインデックスの(開始位置)番目から、(表示個数)個のアイテムを返却する。 検索文字列がマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。 クエリー (GET) の最大値は 8192 Byte(8KB) とする。 ** カスタムフィルター条件 [#m051cee1] カスタムフィルターは、検索結果を条件によって絞り込む。パラメータはクエリー文字列としてクエリー末尾に付加する。 文字列パラメータがマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。 カスタムフィルター条件は省略可能であり、省略されたものは実施されない。 |パラメータ名|内容|形式|省略可否|h |exword|文言除外フィルター指定文字列&br;複数指定時は半角スペースで区切る|文字列|省略可・未指定時非実施| |excond|文言除外フィルター除外条件|OR条件=or AND条件=and|exword指定時必須| |exstuff_idN|栄養素値フィルター指定栄養素ID&br;Nは1から始まる添字。Nは1ずつ増加しなければならない。|栄養素コード&br;※shopnameを例外的対象としexstuff_existNによる判定に対応|省略可・未指定時非実施| |exstuff_upperN|栄養素値フィルター範囲最大値&br;Nはexstuff_idに対応する添字。|数値|exstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須| |exstuff_lowerN|栄養素値フィルター範囲最小値&br;Nはexstuff_idに対応する添字。|数値|exstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須| |exstuff_existN|栄養素値フィルター存在指定&br;Nはexstuff_idに対応する添字。|存在時除外=exclude 非存在時除外=include|exstuff_id指定時、exstuff_upper/exstuff_lower/exstuff_existのいずれか必須| |sort_id|カスタムソート指定栄養素ID&br;※本ソート指定を行うと、標準ソート(検索文字列の完全合致を最優先)は解除されます。|栄養素コード|省略可・未指定時非実施| |sort_dir|カスタムソート順序|昇順=asc 降順=desc|sort_id指定時必須| |concat|検索語結合モード指定|AND条件=and 各検索語の結果のうち全ての検索語を含むもののを対象にフィルターを実施する&br;OR条件=or 各検索語の結果のうちいずれかの検索語を含むものを対象にフィルターを実施する|省略時and| |nozero|先頭検索語の文字数を減数して再検索&br;フィルターにかける検索結果数が0の時、1番目の検索語の文字数が３文字になるまで１文字ずつ減らして再検索するオプション&br;※検索結果の精度を高めるものではありません|実施する=1|任意| |wordfilterwith|文言フィルターの対象に関連語を追加して合致対象を拡大&br;※検索マッチ数や精度に大きく影響するため、標準では実施しない設定です。|実施する=rword|任意| |extargetobj|検索結果から指定された食品を除外する。(2022/6 標準追加)|食品オブジェクトID 半角スペース区切り|任意| |unlimited|検索対象拡大オプション&br;メーカー名、カテゴリ名、大分類カテゴリ名など4千件超の主要語と本検索語が合致した場合、検索母体数を最大 2 万件まで拡大し検索する。(通常は 500 件)&br;※制限事項：フィルタ後の最終検索結果数は最大 500 件に制限されます。&br;※注意事項：検索語によっては処理時間が長くなる場合があります。|実施する=1|任意| |withnewfood|【OPTIONS A】&br;検索対象に新商品を追加します&br;各検索語のいずれかが、新商品の「品名・名称、よみ（平仮名）、検索語、三階層カテゴリ名」内に存在する場合、検索対象（検索母集団）に追加する|追加する=1|任意| |withnewfood_and|【OPTIONS A】&br;検索対象に新商品を追加します&br;全検索語が同時に、新商品の「品名・名称、よみ（平仮名）、検索語、三階層カテゴリ名」内に存在する場合、検索対象（検索母集団）に追加する|追加する=1|任意| |SearchTarget|【OPTIONS C】月額 4 万円&br;検索する対象の範囲を限定する。&br;対象範囲には、「M&Mメニュー」が指定できる。&br;※M&Mメニューとは、メジャー＆マイナーメニューの略語でメジャー（約800品)及びマイナー（約300品）で構成される、IMD独自基準で選別した「主たる食品群」であり、原則としてその他全ての食品（商品や外食を含む）は、構成食材や品種・種目などを基準として、このM&Mに関連付けされている。|M&Mメニュー=mm|任意| |withmm|【OPTIONS C】SearchTarget=mm と同じ検索を実施し&br;その検索結果を通常の検索結果の前に付加します。|withmm=1 で有効|任意| |TargetExampleOID|【OPTIONS C】&br;検索結果を指定したオブジェクトID食品が持つM&Mメニュー食品と同一のものに限定する。|文字列(オブジェクトID)|任意| |filtersn|【OPTIONS D】月額 3 万円&br;メーカー名フィルター&br;shopnameフィールドに対して指定された文字列でフィルターする|文字列|任意| |filtersn_match|【OPTIONS D】&br;メーカー名フィルターマッチ方式&br;|完全一致=full 部分一致=part |省略時part| |flagsn|【OPTIONS D】&br;メーカー名付きフラグ|メーカー名付きのみ=yes メーカー名なしのみ=no 両方=both|省略可・省略時both| |filtercatN|【OPTIONS E】月額 3 万円&br;カテゴリー階層マッチ&br;caregorytreeフィールド内のいずれかに対して指定された文字列でフィルターする&br;Nは1～3を半角数値で指定。完全一致で判定される。|文字列|任意| |reordering|【OPTIONS F】月額 4 万円&br;検索結果並べ替えオプション&br;検索結果を独自ルールに基づいて並べ替える。&br;※slot4方式として右記の検索方式で定義されているものである|食品文字列検索＋＋=slot4|任意| |singular|【OPTIONS G】月額 4 万円&br;検索対象に特異的取扱食品を追加&br;別途定義する特異的取扱食品を検索し、検索結果の先頭に追加する。|実施する=1|任意| |exelement|構成素材による除外指定&br;構成素材の情報を含む食品について、指定の構成要素を含むものを結果から除外する。&br;構成素材の情報を持たない食品は、その食品自身が比較対象となる。|文字列(オブジェクトID) 複数の場合は半角スペース区切り|任意| |inelement|構成素材による含有指定&br;構成素材の情報を含む食品について、指定の構成要素を含むものを結果に含む。&br;構成素材の情報を持たない食品は、その食品自身が比較対象となる。|文字列(オブジェクトID) 複数の場合は半角スペース区切り|任意| ** カスタムスロット条件 [#m051cee1] カスタムスロットは、検索結果のうち指定したものを上位に挿入する。パラメータはクエリー文字列としてクエリー末尾に付加する。 カスタムスロット条件は省略可能であり、省略されたものは実施されない。 |パラメータ名|内容|形式|省略可否|h |slotprio|スロットプライオリティ|文字列|省略可・未指定時非実施| *** スロットプライオリティ書式 [#m051cee1] スロットプライオリティは、各スロット間の優先順位と、個別スロット定義（各スロットの抽出条件及びスロット数）を指定する。&br; 個別スロット定義は、半角カンマで区切って列挙する。左に記述したものが優先される。&br; 個別スロットは、パラメータを半角コロンで区切って記述する。 食品属性を指定した場合、指定された属性を持つ食品がスロットに抽出される。 栄養素コードを指定した場合、指定された栄養素が最も多い順または少ない順に抽出される。 &br; 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 ** カスタムフィルター排他条件 [#s41e35c7] 以下のカスタムフィルター条件は、いずれか１つのみ指定できる。いずれかのグループに属する条件を指定した場合、それ以外のグループに属する条件は無効となる。複数グループにまたがって指定された場合は、優先度の小さいものが有効となる。 |グループ|パラメータ名|優先度|h |M&Mメニュー|SearchTarget|1| |新商品|withnewfood,withnewfood_and|2| ** 特異的取扱食品の指定 [#o02d28a8] 特異的取扱を行う食品を、objectid単位で設定できる。指定された食品は、singular=1 が指定された検索の時、検索結果の先頭に配置される。 （※使用に際し弊社が設定します。指定する食品をお知らせ下さい。） ** 特異的取扱食品の追加位置 [#o02d28a8] 本来の検索結果に追加して特異的取扱食品の結果を返す時、特異的取扱食品の結果は、本来の結果の先頭に追加される。 以下の検索が対象となる。 |パラメータ名|追加データ|h |singular|特異的取扱食品として指定タグを付与された食品群 (EAPITOP_xxx)| ※singular食品群は弊社API全体で有効な食品に対し、専有食品(弊社API全体では無効、任意APIでのみ有効)の指定としてownerexclusiveの用意がある。 ※カテゴリー指定でAPI全体で無効とする場合には「API検索除外設定」がある。（弊社判断による処理） ** 副検索結果の追加位置 [#o02d28a8] 本来の検索結果に追加して副検索の結果を返す時、副検索の結果は、本来の結果の後尾に追加され、以下の副検索が対象となる。 |パラメータ名|追加データ|h |withnewfood|新商品| |withnewfood_and|新商品| ※純粋な結果としては後尾に追加されるが、新商品も栄養素フィルタ対象になり、且つ、ソートした場合には必ずしも後尾とは限らない。 ** 複数検索語による検索（画像認識支援等用途） [#c8331b10] - multiplexer=1 引数に multiplexer=1 を追加することで本機能を利用する。2番目以降の検索語を、_M(番号)needle=検索語 として追加する。番号は1から始まり、0番はURL中の標準検索語となる。 - multiplex_mixtureunit=N 結果を混合するとき、各検索番からN個ずつ取る指定。省略時はN=1 - multiplex_mixturetype=xxx 結果を混合する順番。xxx=roundrobin の場合、0番から順番に取る。xxx=random の場合、ランダムに取る。（省略時はroundrobin） - 返値 obj.foods 従来と同じフォーマットの検索結果&br; obj.foods.(配列の添字).multiplex_index 発生源として各検索番に対応した番号&br; obj.multiplex 複数検索語の情報&br; ※結果数は最大500とし、その他の引数はcustomと同じ。全ての検索番に共通してパラメータが適用される。そのため、検索結果指定数×multiplexer設定数の結果が原則レスポンスされる。 ** 補助処理のオプション [#m051cee1] |パラメータ名|引数|内容|h |html_entity_decode|実施する=1/実施しない=0または省略|実体参照のデコード。項目nameに実体参照が含まれている場合はデコードする。| ** 検索文字列ルール [#u55567aa] [[検索文字列ルール>API利用ガイド#u55567aa]] に従う。 (2022/7頃から適用)&br; 検索結果の候補は、半角英字の大小を区別せず用意されるが、半角英字の大小を区別して検索文字列にマッチしない結果は除外される。&br; (demo06にのみ適用)&br; 但し次の場合を除く。&br; 検索文字列が全て英数字であって、且つ文字数が3文字以上の場合、半角英字の大小を区別せず検索文字列にマッチしない結果は除外される。&br; ** 入力される検索文字列の取り扱い [#xe17b367] 検索文字列は、半角スペース(" ")で区切られた複数の語によって構成される。&br; 入力された各検索語は、先頭から全角6文字相当(半角12文字相当)までが採用され、それ以降の部分は切り捨てて使用される。 ** クエリー例 [#ea78dac9] 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 &html_entity_decode=1 ** レスポンス [#b7e56e30] レスポンスコードは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" : メーカー名, }, { (食品データ) }, : ] } ** レスポンス例 [#i994a280] #html{{ <pre class="brush:xml;"> { "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" } ] }</pre> }} * 考慮事項 [#wa8c2055] 本APIの返却するデータは、クライアント側で適切にキャッシュ等を行い、アクセス量を低減させることが望ましい。 ※但し、特に新商品の更新は常時行われているので、必要に応じて対処願いたい。 * バージョン [#o0becc47] * 仕様変更履歴 [#t05ebefa] 2022/9/15 flagsn について、例外的メーカー名「商品」「外食」「テイクアウト」はメーカー名無しとして扱うのを削除 2022/10/15 特異的取扱食品の追加位置 について、ownerexclusive の説明を追加 このドキュメントのバージョン情報 |Version|1| |Revision|1| |Editor|IMD|
