Skip to content
Guides
Using the dataset

Using the dataset

If you’d rather not call the API, the compiled dataset is committed as plain YAML you can read directly from the repository.

Where it lives 

data/
  series/        one file per Series or Franchise, keyed by id
    demon-slayer.yaml
    fate.yaml
  staff/         voice actors, grouped by language
    japanese-voice-actors.yaml

Every file under data/ is generated by builder build and carries a # Generated by builder build — do not edit header. Treat it as read-only output; the authored inputs live under config/overrides/ (see Building the dataset).

The data model

The catalog is a hierarchy:

  • Franchise — a brand grouping related Series (e.g. Fate). Carries series and optional curated watchOrders.
  • Series — one continuity / storyline, the base unit. Carries seasons, movies and specials.
  • Season — one numbered TV installment (one broadcast run, i.e. a cour), with number, release info, externalIds and episodes.
  • Movie / Special — films and side content (OVA / ONA / special).
  • Episode — one episode, with an airedNumber and, where the series is linearly numbered, an absoluteNumber spanning the whole series.

A file’s top-level key — series: or franchise: — determines its kind, not its directory. Standalone series and multi-storyline franchises both live under data/series/.

Example 

# data/series/demon-slayer.yaml
series:
  id: demon-slayer
  titles:
    original: 鬼滅の刃
    translations:
      en: Demon Slayer
  seasons:
    - id: demon-slayer-s1
      number: 1
      releaseYear: 2019
      releaseSeason: SPRING
      externalIds:
        anilistId: 101922
        anidbId: 14107
        tvdbId: 348545
      episodes:
        - absoluteNumber: 1
          airedNumber: 1
        # ...

Titles

Each node stores a titles block: the native-script original plus translations keyed by BCP-47 code (en, ja, …). Auto-filled titles default to Japanese (ja + romanized ja-Latn). The API resolves these to a single string per request; when reading the YAML directly you get every language.

External IDs

Every node cross-maps to external databases via externalIds: anilistId, anidbId, tmdbId, tvdbId and wikidataId (all optional). Use these to fetch expression — artwork, synopses, ratings — live from those services at runtime. The dataset itself stores only facts (ids, titles, structure), never licensed descriptive content.

Next: Building the dataset — compile the dataset yourself and author new entries with the builder CLI.

Using the APIBuilding the dataset