Filtrage

Le filtrage s'applique uniquement à /query (recherche multi-résultats). Les endpoints à résultat unique /movie et /random n'acceptent pas de filtres.

1. Démarrage rapide

Chaque requête /query accepte quatre entrées optionnelles en plus du terme de recherche q : filter, sort, page et num (taille de page). Fonctionne à la fois en GET (chaîne de requête) et en POST (corps 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 est optionnel lorsqu'un filtre est présent — vous pouvez parcourir toute une catégorie sans mot-clé :

# 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" } }'

Une requête sans q ni filtre est rejetée avec un 400 ("provide a search query or at least one filter").

Le coût est de 200 unités forfaitaires par appel /query réussi, quels que soient les filtres. Une requête qui ne renvoie aucun résultat (404) ou qui échoue est gratuite.

2. Les entrées

filter

Un objet. Tous les champs sont optionnels. Ne définissez que ceux dont vous avez besoin.

sort

L'une des valeurs : relevance (par défaut), release, update, rating, views.

• relevance — pertinence de correspondance textuelle (par défaut si omis).
• release — date de sortie la plus récente en premier.
• update — ajoutés/mis à jour récemment en premier.
• rating — les mieux notés en premier.
• views — réservé ; aucun fournisseur ne le prend encore en charge (toujours rejeté).

page

Entier commençant à 1. Omis = page 1. La taille de page est définie par num.

num

Résultats par page. Entier, par défaut 10, max 50 (les valeurs supérieures sont plafonnées, non rejetées ; num < 1 → 400). Au mieux selon le fournisseur : javdatabase ne le respecte que jusqu'à la taille de page d'archive fixe du site (plafonne les lignes renvoyées) ; missav le plafonne à son nombre de recherche. Le décalage de page est calculé à partir de num (la page 2 avec num=10 saute les 10 premiers).

Coercition numérique en GET. num est converti depuis la chaîne de requête, mais page et les nombres imbriqués filter[...] ne le sont pas encore — en GET ils sont rejetés avec 400 "expected number, received string". Envoyez page et les filtres numériques via POST JSON jusqu'à ce que ce soit corrigé.

3. Matrice des capacités des fournisseurs

/query interroge plusieurs fournisseurs. Tous les fournisseurs ne prennent pas en charge tous les filtres. C'est le cœur du système — lisez-le avant de construire vos requêtes.

Fournisseurs (et leurs ids) : query:fanza, query:dmm (les deux vitrines DMM + FANZA), query:missav, query:javdb, query:javdatabase.

Légende : ✅ pris en charge · ❌ non pris en charge · ≈ accepté mais se comporte comme la valeur par défaut.

Notes :

• fanza/dmm sont censurés uniquement — un filtre uncensored les exclut.
• javdb n'a pas de filtres par champ (genre/actress/etc). Il n'offre que l'onglet censuré grossier, availability et un tri riche. Demander à javdb une dimension nommée quelconque l'exclut.
• javdatabase ne combine que genre + maker (une archive genre ∩ studio) ; toute autre paire l'exclut.
• missav ignore page — il renvoie toujours la première page de correspondances.
• missav ignore sort — les résultats sont classés par pertinence uniquement.

4. Comment fonctionne la sélection du fournisseur (la cascade)

/query essaie les fournisseurs dans l'ordre, le premier résultat valide l'emporte :

FANZA → DMM → missav → javdb → javdatabase

Ce qui arrive à un filtre qu'un fournisseur ne peut pas satisfaire dépend du fait que vous ayez épinglé des fournisseurs.

Non épinglé (par défaut) — ignorer et avancer

Si vous n'envoyez pas providers, chaque fournisseur enregistré est un candidat. Tout fournisseur qui ne peut pas satisfaire pleinement votre filtre est ignoré silencieusement, et la cascade passe au suivant. Vous obtenez un résultat du premier fournisseur qui peut honorer toute la requête.

# 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", ... }

Si aucun fournisseur ne peut satisfaire la requête, vous obtenez un 422 avec un message expliquant pourquoi.

Épinglé — erreur stricte

Envoyez providers pour forcer un fournisseur spécifique (ou un ensemble). Si un fournisseur épinglé ne peut pas satisfaire le filtre, la requête échoue avec 422 et un message nommant la raison — elle n'est jamais abandonnée silencieusement.

# 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 accepte une liste séparée par des virgules ou un tableau, avec ou sans le préfixe query: : "providers": ["fanza","missav"] ou "providers": "javdb".

5. Les valeurs sont transmises telles quelles (important)

Il s'agit d'une conception v1 en transmission directe : toute valeur que vous placez dans un filtre est envoyée au backend du fournisseur concerné telle quelle. Il n'y a pas de taxonomie partagée ni de correspondance approximative entre les fournisseurs. Une valeur qui fonctionne sur un fournisseur ne correspondra souvent pas sur un autre, car chaque source stocke ses métadonnées différemment.

Conséquences à anticiper :

• Les genres diffèrent selon le fournisseur.

  • fanza/dmm et javdatabase utilisent des noms de genre en anglais ("Big Tits", "creampie").
  • Les genres de missav sont en japonais ("巨乳", "フィスト"). Un genre en anglais ne renverra rien sur missav.

• Les noms doivent correspondre exactement. Les filtres sont en correspondance exacte, pas en sous-chaîne. Sur l'index DMM + FANZA, une actrice est stockée avec ses alias intégrés dans le nom, p. ex. "Ema Kisaki (HARUKI, Haruki Kato)". Filtrer actress: "Ema Kisaki" renvoie zéro ligne dans ce cas — il vous faut la chaîne complète telle qu'elle est stockée. (C'est une limitation connue de la v1.)

• censored signifie des choses différentes selon la source. Sur missav, il n'y a pas de drapeau littéral « censored/uncensored » ; l'API fait correspondre censored → titres à mosaïque grand public et uncensored → tout le reste (Caribbeancom, 10musume, Tokyo-Hot, 1pondo, FC2, fuites non censurées, …).

• Les chemins de javdatabase sont transformés en slugs. maker: "S1 NO.1 STYLE" devient automatiquement l'archive de studio s1-no-1-style — transmettez le nom lisible, le slug est dérivé pour vous.

Si une valeur ne correspond pas, vous obtenez simplement moins de lignes (ou aucune) de ce fournisseur (et, s'il n'est pas épinglé, la cascade continue). Rien ne génère d'erreur — une correspondance vide n'est pas une erreur.

6. Format de la réponse

Le corps est l'ensemble de résultats du fournisseur gagnant :

{
  "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 est un sur-ensemble — seules les clés produites par le fournisseur qui répond sont présentes. Les champs principaux (id, dvdId, title, cover, releaseDate) sont cohérents entre tous les fournisseurs.

Les en-têtes de réponse portent des métadonnées : X-Response-Time-Ms, X-Balance-Remaining.

7. Aide-mémoire par fournisseur

fanza / dmm (les vitrines DMM + FANZA) — le filtrage structuré le plus riche.

• Toutes les dimensions nommées, librement combinées. Valeurs de genre/nom en anglais.
• runtimeMin/runtimeMax en minutes. sort: release. Paginé.
• Catalogue censuré uniquement — pas d'uncensored, pas d'availability, pas de plage de sortie.

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

missav — la surface de filtrage la plus large, classée par pertinence uniquement.

• Toutes les dimensions nommées (les genres sont en japonais), plages de durée et de sortie, censored dans les deux sens.
• Pas de sort (pertinence uniquement), pas de vraie pagination (page 1 uniquement), pas d'availability.

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

javdb — pas de filtres par champ, mais le meilleur tri + availability.

• Uniquement censored (les deux), availability et sort (relevance/release/update/rating).
• Paginé. Pas de genre/actress/maker/etc.

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

javdatabase — navigation dans les archives par une dimension (ou genre ∩ maker).

• genre, actress, maker, series, director ; seuls genre+maker se combinent. Censuré + non censuré. Valeurs en anglais, transformées automatiquement en slugs. Paginé.
• Pas de plage de durée/sortie, pas de label/actor, pas de vrai tri (les plus récents d'abord).

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

8. Ce qui n'est PAS possible (v1)

• Normalisation des valeurs entre fournisseurs. Pas de vocabulaire unifié de genre/actress — vous devez parler le dialecte de chaque fournisseur (anglais vs japonais, chaînes exactes).
• sort: views — réservé, aucun fournisseur ne l'implémente.
• Plusieurs valeurs par dimension. Une seule valeur par champ (pas de genre: ["a","b"]).
• Plages en dehors de leur fournisseur. La plage de durée est réservée à fanza/dmm/missav ; la plage de sortie est réservée à missav.
• availability ailleurs que sur javdb.
• Combiner des filtres arbitraires sur javdb (aucun) ou javdatabase (genre+maker uniquement).
• Pagination / tri sur missav.
• Filtrer /movie ou /random.

Lorsqu'une combinaison n'est pas possible : épinglé → 422 avec une raison ; non épinglé → ce fournisseur est ignoré et le suivant est essayé.

Suite

• Parcourez la référence complète de l'API — l'opération /query liste chaque paramètre de filtre avec un playground interactif.
• Consultez Erreurs pour les cas 400 et 422.