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 May 19, 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 is a dictionary of price objects, keys are regular and foil STRING.
  • For each price object, 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"
    },
    "retail": {
        "STRING": {
            "STRING": {
                "regular": 0.0
            },
            "STRING": {
                "regular": 0.0,
                "foil": 0.0
            }
        }
    },
    "buylist": {}
}

Options

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.

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, or Scryfall hashes.

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.

Clone this wiki locally