TCGplayer prices

This document provides information for the TCGplayer crawler of the crawl tcg-prices command.

TCGplayer has somewhat limited support for card variants. They have a fixed set of card variant types, which they call printings. These printings were designed to describe standard and parallel set card variant types in general. Each product (card) on TCGplayer is assigned one or more of these printings, from which sellers can choose. The available printings are:

Normal
Holofoil
Reverse Holofoil
Unlimited
Unlimited Holofoil
1st Edition
1st Edition Holofoil

The Unlimited and Unlimited Holofoil printings are identical to the Normal and Holofoil printings. They're used exclusively for products that also have 1st Edition or 1st Edition Holofoil printings. This is to avoid confusion for buyers who might incorrectly assume Normal or Holofoil printings to be 1st Edition or 1st Edition Holofoil printings.

In the context of crawling TCG prices, this distinction for the Unlimited and Unlimited Holofoil printings has no real use. Therefore, we don't use them and automatically translate them to Normal and Holofoil internally.

TCGplayer has no option for card variants like Cracked Ice Holo or Cosmos Holo. This means that they're forced to list these card variants as separate products. This makes it difficult to automatically figure out which card variant they're referring to. Our solution is to use an external database that contains this mapping information.

A lot of card names, expansion names and card numbers are labeled in an inconsistent manner. For that reason, mapping information for these values is included in the external database as well.

Command usage (options)

`--tcgplayer-api-config-file-path` (required)

This JSON file contains the configuration for the TCGplayer API.

Property	Type	Is required	Description
publicKey	string	Yes
privateKey	string	Yes

JSON file example

{
  "publicKey": "public-key",
  "privateKey": "private-key"
}

`--tcgplayer-product-mappings-dir-path`

Because TCGplayer can be inconsistent when it comes to card names, expansion names, and card variants (as explained previously), an external database is needed that maps the values as they appear on TCGplayer to their corrected/sanitized values. This database consists out of a JSON file per product with the following properties:

Property	Type	Is required	Description
productId	int32	Yes	The TCGplayer product ID.
productName	string	Yes	The TCGplayer product name. It usually refers to the card name.
productGroupName	string	Yes	The TCGplayer group name. It usually refers to the expansion name.
productNumber	string\|null	Yes	The TCGplayer product number. It usually refers to the card number.
productUrl	string	Yes	The TCGplayer product URL.
cardId	string\|null	No	If this value is set, all card-related properties will be ignored when identifying the card. This can be useful when mapping TCG prices to an external database such as TCG Collector.
cardName	string\|null	No	Optionally can be used to help identify the card.
expansionId	string\|null	No	If this value is set, all expansion-related properties will be ignored when identifying the expansion. This can be useful when mapping TCG prices to an external database such as TCG Collector.
expansionName	string	Yes
tcgRegionName	string	Yes
cardNumber	string\|null	Yes
cardNumberSortingOrder	int32\|null	Yes
normalCardVariantId	string\|null	No	See 1*.
normalCardVariantType	string	Yes	See 2*.
normalWeight	int32\|null	No	See 3*.
holofoilCardVariantId	string\|null	No	See 1*.
holofoilCardVariantType	string	Yes	See 2*.
holofoilWeight	int32\|null	No	See 3*.
reverseHolofoilCardVariantId	string\|null	No	See 1*.
reverseHolofoilCardVariantType	string	Yes	See 2*.
reverseHolofoilWeight	int32\|null	No	See 3*.
firstEditionCardVariantId	string\|null	No	See 1*.
firstEditionCardVariantType	string	Yes	See 2*.
firstEditionWeight	int32\|null	No	See 3*.
firstEditionHolofoilCardVariantId	string\|null	No	See 1*.
firstEditionHolofoilCardVariantType	string	Yes	See 2*.
firstEditionHolofoilWeight	int32\|null	No	See 3*.

This option isn't required because no product mappings will exist yet on the first run. After the first run, the product mappings can be created by mapping the unhandled products output (see the --tcgplayer-unhandled-products-output-dir-path option).

Each JSON file is required to have a tcgplayer-product-mapping suffix, e.g., 158963.tcgplayer-product-mapping.json.

1*: If this value is set, all other properties will be ignored when identifying the card variant. This can be useful when mapping TCG prices to an external database such as TCG Collector.

2*: These properties map the TCGplayer printings to card variant types. All properties are required to have a value because TCGplayer sellers might list incorrect printings for a product. However, this might cause different TCGplayer printings to map to the same card variant type. For such cases, see 3*.

3*: If different printings from the same TCGplayer product map to the same card variant type, a weight can be assigned to determine which printing should be used. The TCGplayer printing with the highest weight always takes precedence. If no weight is set, the lowest possible integer value is used as the default weight. If the weight of the TCGplayer printings is identical, the crawler will log a duplicate TCG price warning, and the TCGplayer printing that was crawled first will take precedence.

`--tcgplayer-skipped-products-dir-path`

Sometimes, TCGplayer will list products that you don't want to track. In order to prevent these products from showing up in the unhandled products output (see the --tcgplayer-unhandled-products-output-dir-path option), a JSON file per product with the following properties can be used:

Property	Type	Is required	Description
id	int32	Yes	The TCGplayer product ID.
name	string	Yes	The TCGplayer product name. It usually refers to the card name.
groupName	string	Yes	The TCGplayer group name. It usually refers to the expansion name.
number	string\|null	Yes	The TCGplayer product number. It usually refers to the card number.
url	string	Yes	The TCGplayer product URL.
reasonForSkipping	string\|null	No	The reason for skipping the TCGplayer product.

Each JSON file is required to have a skipped-tcgplayer-product suffix, e.g., 158963.skipped-tcgplayer-product.json.

`--tcgplayer-unhandled-products-output-dir-path` (required)

Unhandled products are TCGplayer products for which no product mapping could be found during the crawling process. Each unhandled product is exported as a JSON file with the following properties:

Property	Type	Is required	Description
id	int32	Yes	The TCGplayer product ID.
name	string	Yes	The TCGplayer product name. It usually refers to the card name.
groupName	string	Yes	The TCGplayer group name. It usually refers to the expansion name.
number	string\|null	Yes	The TCGplayer product number. It usually refers to the card number.
url	string	Yes	The TCGplayer product URL.

This output should be mapped manually into product mappings or skipped products. If the TCG Collector database is used, the unhandled products can be semi-automatically mapped using the cms tcgplayer map-unhandled-products command.

To get an overview of all unhandled TCGplayer groups, the cms tcgplayer show-unhandled-groups command can be used.

Each JSON file is required to have a unhandled-tcgplayer-product suffix, e.g., 158963.unhandled-tcgplayer-product.json.

How to map TCGplayer printings to card variants

There are two kinds of TCGplayer products:

"Main" products: These products map to card variants from the standard and parallel set (or to card variants from promotional/other expansions). The TCGplayer printings map to one or more card variants.
"Separate" products: These products map to card variants that can't be described by any of the TCGplayer printings. The TCGplayer printings map to only one card variant.

Mapping non-holographic "main" products without parallel set

Property	TCGplayer printing	Card variant type
normalCardVariantType	Normal	Standard Set
holofoilCardVariantType	Holofoil	Standard Set
reverseHolofoilCardVariantType	Reverse Holofoil	Standard Set
firstEditionCardVariantType	1st Edition	Standard Set
firstEditionHolofoilCardVariantType	1st Edition Holofoil	Standard Set

Mapping non-holographic "main" products with parallel set

Property	TCGplayer printing	Card variant type
normalCardVariantType	Normal	Standard Set
holofoilCardVariantType	Holofoil	Parallel Set Foil
reverseHolofoilCardVariantType	Reverse Holofoil	Parallel Set Foil
firstEditionCardVariantType	1st Edition	Standard Set
firstEditionHolofoilCardVariantType	1st Edition Holofoil	Parallel Set Foil

Mapping holographic "main" products without parallel set

Property	TCGplayer printing	Card variant type
normalCardVariantType	Normal	Standard Set Foil
holofoilCardVariantType	Holofoil	Standard Set Foil
reverseHolofoilCardVariantType	Reverse Holofoil	Standard Set Foil
firstEditionCardVariantType	1st Edition	Standard Set Foil
firstEditionHolofoilCardVariantType	1st Edition Holofoil	Standard Set Foil

Mapping holographic "main" products with parallel set

Property	TCGplayer printing	Card variant type
normalCardVariantType	Normal	Standard Set Foil
holofoilCardVariantType	Holofoil	Standard Set Foil
reverseHolofoilCardVariantType	Reverse Holofoil	Parallel Set Foil
firstEditionCardVariantType	1st Edition	Standard Set Foil
firstEditionHolofoilCardVariantType	1st Edition Holofoil	Standard Set Foil

Mapping "separate" products

Using a Cosmos Holo card variant as an example:

Property	TCGplayer printing	Card variant type
normalCardVariantType	Normal	Cosmos Holo
holofoilCardVariantType	Holofoil	Cosmos Holo
reverseHolofoilCardVariantType	Reverse Holofoil	Cosmos Holo
firstEditionCardVariantType	1st Edition	Cosmos Holo
firstEditionHolofoilCardVariantType	1st Edition Holofoil	Cosmos Holo

Automatic mapping

When using the cms tcgplayer map-unhandled-products or cms tcgplayer remap-products command, there's an --auto-map-printings option and an auto input value option to attempt to automatically map the TCGplayer printings. However, this isn't completely foolproof and should not be used in the following cases:

One or more of the TCGplayer products being mapped are "separate" products.

Automatic mapping only works for "main" TCGplayer products. "Main" products can't be automatically distinguished from "separate" products. "Main" products are usually listed in specific TCGplayer groups, which usually correspond to expansions.
The TCG Collector card variants are incomplete or incorrect.

The mapping of the TCGplayer printings differs based on which TCG Collector card variants are available and whether they're holographic. If automatic mapping proceeds with an incomplete or incorrect list of card variants, duplicate TCG price warnings are likely to occur during the crawling process (also see the Changes to product mappings over time section regarding new TCGplayer printings).

Changes to product mappings over time

Over time, manual maintenance to the product mappings might be required because of the following reasons:

A new product has been added on TCGplayer.

See the --tcgplayer-unhandled-products-output-dir-path option.
A new printing has been added to an existing TCGplayer product.

A new printing will cause the existing product mapping to incorrectly map to the same card variant. The crawler will log a duplicate TCG price warning that will need to be corrected manually. It's also possible a seller on TCGplayer specified an incorrect printing. In that case, the warning can be ignored. It can also be suppressed by assigning a weight to the printing in the TCGplayer product mapping.

If the TCG Collector database is used, existing product mappings and/or skipped products can be semi-automatically remapped using the cms tcgplayer remap-products command.
A product has been deleted on TCGplayer.

This deleted product should remain in the product mappings, because there's a chance of the product becoming available again. The crawler doesn't log any warnings or errors for deleted products.
A new card (variant) has been added to an externally mapped database.

If the card (variant) doesn't exist on TCGplayer, no action is required. If TCGplayer adds this card (variant) at some point, see item 1 and 2.
One or more of the values of the mappings have gone out of sync with an externally mapped database.

Unfortunately, the crawler has no way of detecting values that have gone out of sync with an externally mapped database. However, it's advised that the process of uploading the TCG prices to externally mapped databases should log warnings about it. This primarily concerns changes and deletions, since new values are already automatically detected (see item 4). With the help of these logs, it should be possible to correct the mappings manually.

If one or more property values of a mapping have changed, and the cardId, *CardVariantId, and expansionId properties are set, then all other properties are ignored during the crawling process. This means that no warnings or errors will be logged, because there's no need to rely on the other property values.

If the TCG Collector database is used, product mappings can be synchronized using the cms tcgplayer sync-product-mappings command.