Anime ID Mapping
Match anime across services with different IDs and episode numbering.
Anime ID Mapping helps CrossWatch match anime across services with different IDs and episode numbering.
Anime ID Mapping
Anime providers do not always describe the same show in the same way.
A normal TV provider might store an anime as one show with several seasons. An anime tracker may store each season as a separate title. It may use continuous episode numbers across the series.
CW Anime ID Mapping translates between those structures.
It can improve matching between providers such as:
TMDB
TVDB
IMDb
AniDB
MyAnimeList
AniList
SIMKL
Kitsu
It can also translate episode numbering when providers disagree about seasons and absolute episode numbers.
What Anime ID Mapping does
CW uses Anime ID Mapping to:
Add missing anime IDs to items
Match the same anime across different provider ID systems
Translate season and episode numbers into anime absolute episode numbers
Translate anime absolute episode numbers back into normal season and episode numbers
Handle anime where one provider uses a single show while another splits seasons into separate entries
Apply custom mappings when the downloaded mapping does not match your setup
Custom rules always take priority over the downloaded dataset.
Enable Anime ID Mapping
Open Settings → Connections → Metadata → Anime ID Mapping.
Enable Anime ID Mapping and save the settings.
When Anime ID Mapping is enabled for the first time, CW can download the mapping data and build its local index automatically.
Automatic updates can keep the local mapping data current.
Using Anime Mapping in a sync pair
Anime ID Mapping is applied per sync feature.
Open your synchronization pair and look for Use Anime ID Mapping in the feature settings.
Watchlist and Ratings normally use Anime ID Mapping automatically when the pair supports it.
History mapping is opt in.
For supported AniList setups, Anime only sync can restrict that feature to anime items.
Episode mapping
Episode mapping is useful when providers use different numbering models.
One provider may expose:
The anime tracker may expect:
More complicated shows may have several normal seasons. The anime tracker may use one continuous episode sequence.
CW can translate those coordinates before writing the item.
It can also reverse that mapping when reading anime data back.
This is especially important with SIMKL. Some anime seasons use separate SIMKL entries and different TMDB IDs.
CW can map the SIMKL episode back to the original source show, season, and episode. The same item is then recognised on the next sync.
Custom anime mappings
If the downloaded mapping does not match a title correctly, open Custom anime mappings.
A custom rule tells CW:
For shows, you can optionally include:
Source season
First episode
Last episode
The episode number where the range starts on the anime tracker
Leave the episode fields empty when you only need to correct an ID.
Movies only use ID mapping. They do not have season or episode ranges.
Custom mappings can be enabled, disabled, edited, or deleted.
Your rules are evaluated before the downloaded Anime ID Mapping data.
Find anime on SIMKL
When the target of a custom rule is SIMKL, CW can search SIMKL directly from the mapping editor.
A connected SIMKL account is required.
Select SIMKL as the target and use the search button.
Search by title. CW shows matching SIMKL anime entries.
For each result, you can choose Use ID or Build seasons.
Use ID fills the selected SIMKL ID. You can then finish the rule manually.
Build seasons helps when your source has one continuous season. SIMKL may split the anime into several entries.
CW follows related SIMKL season entries and prepares the episode ranges automatically.
CW shows the generated rules and asks for confirmation before saving.
Entries that have not aired, or lack a usable episode count, are skipped.
Import custom mappings
Custom mappings can be imported from a CW JSON export.
Choose one of two modes:
Merge into my rules
Keeps your current rules and adds or updates rules from the imported file.
Replace all rules
Replaces your current custom rule set with the imported file.
CW validates imported rules before saving them.
Invalid rules are skipped. The import result shows added, updated, and skipped rules.
Export custom mappings
Select Export to save all custom anime mapping rules as a JSON file.
The export contains your custom rules only.
It does not contain the downloaded Anime ID Mapping dataset.
Exports are useful for:
Backing up custom mappings
Moving mappings to another CW installation
Sharing a known working mapping set
Editing or reviewing a larger rule set outside CW
When should I create a custom rule?
Create a custom rule when:
The same anime keeps appearing as unresolved
The wrong season or episode is written
A SIMKL item is added again on every sync
The provider uses a different ID than the downloaded mapping expects
One provider splits a show differently from another provider
You know the correct mapping and want CW to use it instead of the downloaded dataset
For normal titles, no custom rule is required.
Let the downloaded Anime ID Mapping handle them automatically.
Troubleshooting
If mapping does not appear to work:
Confirm Anime ID Mapping is enabled
Confirm Use Anime ID Mapping is enabled for the feature in your sync pair
Confirm the mapping index is installed and ready
Update or rebuild the mapping index if required
Check that the item has at least one usable provider ID
Use a custom mapping when the automatic result is wrong
If SIMKL search is not available, connect SIMKL under tracker connections.
Power users
Anime ID Mapping is an ID enrichment and episode coordinate translation layer. It runs before provider-specific matching and writes.
It combines downloaded mapping data with local custom overrides.
Custom overrides have priority over the downloaded mapping.
Data sources
CW builds the local anime index from two data sources.
The main relationship graph comes from AniBridge.
CW downloads:
CW also downloads the anime identity dataset from animeApi v3.
The identity data provides an additional bridge. It helps when an item starts with an anime-specific ID, such as SIMKL or Kitsu. Those items may not have a normal mapping seed ID.
The downloaded data is converted into a local SQLite index for runtime lookups.
Mapping model
The service supports two related operations:
Identity enrichment
Episode coordinate translation
Identity enrichment adds compatible IDs to an item.
Episode translation handles differences between normal season numbering and anime absolute numbering.
These operations are related but separate.
Identity enrichment
Normal mapping seed namespaces include:
SIMKL and Kitsu can also act as identity seeds. This applies when an item lacks a normal seed ID.
CW then uses the identity index to recover native mapping IDs. It continues through the normal mapping graph.
The mapping service follows edges to a limited depth. It only accepts an automatically selected ID when the result is unambiguous.
Existing IDs are not replaced merely because another mapping candidate exists.
Custom override namespaces
A custom rule can match these providers:
A custom rule can target:
Supported media types are:
Movie rules are identity only.
Show rules can additionally describe an episode range.
Override precedence
For episode mapping, CW uses this order:
User override
AniBridge mapping
Native passthrough, when applicable
For reverse episode mapping, CW uses this order:
User override
AniBridge reverse mapping
A custom rule can correct both the write path and the readback path.
Episode rule format
A show rule can contain:
Example concept:
The equivalent mapping values are:
The forward resolver translates:
The reverse resolver translates the target coordinates back:
Forward episode resolution
The episode resolver starts with source show IDs and season and episode coordinates.
TVDB and TMDB are preferred aired-numbering entry points.
When only TMDB is available, CW can use the local show-pair mapping. This reaches the related TVDB show.
The resolver checks the AniBridge season scope. It translates the source episode through stored source and target ranges.
Anime native targets currently prefer:
Season zero is not automatically translated. The caller must explicitly allow specials.
Reverse episode resolution
Reverse mapping lets anime tracker data be recognised when it is read back later.
The resolver accepts an anime target ID and an absolute episode number.
It first checks local user overrides.
If no override matches, it queries AniBridge reverse edges.
Reverse mapping can resolve back to:
A reverse result is only accepted when it produces one unambiguous season and episode coordinate.
This prevents ambiguous mappings from silently rewriting an item to the wrong episode.
SIMKL readback
SIMKL is a main consumer of reverse episode mapping.
SIMKL may represent anime using:
One flat absolute episode sequence
Separate SIMKL entries for individual seasons
Different TMDB IDs for those separate entries
When reading SIMKL anime history, CW can reverse the absolute episode number into the original aired coordinate.
Where required, source show IDs are also restored. The canonical item then matches the source provider again.
This fixes cases where a write succeeded on SIMKL. A later read could not recognise the item and attempted to add it again.
SIMKL catalog lookup
The custom mapping editor exposes SIMKL catalog lookup through:
A configured SIMKL profile is required.
If the requested profile is not configured, CW can resolve another configured SIMKL profile for the catalog client.
Search uses the SIMKL anime search API.
The current search result limit is capped at:
Only SIMKL anime entries with the TV anime type are returned.
Results can include:
Build seasons
Build seasons supports source seasons that represent several separate SIMKL anime entries.
CW starts from the selected SIMKL entry and inspects its sequel relationships.
Only aired entries with a usable year and positive episode count are included.
The entries are ordered and converted into contiguous source ranges.
For example, if the SIMKL chain contains:
CW can generate:
The generated plan is shown before the rules are created.
Unaired entries and entries without a usable episode count are reported as skipped.
Import and export
Custom rules are stored independently from downloaded AniBridge data.
Export returns:
The generated filename uses:
Import accepts either a JSON list of rules or an object containing an overrides list.
Supported modes are:
Merge
Merge starts with the current rule set.
Rules with an existing rule ID are updated.
New rule IDs are added.
Existing rules absent from the import remain untouched.
Replace
Replace starts with an empty rule set. It imports valid rules from the supplied file.
The UI asks for confirmation before replacing an existing rule set.
Validation
Every imported rule passes through the normal override validator.
Invalid entries are skipped.
The result reports:
Details for skipped rules are also returned. The response limits these to 50 skipped entries.
The current maximum is:
Custom override storage
Custom mappings are stored at:
The file is separate from:
Downloaded AniBridge mappings
animeApi identity data
The generated SQLite mapping index
Writes use atomic temporary-file replacement.
The runtime caches parsed overrides. It invalidates the cache after changes.
Rule evaluation
Enabled rules are evaluated in stored order.
Disabled rules are ignored.
For episode rules, the first matching enabled range is used.
A show episode rule requires:
episode_to may be omitted for an open-ended range.
Episode numbers must be 1 or higher.
The ending episode cannot be below the starting episode.
Movie mappings cannot define season or episode coordinates.
Pair behavior
Anime Mapping is globally enabled through the anime_mapping configuration block. Pair feature settings also control its use.
The normal default features are:
History is an opt-in Anime Mapping feature.
Pair feature options include:
anime_only_sync is disabled when use_anime_mapping is disabled.
By default, the global mapping scope is intended for pairs involving anime-native providers:
The configured provider list can also contain:
This allows Anime Mapping for any pair.
Dataset updates
The default release tag is:
When Anime ID Mapping is enabled and the local index is missing, saving the settings can bootstrap the dataset immediately.
Automatic updating is enabled by default when the feature is enabled.
The normal refresh interval is:
The minimum interval is one hour.
CW first checks the AniBridge statistics metadata.
The full mapping file is downloaded and rebuilt only when required. A forced update bypasses this check.
The local index can also be rebuilt from downloaded mapping files. This does not download the dataset again.
Local index
The runtime uses a generated SQLite index. It does not repeatedly parse downloaded mapping files.
Status information includes:
The index can automatically rebuild when its schema is outdated.
API
The main Anime Mapping API is:
Important endpoints include:
Code map
Main mapping service:
Episode translation and reverse translation:
Custom mappings:
SIMKL catalog lookup and season planning:
Dataset updater:
API:
UI:
Last updated
Was this helpful?