Mapping Standard

The mapping standard describes how an anime or manga site tells Aniworks which series it carries and what its URLs look like. A site that follows it gets two things:

• The Aniworks extension on its pages. The Aniworks browser extension recognises the site's episode and chapter pages, then:
  • opens that episode's or chapter's discussion beside the player or reader;
  • tracks the visitor's progress: when they finish an episode, it's marked watched on their Aniworks list (and on AniList, if they've connected it), with no manual updating.
• Links from Aniworks. Series pages on aniworks.net link to the site under Watch or Read, but only for series the site actually has.

Any site can follow the standard. You don't need an agreement with Aniworks or an API key.

How Mapping Works

Your site and Aniworks identify series differently. Your site has its own id for each series, which appears in its URLs: a slug like violet-evergarden in /watch/violet-evergarden/episode-3, or a number like 4821 in /watch/4821/episode-3. Aniworks has its own id for the same series, a number like 9269, which won't match yours. Mapping connects the two, in two parts:

1. A URL template and patterns tell Aniworks where your id and the episode or chapter number sit in your URLs. They're listed in your manifest, a file at a fixed address on your site.
2. A catalog lists every series you carry, pairing your id with the series' Aniworks id.

Together they work in both directions.

From your page to an Aniworks discussion

Say a visitor with the extension opens https://example.com/watch/violet-evergarden/episode-3, and your manifest has this pattern:

/watch/{id}/episode-{ep}

1. The extension matches the URL against the pattern and reads {id} = violet-evergarden and {ep} = 3.
2. Aniworks looks up violet-evergarden in your anime catalog and finds { "id": "violet-evergarden", "aniworks": 9269 }.
3. Aniworks series 9269 is Violet Evergarden, so the extension opens the discussion for its episode 3, and marks episode 3 watched on the visitor's list once they finish it.

From an Aniworks series page to your site

When someone opens Violet Evergarden on aniworks.net:

1. Aniworks sees that your catalog has series 9269, under your id violet-evergarden.
2. It fills that id into your URL template, /watch/{id}/episode-{ep}, and links to the episode the visitor is up to (or episode 1), such as /watch/violet-evergarden/episode-4.

A series that isn't in your catalog gets no link, so visitors are never sent to a page that doesn't exist.

Quick Start

1. Write your URL template. Take one of your episode or chapter URLs and replace your series id with {id} and the number with {ep} (anime) or {ch} (manga). Usually it's also your only pattern. See URL Templates and Patterns.
2. Find the Aniworks id of each series you carry. If you store MyAnimeList or AniList ids, translate them with the Id Mappings. See Finding Aniworks ids for other cases.
3. Generate a catalog for each media you carry: a JSON list of your ids, each with its Aniworks id. See The Catalog.
4. Publish the manifest at https://<your-domain>/.well-known/aniworks.json, naming your site, your template and patterns, and where the catalogs are. See The Manifest.
5. Check both files against the JSON Schemas, then get listed.

A complete minimal setup for an anime site is two files:

// https://example.com/.well-known/aniworks.json
{
  "version": 1,
  "name": "Example Site",
  "anime": {
    "url": "/watch/{id}/episode-{ep}",
    "patterns": ["/watch/{id}/episode-{ep}"],
    "catalog": "/.well-known/aniworks-anime.json"
  }
}

// https://example.com/.well-known/aniworks-anime.json
{
  "version": 1,
  "series": [
    { "id": "violet-evergarden", "aniworks": 9269 },
    { "id": "violet-evergarden-the-movie", "aniworks": 10806 }
  ]
}

(The // lines name each file's address. Leave them out of the real files: JSON doesn't allow comments.)

The Manifest

The manifest is the entry point: the one file Aniworks looks for on your site. It always lives at the same address, /.well-known/aniworks.json on your domain (.well-known is the standard folder for files like this). It says what your site is called, and for each media you carry, what your URLs look like and where that media's catalog is.

Every address in the manifest (icon, url, patterns and catalog) is a path starting with /, such as /watch/{id}, meaning that path on the domain serving the manifest. Your pages, icon and catalogs must therefore all be on that domain. Since the file names no domain, it stays correct if your site moves to another one.

{
  "version": 1,
  "name": "Example Site",
  "icon": "/favicon-192.png",
  "anime": {
    "url": "/watch/{id}/episode-{ep}",
    "patterns": ["/watch/{id}/episode-{ep}", "/watch/{id}?ep={ep}"],
    "catalog": "/.well-known/aniworks-anime.json"
  },
  "manga": {
    "url": "/read/{id}/chapter-{ch}",
    "patterns": ["/read/{id}/chapter-{ch}"],
    "catalog": "/.well-known/aniworks-manga.json"
  }
}

Top-level fields

The anime and manga sections

URL Templates and Patterns

Each media section describes your URLs twice, for two different jobs:

• url, the template, is how Aniworks builds links to your site. There's exactly one.
• patterns are how the extension recognises your pages. There can be several, because visitors may reach the same page through URLs of different shapes.

Usually the template and your only pattern are the same line. They differ when your pages have more than one URL. For example, on some sites /watch/x7k2p?ep=4 and /watch/violet-evergarden-x7k2p?ep=4 are the same page, with an optional title in front of the id. Aniworks can only build the short form, but visitors arrive on both:

"url": "/watch/{id}?ep={ep}",
"patterns": ["/watch/{*}-{id}?ep={ep}", "/watch/{id}?ep={ep}"]

Placeholders

Both the template and patterns are paths starting with /, and both must contain {id}.

The template

• With {ep} (or {ch}), Aniworks links straight to the episode the visitor is up to, or episode 1. Without it, Aniworks links to your series page.
• It can't contain {*}, since Aniworks wouldn't know what text to put there.
• It's only used to build links. If visitors watch on pages of this shape, which they usually do, list it under patterns too.

Patterns

• Each pattern needs {ep} (or {ch} for manga). The extension only acts on episode and chapter pages.
• They're tried in order, and the first match wins. Put specific patterns before general ones. In the example above, /watch/{id}?ep={ep} would also match the long URL and read the whole of violet-evergarden-x7k2p as the id, so it comes last.
• Up to 10 per media.

Matching rules

When the extension compares a page's URL with a pattern:

• Only the path and query are compared. The page must be on your manifest's domain, with or without www..
• Path segments match one for one. Each segment (the parts between /) must match the pattern's segment in the same position. The URL may have extra segments after the pattern's last one, so /watch/{id}/{ep} also matches /watch/123/4/some-title.
• Query parameters match by name. Each parameter in the pattern must be in the URL. The URL's other parameters, and their order, don't matter.
• {*} takes as much as it can. In /watch/{*}-{id}, the id is everything after the last -, so this only works if your ids contain no -.
• Letters are compared without regard to case. {id} is URL-decoded before it's looked up in your catalog, so %20 is a space.

Examples

The Catalog

A catalog lists the series you carry, one file per media, at the URL your manifest's catalog gives. Each entry pairs your id for a series with that series' Aniworks id. Anime and manga need separate catalogs because Aniworks numbers them separately: anime 1 and manga 1 are different series.

{
  "version": 1,
  "series": [
    { "id": "violet-evergarden", "aniworks": 9269, "title": "Violet Evergarden", "available": 13 },
    { "id": "violet-evergarden-dub", "aniworks": 9269 },
    { "id": "violet-evergarden-the-movie", "aniworks": 10806 }
  ]
}

Several of your ids can point at the same series. In the example above, the subbed page violet-evergarden and the dubbed page violet-evergarden-dub are both series 9269. The extension recognises all of them, but Aniworks links to your site only once per series, using the first entry for that series in your catalog. List the page you'd like visitors sent to first.

An entry whose Aniworks id doesn't exist is skipped, and the rest of your catalog is still used.

Finding Aniworks ids

• If you store MyAnimeList or AniList ids, translate them with the Id Mappings when you generate your catalog.
• If you don't, match your series to Aniworks once, by title, and store the Aniworks ids alongside your own. A series' id is the number in its aniworks.net URL.

Aniworks adds series from time to time. Regenerate your catalog now and then with fresh mappings, so newly added series get matched.

Seasons and episode numbers

Each Aniworks series is one season, and {ep} counts from 1 within it, so map each id to its season. If one id covers several seasons and its episodes are numbered straight through, map it to the first season: Aniworks follows its season order, so if season 1 has 12 episodes, episode 15 opens season 2's episode 3.

Id Mappings

Aniworks publishes every series' MyAnimeList and AniList ids, for translating them to Aniworks ids:

• https://api.aniworks.net/records/api/mapping/anime.json
• https://api.aniworks.net/records/api/mapping/manga.json

Each file is a JSON list with one entry per series. Ids a series doesn't have are left out:

[
  { "aniworks": 9269, "mal": 33352, "anilist": 21827 },
  { "aniworks": 10806, "mal": 37987, "anilist": 103047 }
]

MyAnimeList and AniList number anime and manga separately (MyAnimeList anime 1 and manga 1 are different series), so translate anime ids with the anime file and manga ids with the manga file.

Hosting the Files

• HTTPS only. Aniworks expects a 200 response with JSON content (application/json). Redirects are followed if they stay on your domain.
• Size limits: 64 KB for the manifest, 20 MB for each catalog, measured uncompressed. Aniworks accepts gzip compression.
• Updates: Aniworks fetches your files about once a day, so changes take up to a day to show. If you send an ETag or Last-Modified header, unchanged files aren't downloaded again.
• Bot protection: Aniworks' requests use the user agent Aniworks/1.0 (+https://aniworks.net/docs/mapping). If a firewall or bot check sits in front of your site, allow it for these files. Aniworks only fetches these files and never sends cookies.

Validating

JSON Schemas for both files are published for checking them with any JSON Schema validator (draft 2020-12):

• Manifest: https://aniworks.net/schemas/mapping-manifest-v1.json
• Catalog: https://aniworks.net/schemas/mapping-catalog-v1.json

The schemas check each file's structure. Aniworks also checks things a schema can't, such as whether your catalog's Aniworks ids exist.

Getting Listed

Aniworks learns about your site in one of two ways:

• A visitor turns on the extension on your site. The extension checks whether your site has a manifest and, if it does, sends Aniworks your domain. Nothing else about the visit is sent.
• You submit your domain. A submission form is coming soon.

Aniworks then fetches and checks your files straight away. Until an Aniworks moderator reviews your site:

• the extension already works on it, with a note asking visitors to check that the series shown matches the one on your page;
• aniworks.net doesn't link to it.

The review checks that your ids point at the right series. Once approved, your links appear on the pages of the series in your catalog, under the free sites unless you're a licensed service. Moderators can turn a site off again if its mappings turn out to be wrong or the discussions coming from it become a problem.

Versioning

This document describes version 1. New optional fields may be added to version 1, and files without them stay valid. A change that breaks existing files would come as version 2, and Aniworks will keep reading version 1 files.