# javinfo Search API

> One endpoint for JAV release lookup: `POST /search`. Send a DVD ID such as `SSIS-001` and get one normalized result with title, cast, maker, series, cover art, and runtime. Paid plans can also return download and magnet links. Responses are cached on the server. The API is distributed through RapidAPI and is currently in beta.

Key facts:

- Site: https://javinfo.eu.org
- API host: `https://javinfo-search.p.rapidapi.com`
- RapidAPI listing (docs, keys, plans): https://rapidapi.com/iamrony777/api/javinfo
- Auth: RapidAPI headers `X-RapidAPI-Key` + `X-RapidAPI-Host`. RapidAPI handles upstream auth; you do not need a separate javinfo key.
- One endpoint: `POST /search`. Query by DVD ID / code; optionally pin providers.
- On a miss, or if every upstream times out, you get `504`. Usually the code is not indexed.

## Quick start

```bash
curl -X POST 'https://javinfo-search.p.rapidapi.com/search' \
  -H 'Content-Type: application/json' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: javinfo-search.p.rapidapi.com' \
  -d '{ "q": "SSIS-001" }'
```

JavaScript (fetch):

```js
const res = await fetch("https://javinfo-search.p.rapidapi.com/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
    "X-RapidAPI-Host": "javinfo-search.p.rapidapi.com",
  },
  body: JSON.stringify({ q: "CAWD-001", providers: "javdb" }),
});
const data = await res.json();
```

Python (requests):

```python
import requests

res = requests.post(
    "https://javinfo-search.p.rapidapi.com/search",
    headers={
        "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
        "X-RapidAPI-Host": "javinfo-search.p.rapidapi.com",
    },
    json={"q": "CAWD-001", "providers": "javdb"},
)
data = res.json()
```

## Request

`POST /search` accepts a JSON body:

- `q` (`string`, required): the code / DVD ID to look up, for example `SSIS-001`. Min length 1.
- `providers` (`string | string[]`, optional): restrict which providers to try. Use a comma-separated string such as `"r18,javdb"` or a JSON array.

If `providers` is omitted, the API tries every provider your plan allows and returns the first match. Requested providers outside your plan are ignored.

Providers:

- `r18`: bilingual metadata: title, cast, maker, label, series, covers. Available on all tiers.
- `javdb`: metadata plus download / magnet links. Pro only.
- `missav`: metadata plus HLS stream URLs (`.m3u8`). Pro only.
- `javlibrary`, `javdatabase`: coming soon.

## Response

Successful calls return the same envelope:

- `result` (`object`): the matched item: a shared base `video`, plus a per-source `extra` object on some providers. `result.source` names the provider that answered.
- `latencyMs` (`number`): server-side time to resolve.
- `cached` (`boolean`): `true` if served from the server-side cache.
- `gated` (`boolean`): `true` if paid-only fields were stripped for your plan (free tier).

Every provider maps to the same base `video` shape, so clients can read `result.video.*` the same way across sources. `r18` adds richer actress data and media fields. Providers like `javdb` add a per-source `extra` object.

Base `video` fields: `contentId`, `dvdId`, `titleEn`/`titleJa`, `commentEn`/`commentJa`, `runtimeMins`, `releaseDate`, `makers` (`string[]`), `label`, `series`, `categories` (`string[]`), `actresses` (`string[]`), `actors` (`string[]`), `directors` (`string[]`), `authors` (`string[]`), `jacketFullUrl`/`jacketThumbUrl`, `site`, `serviceCode`. `video` may be `null` when a provider matched no detail.

### source `r18` (base + media)

`r18` adds these fields to the base `video`:

- `actresses`: `{ name: string, image: string | null }[]`; this overrides the base `string[]`. `image` is a full DMM profile URL, and about 61% are `null`.
- `sampleUrl` (`string | null`): preview video / trailer URL.
- `galleryFull` (`string[]`): full-size preview image URLs.
- `galleryThumb` (`string[]`): thumbnail preview image URLs.

Note: `jacketFullUrl` / `jacketThumbUrl` are partial paths. Prefix with `https://pics.dmm.co.jp/` and append `.jpg`. Gallery fields are already full URLs.

```json
{
  "result": {
    "q": "SSIS-001",
    "source": "r18",
    "video": {
      "dvdId": "SSIS-001",
      "titleEn": "Newcomer NO.1 STYLE ...",
      "runtimeMins": 120,
      "releaseDate": "2020-07-07",
      "makers": ["S1 NO.1 STYLE"],
      "actresses": [
        { "name": "Example Actress", "image": "https://pics.dmm.co.jp/mono/actjpgs/example_actress.jpg" }
      ],
      "jacketFullUrl": "digital/video/ssis00001/ssis00001pl",
      "sampleUrl": "https://cc3001.dmm.co.jp/litevideo/freepv/s/ssi/ssis00001/ssis00001_dmb_w.mp4"
    }
  },
  "latencyMs": 142,
  "cached": false,
  "gated": true
}
```

### source `javdb` (base + `extra`)

`javdb` maps onto the base `video`. Fields that only exist on `r18`, such as `contentId`, `site`, `serviceCode`, and `titleJa`, come back `null`. Provider-only data lives under `extra`: `extra.downloadLinks` plus `extra.score` / `extra.voteCount`. The `magnet` and `url` link fields are paid-only. They are present on Pro and stripped on the free tier. `name`, `size`, and `hd` are always returned.

```json
{
  "result": {
    "q": "CAWD-001",
    "source": "javdb",
    "video": { "dvdId": "CAWD-001", "runtimeMins": 120, "series": "Series Name" },
    "extra": {
      "downloadLinks": [
        {
          "name": "CAWD-001 1080p",
          "hash": "0123456789abcdef0123456789abcdef01234567",
          "magnet": "magnet:?xt=urn:btih:0123456789abcdef...",
          "size": 5905580032,
          "hd": true,
          "url": "https://mypikpak.com/s/VOabc12"
        }
      ],
      "score": 4.3,
      "voteCount": 512
    }
  },
  "latencyMs": 980,
  "cached": false,
  "gated": false
}
```

### source `missav` (base + `extra`)

`missav` maps onto the base `video`. Fields that only exist on `r18` come back `null`, and `actresses` is a plain `string[]`. Provider-only data lives under `extra`: `extra.pageUrl` (the source page) and `extra.streams`, an HLS master playlist (`.m3u8`) plus per-resolution `variants`. Streams are paid-only (Pro); the free tier never reaches `missav`.

```json
{
  "result": {
    "q": "EBOD-391",
    "source": "missav",
    "video": { "dvdId": "EBOD-391", "runtimeMins": 119, "makers": ["E-BODY"] },
    "extra": {
      "pageUrl": "https://missav.ws/en/ebod-391",
      "streams": {
        "master": "https://surrit.com/<id>/playlist.m3u8",
        "variants": [
          "https://surrit.com/<id>/1280x720/video.m3u8",
          "https://surrit.com/<id>/842x480/video.m3u8"
        ]
      }
    }
  },
  "latencyMs": 369,
  "cached": false,
  "gated": false
}
```

## Plans

All plans use the same `/search` endpoint. They differ by quota, rate limit, and returned fields.

- Free: 100 req/day, 10/min, provider `r18`, no download/magnet/stream links (`gated: true`).
- Pro: 1000 req/day, 60/min, providers `r18` + `javdb` + `missav`, download / magnet links and HLS streams included.

## Errors

- `401`: missing or invalid RapidAPI credentials.
- `429`: rate limit or daily quota exceeded. Respect the `Retry-After` header.
- `504`: no provider returned a valid result. This can mean no match or that all upstreams timed out. Try a different code or provider.

## Tips

- The same `q` + `providers` combination is cached, so repeated lookups usually return quickly.
- Pin a provider with `providers` when you only want one source, for example `"providers": "javdb"` for magnet-first lookups on a paid plan.
- Code matching is fuzzy, so common formats such as `SSIS-001` and `ssis001` generally resolve to the same release.

## Roadmap

- More providers: `javlibrary`, `javdatabase`.
- New search modes: by image (reverse lookup from a cover/screenshot), by actress (releases for a performer), by video (match a release from a clip).

## Site

- [Home](https://javinfo.eu.org/): What javinfo is and how to get started.
- [Blog](https://javinfo.eu.org/blog): Notes on the API and how it is built.
- [Releases](https://javinfo.eu.org/releases): Version history and changelog.
- [Privacy](https://javinfo.eu.org/privacy): Privacy policy.

Blog and release pages also serve their raw Markdown source when requested with the `Accept: text/markdown` header.

## Blog

- [Introducing the javinfo API](https://javinfo.eu.org/blog/hello-javinfo): A small API for consistent JAV metadata across providers.
- [Built different](https://javinfo.eu.org/blog/built-different): No onboarding funnel. No metrics theater. No AI buzzword banners.
- [API-first, provider-agnostic](https://javinfo.eu.org/blog/api-first): One search endpoint. Consistent JAV metadata. No vendor lock-in.
- [Why javinfo exists](https://javinfo.eu.org/blog/why-javinfo): Adult content metadata should not require five brittle scrapers.
- [JAV Metadata API: One Endpoint Instead of Five Scrapers](https://javinfo.eu.org/blog/jav-metadata-api): There is no public, stable JAV metadata API; every source is a scraper that rots. javinfo is one hosted endpoint returning normalized metadata by code.
- [The JavDB API that doesn't exist](https://javinfo.eu.org/blog/javdb-api): JavDB never shipped a public API. Every "javdb api" on GitHub is a fragile scraper; javinfo has a real `javdb` provider with download/magnet links.
- [The DMM API problem](https://javinfo.eu.org/blog/dmm-api-problem): DMM/FANZA geo-blocks non-Japan IPs and has no usable public docs. javinfo covers ~99% of the dmm.co.jp library through one normalized endpoint.

## Releases

- [v0.1.0 — Initial beta](https://javinfo.eu.org/releases/v0-1-0): First public beta of the javinfo search API.