フィルタリング

フィルタリングは /query（複数結果検索）にのみ適用されます。単一結果の /movie と /random エンドポイントはフィルターを受け付けません。

1. クイックスタート

すべての /query リクエストは、検索語 q に加えて 4 つのオプション入力を 受け付けます：filter、sort、page、num（ページサイズ）。GET（クエリ文字列）と POST（JSON ボディ）の両方で動作します。

KEY="jvi_..."   # your API key, sent as the x-javinfo-key header

# POST — genre + runtime filter, newest first
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{
        "q": "ema kisaki",
        "filter": { "genre": "Big Tits", "runtimeMin": 120 },
        "sort": "release",
        "page": 1
      }'

# GET — same thing, flattened into query params
curl -s "https://api.javinfo.dev/query?q=ema%20kisaki&filter[genre]=Big%20Tits&filter[runtimeMin]=120&sort=release" \
  -H "x-javinfo-key: $KEY"

フィルターが指定されている場合、q は省略可能です — キーワードなしで カテゴリー全体を閲覧できます：

# All "creampie" titles, no search term
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "filter": { "genre": "creampie" } }'

q もフィルターもないリクエストは 400 （"provide a search query or at least one filter"）で拒否されます。

フィルターの有無にかかわらず、成功した /query 呼び出しごとに一律 200 ユニットの料金がかかります。結果が返らない（404）またはエラーになる リクエストは無料です。

2. 入力パラメーター

filter

オブジェクトです。すべてのフィールドは任意です。必要なものだけ設定してください。

sort

次のいずれか：relevance（デフォルト）、release、update、rating、views。

• relevance — テキストマッチの関連度（省略時のデフォルト）。
• release — 発売日が新しい順。
• update — 最近追加/更新された順。
• rating — 評価が高い順。
• views — 予約済み；まだどのプロバイダーも対応していません（常に拒否）。

page

1 始まりの整数。省略時は 1 ページ目。ページサイズは num で設定します。

num

1 ページあたりの結果数。整数、デフォルト 10、最大 50（超過した値は拒否ではなくクランプされます；num < 1 → 400）。プロバイダーごとにベストエフォート：javdatabase はサイト固定のアーカイブページサイズの範囲内でのみ従います（返される行数を制限）；missav は検索件数を上限とします。page のオフセットは num から計算されます（num=10 の 2 ページ目は最初の 10 件をスキップ）。

GET の数値強制変換。 num はクエリ文字列から数値に強制変換されますが、page とネストされた filter[...] の数値はまだされません — GET ではそれらは 400 "expected number, received string" で拒否されます。修正されるまでは、page と数値フィルターは POST JSON で送ってください。

3. プロバイダー対応マトリクス

/query は複数のプロバイダーを検索します。すべてのプロバイダーがすべての フィルターに対応しているわけではありません。これはシステムの核心です — クエリを組み立てる前に必ず読んでください。

プロバイダー（および ID）：query:fanza、query:dmm（DMM + FANZA の2つのストアフロント）、query:missav、 query:javdb、query:javdatabase。

凡例：✅ 対応 · ❌ 非対応 · ≈ 受け付けるがデフォルトの挙動になる。

補足：

• fanza/dmm はモザイクありのみ — uncensored フィルターはこれらを除外します。
• javdb にはフィールド単位のフィルターがありません（genre/actress など）。 粗いモザイク有無のタブ、availability、そして充実したソートのみを提供します。 javdb に名前付きの次元を要求すると除外されます。
• javdatabase は genre + maker のみ組み合わせ可能（ジャンル ∩ スタジオのアーカイブ）；それ以外の組み合わせは除外されます。
• missav は page を無視します — 常にマッチした最初のページを返します。
• missav は sort を無視します — 結果は関連度順のみです。

4. プロバイダー選択の仕組み（ウォーターフォール）

/query はプロバイダーを順番に試し、最初の有効な結果が採用されます：

FANZA → DMM → missav → javdb → javdatabase

プロバイダーが満たせないフィルターがどう扱われるかは、プロバイダーを **ピン留め（pin）**したかどうかによります。

ピン留めなし（デフォルト）— スキップして次へ

providers を送らない場合、登録済みのすべてのプロバイダーが候補になります。 フィルターを完全に満たせないプロバイダーは黙ってスキップされ、 ウォーターフォールは次へ進みます。リクエスト全体を満たせる最初のプロバイダー から結果を得ます。

# sort=rating is javdb-only → fanza/dmm/missav/javdatabase are skipped,
# javdb answers.
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "q": "ABP", "sort": "rating" }'
# → { "source": "javdb", ... }

どのプロバイダーもリクエストを満たせない場合、理由を説明するメッセージ付きの 422 が返されます。

ピン留めあり — ハードエラー

特定のプロバイダー（またはセット）を強制するには providers を送ります。 ピン留めしたプロバイダーがフィルターを満たせない場合、リクエストは 422 で失敗し、message に理由が示されます — 黙って破棄されることはありません。

# Pin javdb, ask for a genre it can't filter → 422
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "q": "x", "providers": ["query:javdb"], "filter": { "genre": "creampie" } }'
# → 422 { "message": "does not support filter \"genre\"" }

# Pin fanza, ask for uncensored → 422
#   → { "message": "does not support uncensored content" }

providers はカンマ区切りのリストまたは配列を受け付け、query: プレフィックスは 付けても付けなくても構いません："providers": ["fanza","missav"] または "providers": "javdb"。

5. 値はそのまま透過されます（重要）

これは v1 の透過（パススルー）設計です：フィルター値に入れたものは、その プロバイダー自身のバックエンドにそのまま送られます。共有の分類体系はなく、 プロバイダーをまたいだあいまい検索もありません。あるプロバイダーで機能する値は、 別のプロバイダーではマッチしないことがよくあります。各ソースがメタデータを 保存する方法が異なるためです。

考慮すべき影響：

• ジャンルはプロバイダーごとに異なります。

  • fanza/dmm と javdatabase は英語のジャンル名を使います（"Big Tits"、 "creampie"）。
  • missav のジャンルは日本語です（"巨乳"、"フィスト"）。英語の ジャンルは missav では何も返しません。

• 名前は完全一致が必要です。 フィルターは部分文字列ではなく完全一致です。 DMM + FANZA インデックスでは、女優は別名が名前に組み込まれた形で保存されます。例： "Ema Kisaki (HARUKI, Haruki Kato)"。そこで actress: "Ema Kisaki" で フィルターするとゼロ件になります — 保存されている完全な文字列が必要です。 （これは v1 の既知の粗い部分です。）

• censored はソースごとに意味が異なります。 missav には文字どおりの 「censored/uncensored」フラグはありません。API は censored を主流の モザイク作品に、uncensored をそれ以外すべて（Caribbeancom、10musume、 Tokyo-Hot、1pondo、FC2、無修正流出など）にマッピングします。

• javdatabase のパスは slug 化されます。 maker: "S1 NO.1 STYLE" は 自動的に s1-no-1-style スタジオアーカイブになります — 人間が読める名前を 渡せば、slug は自動生成されます。

値がマッチしない場合、そのプロバイダーから得られる件数が減る（または 0 件に なる）だけです（ピン留めしていなければウォーターフォールは次へ進みます）。 エラーにはなりません — マッチが空であることはエラーではありません。

6. レスポンスの構造

ボディは、採用されたプロバイダーの結果セットです：

{
  "q": "ema kisaki",        // your query, echoed
  "source": "fanza",        // which provider answered
  "count": 10,              // results this page (default 10, set by num)
  "results": [
    {
      "id": "118abp00999",          // stable id (content id or dvd id)
      "dvdId": "ABP-999",
      "title": "…",
      "cover": "https://…/…ps.jpg",
      "releaseDate": "2019-01-04",
      "extra": {                    // provider-specific, keys vary by source
        "runtimeMins": 130,
        "maker": "…",
        "categories": ["Big Tits", "…"],
        "actresses": [{ "name": "…", "image": "https://…|null" }],
        "duration": 7800,           // missav (seconds)
        "genres": ["巨乳"],          // missav
        "studio": "…", "url": "…"   // javdatabase
        // …
      }
    }
  ]
}

extra はスーパーセットです — 応答したプロバイダーが実際に生成したキーのみが 含まれます。コアフィールド（id、dvdId、title、cover、releaseDate）は すべてのプロバイダーで一貫しています。

レスポンスヘッダーはメタデータを保持します：X-Response-Time-Ms、 X-Balance-Remaining。

7. プロバイダー別チートシート

fanza / dmm（DMM + FANZA ストアフロント）— 最も充実した構造化フィルタリング。

• すべての名前付き次元を自由に組み合わせ可能。英語のジャンル/名前の値。
• runtimeMin/runtimeMax は分単位。sort: release。ページング対応。
• モザイクありのカタログのみ — uncensored、availability、発売日範囲はなし。

# Big-tits titles over 120 min, newest first
-d '{ "filter": { "genre": "Big Tits", "runtimeMin": 120 }, "sort": "release" }'

missav — 最も広いフィルター範囲だが、関連度順のみ。

• すべての名前付き次元（ジャンルは日本語）、再生時間および発売日の 範囲、censored の両方向。
• sort なし（関連度のみ）、実質的なページングなし（1 ページ目のみ）、 availability なし。

# Uncensored titles matching "caribbean"
-d '{ "q": "caribbean", "filter": { "censored": "uncensored" } }'
# Japanese genre browse
-d '{ "q": "SSIS", "filter": { "genre": "巨乳" } }'

javdb — フィールドフィルターはないが、最良のソート + availability。

• censored（両方）、availability、sort（relevance/release/update/rating）のみ。
• ページング対応。genre/actress/maker などはなし。

# Playable, highest rated
-d '{ "q": "ABP", "filter": { "availability": "playable" }, "sort": "rating" }'

javdatabase — 単一の次元でのアーカイブ閲覧（または genre ∩ maker）。

• genre、actress、maker、series、director；組み合わせ可能なのは genre+maker のみ。モザイクあり + 無修正。英語の値で、自動的に slug 化。 ページング対応。
• 再生時間/発売日の範囲なし、label/actor なし、実質的なソートなし （新しい順）。

# Creampie titles from S1
-d '{ "filter": { "genre": "creampie", "maker": "S1 NO.1 STYLE" } }'

8. できないこと（v1）

• プロバイダーをまたいだ値の正規化。 統一されたジャンル/女優の語彙は ありません — 各プロバイダーの方言（英語 vs 日本語、正確な文字列）を 使い分ける必要があります。
• sort: views — 予約済みで、どのプロバイダーも実装していません。
• 1 次元あたり複数値。 1 フィールドにつき 1 値のみ（genre: ["a","b"] は不可）。
• 対応プロバイダー以外での範囲指定。 再生時間の範囲は fanza/dmm/missav のみ、 発売日の範囲は missav のみ。
• javdb 以外での availability。
• javdb（不可）または javdatabase（genre+maker のみ）での任意フィルターの 組み合わせ。
• missav でのページング/ソート。
• /movie や /random のフィルタリング。

組み合わせが不可能な場合：ピン留めあり → 理由付きの 422；ピン留めなし → そのプロバイダーはスキップされ、次が試されます。

次へ

• 完全な API リファレンスを見る — /query オペレーションはすべてのフィルターパラメーターをライブプレイグラウンド付きで一覧します。
• 400 と 422 のケースについてはエラーを参照。