Фильтрация

Фильтрация применяется только к /query (поиск с несколькими результатами). Конечные точки с одним результатом /movie и /random не принимают фильтры.

1. Быстрый старт

Каждый запрос /query принимает четыре необязательных параметра в дополнение к поисковому запросу q: 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").

Стоимость — фиксированные 200 единиц за каждый успешный вызов /query независимо от фильтров. Запрос, который не возвращает результата (404) или завершается ошибкой, бесплатен.

2. Параметры

filter

Объект. Все поля необязательны. Задавайте только те, которые вам нужны.

sort

Одно из: relevance (по умолчанию), release, update, rating, views.

• relevance — релевантность текстового совпадения (по умолчанию, если не указано).
• release — сначала самые новые по дате выпуска.
• update — сначала недавно добавленные/обновлённые.
• rating — сначала с наивысшим рейтингом.
• views — зарезервировано; пока не поддерживается ни одним провайдером (всегда отклоняется).

page

Целое число, начиная с 1. Не указано = страница 1. Размер страницы задаётся параметром num.

num

Количество результатов на страницу. Целое число, по умолчанию 10, максимум 50 (более высокие значения ограничиваются, а не отклоняются; num < 1 → 400). По возможности для каждого провайдера: javdatabase учитывает его только до фиксированного размера архивной страницы сайта (ограничивает количество возвращаемых строк); missav ограничивает его своим числом результатов поиска. Смещение page вычисляется из num (страница 2 при num=10 пропускает первые 10).

Числовое приведение в GET. num приводится из строки запроса, а page и вложенные числа filter[...] — пока нет: на GET они отклоняются с 400 "expected number, received string". Отправляйте page и числовые фильтры через POST JSON, пока это не исправлено.

3. Матрица возможностей провайдеров

/query ищет по нескольким провайдерам. Не каждый провайдер поддерживает каждый фильтр. Это суть всей системы — прочитайте это перед составлением запросов.

Провайдеры (и их идентификаторы): query:fanza, query:dmm (две витрины DMM + FANZA), 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

Что произойдёт с фильтром, который провайдер не может удовлетворить, зависит от того, закрепили ли вы провайдеров.

Без закрепления (по умолчанию) — пропустить и перейти дальше

Если вы не отправляете 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 преобразуются в слаги. maker: "S1 NO.1 STYLE" автоматически становится архивом студии s1-no-1-style — передавайте читаемое имя, слаг выводится за вас.

Если значение не совпадает, вы просто получаете меньше строк или ни одной от этого провайдера (и, если не закреплено, каскад продолжается). Ничего не завершается ошибкой — пустое совпадение не является ошибкой.

6. Форма ответа

Тело — это набор результатов от победившего провайдера:

{
  "q": "ema kisaki",        // your query, echoed
  "source": "fanza",        // which provider answered
  "count": 10,              // 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 — без фильтров по полям, но лучшая сортировка + доступность.

• Только 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. С цензурой + без цензуры. Английские значения, автоматически преобразуются в слаги. С разбивкой на страницы.
• Без диапазона продолжительности/дат выпуска, без label/actor, без настоящей сортировки (сначала новейшие).

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

8. Что НЕВОЗМОЖНО (v1)

• Нормализация значений между провайдерами. Нет единого словаря жанров/актрис — вы должны говорить на диалекте каждого провайдера (английский или японский, точные строки).
• sort: views — зарезервировано, ни один провайдер не реализует.
• Несколько значений на измерение. Одно значение на поле (нельзя genre: ["a","b"]).
• Диапазоны вне их провайдера. Диапазон продолжительности только у fanza/dmm/missav; диапазон дат выпуска только у missav.
• availability где-либо, кроме javdb.
• Комбинирование произвольных фильтров на javdb (никаких) или javdatabase (только genre+maker).
• Разбивка на страницы / сортировка на missav.
• Фильтрация /movie или /random.

Когда комбинация невозможна: закреплено → 422 с причиной; не закреплено → этот провайдер пропускается и пробуется следующий.

Далее

• Просмотрите полный справочник API — операция /query перечисляет каждый параметр фильтра с интерактивной песочницей.
• См. Ошибки для случаев 400 и 422.