Filtrado

El filtrado se aplica solo a /query (búsqueda de múltiples resultados). Los endpoints de resultado único /movie y /random no aceptan filtros.

1. Inicio rápido

Cada solicitud a /query acepta cuatro entradas opcionales además del término de búsqueda q: filter, sort, page y num (tamaño de página). Funciona tanto con GET (cadena de consulta) como con POST (cuerpo 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 es opcional cuando hay un filtro presente — puedes explorar una categoría completa sin ninguna palabra clave:

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

Una solicitud sin q ni filtro se rechaza con 400 ("provide a search query or at least one filter").

El costo es fijo de 200 unidades por cada llamada exitosa a /query, independientemente de los filtros. Una solicitud que no devuelve resultados (404) o que da error es gratuita.

2. Las entradas

filter

Un objeto. Todos los campos son opcionales. Configura solo los que necesites.

sort

Uno de: relevance (predeterminado), release, update, rating, views.

• relevance — relevancia por coincidencia de texto (predeterminado cuando se omite).
• release — fecha de lanzamiento más reciente primero.
• update — añadidos/actualizados recientemente primero.
• rating — mejor valorados primero.
• views — reservado; ningún proveedor lo admite todavía (siempre se rechaza).

page

Entero basado en 1. Omitido = página 1. El tamaño de página lo define num.

num

Resultados por página. Entero, predeterminado 10, máximo 50 (los valores mayores se recortan, no se rechazan; num < 1 → 400). Mejor esfuerzo según el proveedor: javdatabase lo respeta solo hasta el tamaño de página de archivo fijo del sitio (limita las filas devueltas); missav lo limita a su recuento de búsqueda. El desplazamiento de page se calcula a partir de num (la página 2 con num=10 omite las primeras 10).

Coerción numérica en GET. num se convierte desde la cadena de consulta, pero los números de page y de filter[...] anidados aún no — en GET se rechazan con 400 "expected number, received string". Envía page y los filtros numéricos vía POST JSON hasta que se corrija.

3. Matriz de capacidades por proveedor

/query busca en múltiples proveedores. No todos los proveedores admiten todos los filtros. Este es el núcleo del sistema — léelo antes de construir consultas.

Proveedores (y sus ids): query:fanza, query:dmm (las dos tiendas DMM + FANZA), query:missav, query:javdb, query:javdatabase.

Leyenda: ✅ admitido · ❌ no admitido · ≈ aceptado pero se comporta como el valor predeterminado.

Notas:

• fanza/dmm son solo censurados — un filtro uncensored los excluye.
• javdb no tiene filtros por campo (genre/actress/etc). Solo ofrece la pestaña general de censurados, availability y ordenación avanzada. Pedir a javdb cualquier dimensión con nombre lo excluye.
• javdatabase combina solo genre + maker (un archivo género ∩ estudio); cualquier otro par lo excluye.
• missav ignora page — siempre devuelve la primera página de coincidencias.
• missav ignora sort — los resultados solo se ordenan por relevancia.

4. Cómo funciona la selección de proveedores (la cascada)

/query prueba los proveedores en orden, gana el primer resultado válido:

FANZA → DMM → missav → javdb → javdatabase

Lo que ocurre con un filtro que un proveedor no puede satisfacer depende de si has fijado proveedores.

Sin fijar (predeterminado) — omitir y avanzar

Si no envías providers, todos los proveedores registrados son candidatos. Cualquier proveedor que no pueda satisfacer completamente tu filtro se omite silenciosamente, y la cascada avanza al siguiente. Obtienes un resultado del primer proveedor que sí puede atender toda la solicitud.

# 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 ningún proveedor puede satisfacer la solicitud, obtienes 422 con un mensaje que explica por qué.

Fijado — error definitivo

Envía providers para forzar un proveedor específico (o conjunto). Si un proveedor fijado no puede satisfacer el filtro, la solicitud falla con 422 y un message que indica el motivo — nunca se descarta silenciosamente.

# 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 acepta una lista separada por comas o un array, con o sin el prefijo query:: "providers": ["fanza","missav"] o "providers": "javdb".

5. Los valores se pasan tal cual (importante)

Este es un diseño de paso directo (pass-through) v1: lo que pongas en el valor de un filtro se envía al backend del propio proveedor tal cual. No hay taxonomía compartida ni coincidencia aproximada entre proveedores. Un valor que funciona en un proveedor a menudo no coincidirá en otro, porque cada fuente almacena sus metadatos de forma diferente.

Consecuencias que debes prever:

• Los géneros difieren según el proveedor.

  • fanza/dmm y javdatabase usan nombres de género en inglés ("Big Tits", "creampie").
  • los géneros de missav están en japonés ("巨乳", "フィスト"). Un género en inglés no devolverá nada en missav.

• Los nombres deben coincidir exactamente. Los filtros son de coincidencia exacta, no de subcadena. En el índice DMM + FANZA una actriz se almacena con sus alias incluidos en el nombre, p. ej. "Ema Kisaki (HARUKI, Haruki Kato)". Filtrar por actress: "Ema Kisaki" devuelve cero filas allí — necesitas la cadena completa almacenada. (Esta es una aspereza conocida de la v1.)

• censored significa cosas distintas según la fuente. En missav no hay una marca literal de "censurado/sin censura"; la API asigna censored → títulos de mosaico convencionales y uncensored → todo lo demás (Caribbeancom, 10musume, Tokyo-Hot, 1pondo, FC2, filtraciones sin censura, …).

• Las rutas de javdatabase se convierten en slug. maker: "S1 NO.1 STYLE" se convierte automáticamente en el archivo de estudio s1-no-1-style — pasa el nombre legible por humanos, el slug se deriva por ti.

Si un valor no coincide, simplemente obtienes menos/ninguna fila de ese proveedor (y, si no está fijado, la cascada continúa). Nada da error — una coincidencia vacía no es un error.

6. Forma de la respuesta

El cuerpo es el conjunto de resultados del proveedor ganador:

{
  "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 es un superconjunto — solo están presentes las claves que produce el proveedor que responde. Los campos principales (id, dvdId, title, cover, releaseDate) son consistentes en todos los proveedores.

Los encabezados de respuesta transportan metadatos: X-Response-Time-Ms, X-Balance-Remaining.

7. Guía rápida por proveedor

fanza / dmm (las tiendas DMM + FANZA) — el filtrado estructurado más completo.

• Todas las dimensiones con nombre, combinadas libremente. Valores de género/nombre en inglés.
• runtimeMin/runtimeMax en minutos. sort: release. Paginado.
• Solo catálogo censurado — sin uncensored, sin availability, sin rango de lanzamiento.

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

missav — la mayor superficie de filtros, ordenado solo por relevancia.

• Todas las dimensiones con nombre (los géneros están en japonés), rangos de duración y de lanzamiento, censored en ambos sentidos.
• Sin sort (solo relevancia), sin paginación real (solo página 1), sin availability.

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

javdb — sin filtros por campo, pero la mejor ordenación + disponibilidad.

• Solo censored (ambos), availability y sort (relevance/release/update/rating).
• Paginado. Sin genre/actress/maker/etc.

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

javdatabase — exploración de archivo por una dimensión (o genre ∩ maker).

• genre, actress, maker, series, director; solo se combinan genre+maker. Censurado + sin censura. Valores en inglés, convertidos automáticamente en slug. Paginado.
• Sin rango de duración/lanzamiento, sin label/actor, sin ordenación real (más reciente primero).

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

8. Lo que NO es posible (v1)

• Normalización de valores entre proveedores. No hay un vocabulario unificado de género/actriz — debes hablar el dialecto de cada proveedor (inglés vs japonés, cadenas exactas).
• sort: views — reservado, ningún proveedor lo implementa.
• Múltiples valores por dimensión. Un valor por campo (no genre: ["a","b"]).
• Rangos fuera de su proveedor. El rango de duración es solo de fanza/dmm/missav; el rango de lanzamiento es solo de missav.
• availability en cualquier lugar que no sea javdb.
• Combinar filtros arbitrarios en javdb (ninguno) o javdatabase (solo genre+maker).
• Paginación / ordenación en missav.
• Filtrar /movie o /random.

Cuando una combinación no es posible: fijado → 422 con un motivo; sin fijar → ese proveedor se omite y se prueba el siguiente.

Siguiente

• Explora la referencia completa de la API — la operación /query enumera todos los parámetros de filtro con un playground interactivo.
• Consulta Errores para los casos 400 y 422.