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

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情報†

概要†

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

カスタムフィルター†

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

• 文言フィルターの対象となるのは、名前、読み、カテゴリーの各文字列である。(複数可)
• オプションwordfilterwith=rwordが指定された場合、文言フィルターの対象に関連語を追加する。
• 文言除外フィルターは、名前、読み、カテゴリーに指定文字列を全てまたはいずれかを含むものは結果から除外される。
• 栄養素値フィルターは範囲指定の場合、指定された栄養素について、指定された範囲を外れたものは結果から除外される。(全栄養素対象に、複数栄養素に対応)
• 栄養素値フィルターは存在指定の場合（shopname項目の指定時）、指定された栄養素または項目について、存在しているものまたは存在していないものは結果から除外される。 （商品又は一般料理かの区分に対応）

通常の検索結果に他の検索結果を追加するオプション（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エンコードを施したものとする。 カスタムフィルター条件は省略可能であり、省略されたものは実施されない。

カスタムスロット条件†

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

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

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

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

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

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

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

特異的取扱食品の指定†

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

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

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

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

副検索結果の追加位置†

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

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

複数検索語による検索（画像認識支援等用途）†

• 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 従来と同じフォーマットの検索結果
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
&html_entity_decode=1

レスポンス†

レスポンスコードは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 の説明を追加

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

目次

• トップページ
• APIを使用する
• 各APIの詳細
• サンプルソース