#author("2020-12-02T14:33:19+09:00","","")
[[FrontPage]]
&size(24){データAPI/構成食材による検索};
※本API機能は追加オプションご契約の方のみがご利用になれるものです。
* API情報 [#q6190828]
|~名称|構成食材による検索|
|~APIバージョン|2|
|~認証タイプ|なし|
|~URL|https://(APIサーバー名)/services/api2/(アクセスコード)/search/byelement/json/素材objectidまたは基本素材検索語/ &br;https://(APIサーバー名)/services/api2/(アクセスコード)/search/byelement/json/素材objectidまたは基本素材検索語/開始位置/表示個数/|
|~Method|GET|
|~データ更新頻度目安|1週間|
* 概要 [#jfe13a2c]
素材に指定した食品を含む食品を検索し、カスタムフィルター及びカスタムソートを実施する。文字列の比較対象は、名前、よみ、三階層カテゴリー名となる。
** 入力するobjectidまたは語 [#qd87e318]
入力は、素材となる食品のobjectid、または[[データAPI/基本素材リスト文字列検索]]に適用される文字列、のいずれかを取る。&br;
'FO'で始まる文字列は、素材objectidとして解釈される。それ以外の文字列は、[[データAPI/基本素材リスト文字列検索]]を実行し、その結果を素材objectidとして採用する。&br;
objectid及び文字列は単一のみとし、文字列が複数合致する場合は、[[データAPI/基本素材リスト文字列検索]]での検索結果順の素材で検索し、当該順に最大500件まで出力する。
** カスタムフィルター [#qcf1465c]
フィルター処理は、文言除外フィルター、文言限定フィルター、構成要素除外フィルター、構成要素限定フィルター、栄養素値フィルターの各処理が実施される。
- 文言フィルターの対象となるのは、名前、読み、カテゴリーの各文字列である。(複数可)
- 文言除外フィルターは、名前、読み、カテゴリーに指定文字列を全てまたはいずれかを含むものは結果から除外される。
- 文言限定フィルターは、名前、読み、カテゴリーに指定文字列を全てまたはいずれかを含むもののみが結果に含まれる。
- 構成要素除外フィルターは、指定されたobjectidを構成要素に含むものは結果から除外される。
- 構成要素限定フィルターは、指定されたobjectidを構成要素に含むもののみが結果に含まれる。
- 栄養素値フィルターは範囲指定の場合、指定された栄養素について、指定された範囲を外れたものは結果から除外される。(全栄養素対象に、複数栄養素に対応)
- 栄養素値フィルターは存在指定の場合（shopname項目の指定時）、指定された栄養素または項目について、存在しているものまたは存在していないものは結果から除外される。
- メーカー名付きフラグは、商品又は一般料理の区分に対応し、yesの場合は商品、noの場合は一般料理のみを結果に返す
- 検索方向は、素材objectidを素材として含む量が多い方または少ない方から結果を抽出する。カスタムソートを指定しない場合、出現順は素材objectidの順となる。
** カスタムソート [#c0b91488]
指定された栄養素について、昇順または降順によって、結果をソートする。
** 注意点 [#c0b91488]
フィルター条件により適合した食品数が5000件に達した時点で候補の抽出は打ち切られ、5000件までの候補の中でカスタムソートが実行される。このため、フィルター条件の結果数が多くなる場合、ソート結果の１位及び末尾が、全食品中での最大値又は最小値とならない場合がある。
* アクセス手順 [#ya59d11f]
** クエリー [#l9016c71]
https://(APIサーバー名)/services/api2/(アクセスコード)/search/byelement/json/(素材objectidまたは基本素材検索語)/?(カスタムフィルター条件) &br;
素材objectidまたは基本素材検索語で検索した結果にカスタムフィルター条件を適用して返却する。
https://(APIサーバー名)/services/api2/(アクセスコード)/search/byelement/json/(素材objectidまたは基本素材検索語)/(開始位置)/(表示個数)/?(カスタムフィルター条件) &br;
素材objectidまたは基本素材検索語で検索した結果にカスタムフィルター条件を適用し、0から始まるインデックスの(開始位置)番目から、(表示個数)個のアイテムを返却する。
検索文字列がマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。
クエリー (GET) の最大値は 8192 Byte(8KB) とする。
** カスタムフィルター条件 [#m051cee1]
カスタムフィルターは、クエリー文字列としてクエリー末尾に付加する。
文字列パラメータがマルチバイトの場合は、文字コードをUTF-8としURLエンコードを施したものとする。
カスタムフィルター条件は省略可能であり、省略されたものは実施されない。
|パラメータ名|内容|形式|省略可否|h
|exword|文言除外フィルター指定文字列&br;複数指定時は半角スペースで区切る|文字列|省略可・未指定時非実施|
|excond|文言除外フィルター除外条件|OR条件=or AND条件=and|exword指定時必須|
|inword|文言限定フィルター指定文字列&br;複数指定時は半角スペースで区切る|文字列|省略可・未指定時非実施|
|incond|文言限定フィルター除外条件|OR条件=or AND条件=and|inword指定時必須|
|exelement|構成要素除外フィルター指定objectid&br;複数指定時は半角スペースで区切る|文字列|省略可・未指定時非実施|
|execond|構成要素除外フィルター除外条件|OR条件=or AND条件=and|exelement指定時必須|
|inelement|構成要素限定フィルター指定objectid&br;複数指定時は半角スペースで区切る|文字列|省略可・未指定時非実施|
|inecond|構成要素限定フィルター除外条件|OR条件=or AND条件=and|exelement指定時必須|
|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|栄養素コード|省略可・未指定時非実施|
|sort_dir|カスタムソート順序|昇順=asc 降順=desc|sort_id指定時必須|
|flagsn|メーカー名付きフラグ|メーカー名付きのみ=yes メーカー名なしのみ=no 両方=both|省略可・省略時both|
|searchorder|検索方向|多い方から検索=desc 少ない方から検索=asc|省略可・省略時desc|
|keyelement|構成食材包含フィルター|上位3件に 素材objectidを含むものを優先=prio 素材objectidを含むものに限定=only|省略可・未指定時非実施|
|prioritizer|構成食材に指定objectidを含むものを優先|objectid|keyelementにprio指定時のみ有効・省略可・省略時は素材objectid|
|filtersn|メーカー名フィルター&br;shopnameフィールドに対して指定された文字列でフィルターする|文字列|任意|
|filtersn_match|メーカー名フィルターマッチ方式&br;|完全一致=full 部分一致=part |省略時part|
|filtercatN|カテゴリー階層マッチ&br;caregorytreeフィールド内のいずれかに対して指定された文字列でフィルターする&br;Nは1～3を半角数値で指定。完全一致で判定される。|文字列|任意|
** クエリー例 [#ea78dac9]
https://(APIサーバー名)/services/api2/(アクセスコード)/search/byelement/json/FO9ee10c4c46d307f56af1f494/0/100/?inword=ジョナサン&incond=and&exstuff_id1=carbo&exstuff_upper1=100&exstuff_lower1=20&sort_id=stuff_e&sort_dir=asc
** レスポンス [#b7e56e30]
レスポンスコードは200を返し、レスポンスはjson形式である。レスポンスされる食品数の最大値は 500 である。
検索結果が存在しない場合は長さ0の配列が返される。クエリー書式誤り等の場合はレスポンスコード404が返される。
フィールド indexedby は、キーとなった構成食材のobjectidを表す。
{
"foods": [
{
"name": 食品名,
"yomi": 食品名よみ,
"objectid": オブジェクトID,
"unit": 分量,
"stuff_e": カロリー,
"indexedby": オブジェクトID,
:
"categorytree": [
第1階層カテゴリー名,
第2階層カテゴリー名,
第3階層カテゴリー名,
],
"shopname": メーカー名,
"elements": [
{
"elementid": 構成食材オブジェクトID,
"elementunit": 構成食材分量
},
:
]
},
{
(食品データ)
},
:
],
}
** レスポンス例 [#i994a280]
#html{{
<pre class="brush:xml;">
{
"foods": [
{
"name": "スープモーニング(ジョナサン)",
"yomi": "すーぷもーにんぐじょなさん",
"objectid": "FOa25029224c6350a437706fe2",
"unit": 222,
"stuff_e": 415.2,
"stuff_p": 11.5,
"stuff_f": 14.8,
"stuff_c": 59.4,
"stuff_fiber": 3.9,
"carbo": 55.5,
"categorytree": [
"洋食",
"定食\/セット",
"その他セットメニュー"
],
"shopname": "ジョナサン",
"elements": [
{
"elementid": "FO2653a0de46d307c50459d96d",
"elementunit": 60
},
{
"elementid": "FOf426ae2846d307c61283e19d",
"elementunit": 20
},
{
"elementid": "FOc889202846d3086f26e66bb5",
"elementunit": 6
}
]
},
{
"name": "チキンと野菜のトマト煮込みセット キャロットパンとハーブゼリーつき(ジョナサン)",
"yomi": "ちきんとやさいのとまとにこみせっと きゃろっとぱんとはーぶぜりーつき じょなさん",
:
}
],
}</pre>
}}
* 考慮事項 [#wa8c2055]
本APIの返却するデータは、クライアント側で適切にキャッシュ等を行い、アクセス量を低減させることが望ましい。
* バージョン [#o0becc47]
このドキュメントのバージョン情報
|Version|1|
|Revision|1|
|Editor|west|
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
