エクササイズ検索API：クエリと6言語の扱い

APIキーを付けてqを送ります。qがないリクエストは400エラーになります。結果は一覧と同じ{ data, pagination }の形で返り、関連度順に並び、同順位はidで決まります。ページは既定で50件、最大100件です。

curl -H "Authorization: Bearer fed_live_YOUR_KEY" \
  "https://api.fitexercisedb.com/v1/exercises/search?q=squat&pageSize=10&lang=fr"

各結果にはレスポンス項目リファレンスで説明した全項目が含まれます。内部では、種目名、ターゲット筋、器具に対するPostgreSQLの全文検索で、それ以外はインデックスされません。

インデックスにはPostgreSQLのsimpleテキスト設定が使われ、単語は小文字になりますが語幹処理はされません。クエリはplainto_tsqueryで作られ、すべての単語を要求します。そのため、完全な単語だけが一致し、送ったすべての単語が含まれている必要があります。

入力補完が必要なら、必要な分類と名前を一度読み込んでキャッシュし、ローカルで絞り込み、最後の照会にだけ検索を使います。コードを書く前に、エクササイズデータベースでクエリを試してデータの中身を確認してください。

クエリを翻訳するやり方では検索できません。検索対象は英語の名前、ターゲット筋、器具で、翻訳された名前はインデックスに含まれないため、他言語の単語は英語と同じつづりのときだけ一致します。langパラメータが変えるのは返ってくる内容であり、照合の対象ではありません。

ローカライズした検索ボックスでは、ユーザーの入力を自分で英語の語に置き換え、そのうえでユーザーの言語のテキストをAPIに求めるのが有効です。

// The user types in French. You map it to English terms, then ask for French text back.
const q = toEnglish("développé couché");        // your own mapping: "bench press"
const url = `/v1/exercises/search?q=${encodeURIComponent(q)}&lang=fr`;

よくあるケースでは自由入力を避け、部位、筋肉、器具のドロップダウンを用意し、英語の値をキーにして翻訳したラベルを表示します。

3つの情報源を順に確認し、最初に対応しているものが採用されます。どの場合もエラーにはなりません。

地域サフィックスは無視されるため、fr-FRとpt-BRはfrとptに解決されます。ヘッダーは書かれた順に走査され、最初に対応しているタグが使われ、品質値の比較は行われません。deのような値は未対応で、黙って英語になります。すべてのレスポンスに使用した言語が示されます。

Content-Language: fr
Vary: Accept-Language

同じURLでもAccept-Languageによって返るテキストが変わるため、言語をキャッシュキーに含めるか、langを明示的に送ってください。

最後の行が落とし穴です。フランス語のレスポンスでは胸がPoitrineと表示されますが、フィルターが求めるのはChestです。

# the filter value stays English, the labels come back in French
curl -H "Authorization: Bearer fed_live_YOUR_KEY" \
  "https://api.fitexercisedb.com/v1/exercises?bodyPart=Chest&lang=fr"

フィルター用のリストはlangなしで一度取得し、その値をキーとして保存してください。正確なリストはドキュメントにあります。