Palworld TCG Importer Technical Overview
The Palworld importer pulls the card catalogue from the official Bushiroad card-manager API on two hosts — the EN host is canonical, the JP host provides Japanese translations — and produces cards + printings with no marketplace external IDs. Card images come from the official CDN.
Data Sources
| Source | Role | Data Provided |
|---|---|---|
EN API (en.palworld-official-cardgame.com) | Primary | Cards, attributes, rules text, expansions, images |
JP API (palworld-official-cardgame.com) | Translations | Japanese card names + rules text, expansion names |
| Detail endpoint (per card) | Enrichment | Flavor text (list endpoint doesn’t carry it) |
Official CDN (/wordpress/wp-content/images/cardlist/) | Images | 400×559 card PNGs |
All requests send a browser User-Agent header (CloudFront blocks default HTTP-client UAs).
Product Model
| Level | Attributes |
|---|---|
| Card | cardKind (Pal / Event / Gear / Soul / Structure), cardKindSub (Normal Pal / Lucky Pal), color, types (element, pipe-multi), aptitudes (pipe-multi), cost, power, attack |
| Printing | rarity, finishes (single Standard), rulesText, flavorText; printNumber / sortNumber = full EN card number |
Base Card Grouping
Card numbers are {BASE} or {BASE}{SUFFIX} where BASE = XXXNN-NNN and SUFFIX ∈ TSP / TSR / OSR / SSP / SP / SR marks a parallel printing of the same base card. The grouping key is the card number with the suffix stripped (^([A-Z]+\d*-\d+)([A-Z/+]*)$) — e.g. EBP01-004 and EBP01-004SP merge into one card with two printings.
Every printing has a single CardFinish.STANDARD finish: parallels are separate card numbers, not finish variants.
EN ↔ JP Join
EN card numbers are the JP number with an E prefix (EBP01-001 ↔ BP01-001, verified 241/241 at launch). JP ids do not align with EN ids — the join is by card number only. Japanese card_name and normalized text land in card-level translations.ja; expansion names join by the same rule on codes (EN EBP01 ↔ JP BP01, PR2026 unchanged).
(expansion, card_number) is unique, but ESOUL-001 exists in both ETD01 and ETD02 (same Soul card shipped in two trial decks). Printing slugs are the lowercased card number, prefixed with the expansion code whenever the number does not already start with it (etd01-esoul-001 vs etd02-esoul-001) — see the ADR.
Slug Uniqueness
Like Pokémon, identically named cards are expected (the same Pal reappears with different epithets, and plain name collisions like the three Soul base cards already exist). Uniqueness never depends on the name:
- Product slug = expansion-scoped card number (
ebp01-004sp) — the same guarantee class as Pokémon’s{finish}-{setId}-{number}product slugs. - Card slug =
{baseNumber}-{name}(etd01-023-lamball-my-first-pal) — the base number alone is globally unique, so two Pals sharing an exact name can never collide (stronger than Pokémon’s{name}-{expansion}card slugs). nameSluguses the default generator; the threeSoulbase cards (ESOUL-000/001/003) intentionally sharesoulso “See all printings” groups them — they are the same functional card.
Expansions
Expansions come from the /products endpoint (pack | deck | pr types). Slug = slugified clean name (dawn-of-palpagos, trial-deck-dawn-of-palpagos-red-blue), matching the name-based convention every other game uses; release dates normalized from 2026.07.30 to 2026-07-30; languages ["en", "ja"]; no expansion groups. The code (EBP01, PR2026) stays the stable join key against the API.
The endpoint names each product by its sealed-product format (Booster Pack "…", Trial Deck "…", PR Cards (2026)), and “Booster Pack …” reads like a sealed product in the catalogue. cleanExpansionName() normalises names per type, matching how the rest of the catalogue is named (MTG “Aetherdrift”, FAB “Blitz Deck”, DBS “Starter Deck 1: Son Goku”):
- pack — the booster is the flagship set, so we drop the format prefix and keep the quoted set name:
Booster Pack "Dawn of Palpagos"→ Dawn of Palpagos. - deck — starter/trial decks keep their format name (as every other game does); we only tidy the quotes into a separator:
Trial Deck "Dawn of Palpagos Green・Purple"→ Trial Deck: Dawn of Palpagos Green・Purple. - pr —
PR Cards (2026)→ Promotional Cards 2026 (JP: プロモカード（2026年）), matching thePromotional {year}convention. - fallback — any product whose name matches no known pattern keeps its raw name and logs a warning, so a genuinely new product format is noticed rather than shipped ugly.
The rule is driven entirely by the product type + the quote pattern Bushiroad uses consistently, so future releases (BP02, TD03, next year’s promos) are named automatically with no code change.
The expansion slug is derived from the clean name (dawn-of-palpagos), so a change to cleanExpansionName’s output for an already-imported set re-slugs the expansion, which cascade-deletes and recreates it (and orphans any inventory). The set names themselves are stable, so this is a non-issue in normal operation — but treat any change to the naming rule for a live set as a breaking migration. The names were finalised before launch specifically so the slugs are locked in from the first production import.
| Code | Format | Expansion name (EN) | Cards |
|---|---|---|---|
EBP01 | Booster pack | Dawn of Palpagos | 161 |
ETD01 | Trial deck | Trial Deck: Dawn of Palpagos Red・Blue | 39 |
ETD02 | Trial deck | Trial Deck: Dawn of Palpagos Green・Purple | 39 |
PR2026 | Promo | Promotional Cards 2026 | 2 |
Rarity Mapping
| API code | Rarity |
|---|---|
C | Common |
U | Uncommon |
R | Rare |
RR | Double Rare |
SR | Super Rare |
SP | Special |
SSP | Super Special |
OSR | Over Super Rare |
TD | Trial Deck |
TSP | Trial Deck Special |
TSR | Trial Deck Super Rare |
PR | Promo |
RR/SSP | Double Rare |
EBP01-049 carries the composite rare value RR/SSP while a separate EBP01-049SSP row exists for the actual Super Special parallel — so RR/SSP maps to Double Rare.
Text Normalization
The text field embeds icon tokens suffixed with @ (AUTO@, ACT@, OnDeploy@, …), 【Element】 brackets and circled digits. The importer rewrites ability/timing markers to bracketed labels (AUTO@ → [AUTO], OnDeploy@ → [On Deploy], 1Turn@ → [1/Turn], …) and strips the @ from inline stat/resource icons (Ingredient@, Power@+500 → Power +500), keeping everything else (including newlines) verbatim. JP text carries no @ tokens and is stored as-is. Flavor text is fetched per card from the detail endpoint with a request delay.
Import Flow
Pricing
There is no price importer for Palworld TCG. The game is absent from TCGplayer and Cardmarket; all price-source maps resolve to undefined/[].