Skip to content
This repository has been archived by the owner on Apr 23, 2024. It is now read-only.

API documentation

Jump to bottom
Vittorio Giovara edited this page Oct 2, 2021 · 20 revisions

BAN Price API

Data format

API responses are transmitted using JSON encoding, compressed using GZIP. Data uses the concept of unsorted dictionaries to represent a key:value pair.

There is a metadata meta section, containing the date of the API request and the version of the API.

  • For retail and buylist entries, there is a dictionary of card objects, keys are encoded as STRING.
  • For each card object, there is a dictionary of store objects, keys are encoded as STRING.
  • For each store object, there two optional keys, regular and foil STRING.
    • The presence of these keys depends on the card properties and on the id output requested
  • For each price object, there is a price value in FLOAT64.
    • This value represent the highest available price on the platform.
    • (optional) The store object may contain additional keys, namely qty and qty_foil STRING.
      • Each qty object is a quantity value in INT.
      • This value is tied to the highest available price reported.
    • (optional) The store object may contain an additional dictionary for condition prices.
      • Keys for condition can be NM, SP, MP, HP, and PO STRING, or NM_foil, SP_foil, MP_foil, HP_foil, and PO_foil STRING.
      • For each condition key, there is a price value in FLOAT64.

A null object (missing store, missing card, or missing price) will not be represented, and thus will simply be left out of the response.

The price values are in USD.

{
    "error": "",
    "meta": {
        "date": "STRING",
        "version": "STRING",
        "base_url": "STRING"
    },
    "retail": {
        "STRING": {
            "STRING": {
                "regular": 0.0
            },
            "STRING": {
                "regular": 0.0,
                "foil": 0.0
            },
            "STRING": {
                "foil": 0.0,
                "qty_foil": 0
            },
            "STRING": {
                "regular": 0.0,
                "conditions": {
                     "NM": 0.0
                }
            },
        }
    },
    "buylist": {}
}

Options

Change output ID

It is possible to change the output id of the returned card objects from the default MTGBAN UUID.

This is done by setting the id query parameters to one of the following options:

id value description
tcg Use TCGplayer Product Ids
scryfall Use Scryfall hashes
mtgjson Use MTGJSON UUID
mkm Use Cardmarket ids
ck* Use Cardkingdom ids
mtgban* Use MTGBAN UUID
  • = Note that these values separate foil and regular prices under two different ids.

Quantities details

It is possible to request quantities to be embedded in the response: set qty to true. The returned value corresponds to the entire inventory available across conditions (if retail) or the amount requested for purchase. Only a few stores export this kind of information.

Single vendor and single card conditions

It is possible to request detailed information of a single vendor: set vendor to the desired vendor tag. Alternatively when requesting single card prices, it is possible to obtain the same detail information by using the conds query parameter and set it to true.

In this case, the response will contain an additional dictionary with per conditions prices. This mode is not available when quantities are requested.

Endpoints

Full snapshot

The default endpoint provides a full snapshot of the data you were given access to. You can request retail, buylist, or all for both types of pricing.

Edition snapshot

You can select a subset of the data, filtering a single edition only. We follow Scryfall naming convention as a reference.

Single card price

You can select a single card too. Both foil and regular prices will be provided.

The API supports MTGBAN ids, MTGJSON UUIDs, Scryfall hashes, or TCGplayer ids.

Redirect

MTGBAN offers a free to use redirect endpoint. Any single card page can be reached by building the url using data present in the response. The URL is built by concatenating the Metadata.BaseURL value with the vendor tag, followed by the card hash. The hash format can be any of MTGBAN ids, MTGJSON UUIDs, Scryfall hashes, or TCGplayer ids.

Example:

https://www.mtgban.com/go/CK/7da23b15-dfb8-4267-9b33-d7a4c035c434

Authentication

All requests need to have the sig query parameter passed through. The signature will grant access to one mode of operations (retail/buylist/all) according to the access level you were granted.

Response codes

code description action
301 Moved permanently Request was made over an insecure channel, use https
492 Too many requests Perform fewer requests at the same time
502 Bad gateway Server boostrap, try again later
503 Service unavailable Server loading, try again later
200 Success JSON is returned

Please note that when JSON is returned you should check the error field for any problem reported while parsing the request.

Rate limits

Each user is granted a maximum of 10 requests per second.

Changelog

2021-09-13

  • Etched cards are now available, following the same semantics of foil printings.

2021-08-17

  • You can obtain condition prices from single card requests too.

2021-07-07

  • You can request data from a single vendor. The output will include per condition prices as available

2021-07-01

  • You can use TCG IDs in singles input requests
  • You can request quantities available by setting qty=true query parameter (only available for selected vendors)
  • You can go to the vendor retail page by concatenating the Metadata.BaseURL, the vendor tag, and the id/hash of the card

2021-06-01

  • Initial public version
Clone this wiki locally