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 17, 2023 · 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 three optional keys, regular, foil, and etched 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, qty_foil, and qty_etched 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 or NM_etched, SP_etched, MP_etched, HP_etched, and PO_etched 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 details

It is possible to request detailed information of a single vendor: set vendor to the desired vendor tag. The response will contain an additional dictionary with per conditions prices always.

Single card details

When requesting single card prices, it is possible to obtain the a detailed dictionary of per-condition prices. Set the conds query parameter to true.

Endpoints

Edition snapshot

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

This mode supports JSON by default, but also CSV by replacing the extension, such as https://www.mtgban.com/api/mtgban/buylist/10E.csv.

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.

This mode supports JSON by default, but also CSV by replacing the extension.

Full snapshot (deprecated)

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.

Note that full snapshots only offer JSON output. This endpoint is deprecated, and should not be used.

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

CSV Output

It is possible to change the output of the API from JSON to CSV - simply replace .json with .csv in the examples above. Note that this feature is not available when making a full snapshot request.

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

2022-08-10

  • Quantity and conditions query parameters are decoupled and can be requested at the same time.
  • The condition dictionary for buylist data returns a full map, containing the

2021-10-04

  • It is possible to export data as csv.

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