Getting Started
This API is a searchable database of MLP:CCG cards. The query system provides a way to select cards meeting various criteria, and there's some other functionality. The source data is either scraped from the Official Card Reference (OCR) documents or entered by hand where necessary (all flavor text, the entire print revision, cards which don't exist in the OCR). Spelling errors and/or inaccuracies might be a thing and if you let me know about them, I'll fix them sooner or later.
If you're here looking for place to search for cards, you want this.
Definitions
- revision - in most cases, each version of an OCR maps to a revision, but there are two special revisions, Print and Live. Print refers to the cards as they were printed, usually the earliest version (so Marvelous Chapeau's print revision would have the text that drops wild requirements to 1). Live includes all cards in the latest OCR, plus any that have been spoiled or otherwise exist but aren't in an OCR.
- revision_guid - identifies a specific revision. You can get these from asking about the rev tag.
- card_guid - refers to a specific card, roughly equivalent to a card's name (= title, subtitle). You can get these from the card objects that some functions return.
- card_version_guid - refers to a specific card from a specific revision. A given card_version_guid will always refer to a card with those exact attributes, even if the card changes anywhere else e.g. it's possible to refer to the pre-errata version of The High Ground and it will always be the pre-errata version.
Response structure
The API returns a JSON object for successful responses. The basic structure is always the same:
{
comment: "MLP:CCG Card API v1 - @Aracat1"
date: <date of response>
data: <response content>
warnings: array of strings describing non-error issues with your request
}
HTTP 400 errors are generally user errors, meaning you provided some bad input to the API
HTTP 500 errors are internal to the API, meaning I screwed something up (and I'd appreciate knowing what you were doing so I can fix it)
Interface contract
I do not expect to change the format of response content, but I may add fields to any JSON object. The data for the print and live revisions will change and may have errors, not all of which are necessarily my fault (let me tell you how much fun it is to keep up with Enterplay screwing up the OCR). Functionality will doubtlessly be added, but it should only change if there's a bug. I can't give a good uptime guarantee/SLA because I have a day job but I'll probably notice sooner or later and getting me on the horn (see bottom) will accelerate this process considerably.
Terms of use
Requests to the API, including any parameters you or the users of your client/app send, are logged for debugging and abuse prevention purposes.
No guarantee is given about the suitability for any purpose or the accuracy of the response data.
I do not claim ownership of the response data; it belongs to Hasbro or Enterplay or somebody like that.
Use of the API constitutes understanding of and agreement to the above. Your client/app should inform your users of this, if this API is being used as a 3rd party.
Please consider linking to this page if you found the API useful <3.
/
Here
/cards/<card_version_guid>
Gets the specified card by card_version_guid (see above)
The response content is a JSON object with various card attributes, which is explained in the /cards section below.
Example: The High Ground, pre-errata
/cards
This is the card search function
Takes GET parameters:
- query - a string composed of search tags or full text search terms
- list - if set to anything, only returns a small subset of attributes for each card
The response content is an array of JSON objects with various card attributes.
Query string
See here
Programatic use of the API may want all cards. To get this, you should explicitly specify a revision.
Card objects
{
allids - array of strings, one for each known number/set
bonus
card_guid - this card's card_guid
card_version_guid - this card's card_version_guid
color
cost
flavortext
fullname - the card's full name; title, subtitle
gametext
number - the card's number within its set
power
prireq
rarity
req
secreq
set - a two letter code for the set
shortname - a nickname for the card (this is good to display in a big list)
subtitle
status
title
traits
type
wildreq
}
A list-type card object only has the card_guid, card_version_guid, fullname and shortname fields. Otherwise, all cards always have all fields, though they may be null, zero or empty if the field isn't applicable to the card's type. If a Mane Character has different values for the front and back, they are typically separated by a slash, though game text has explicit labels (blame Enterplay for that one).
See the query string help for definitions of most of these fields - tag names generally line up with field names.
Example: not-orange earth pony entry which costs less than 4 AT
/tags
This gets you a list of the supported tags. You can get more information about each tag using the /tag/<name> function, explained below.
The response content is an array of tag names.
/tag/<name>
This gets you information about what the specified tag can take for values.
The response content is a JSON object which has a type field which tells you how the tag will do searches, a value field which tells you what kind of values it will take, and an enum field.
If not null, the enum field is a list of objects which have a label field which is the full/proper name and an aliases field which holds an array of strings. Tags which have a non-null enum field will only accept one of those values as input.
Example: acceptable values for the set tag
/aliases
The response content is equal to the enum field of /tag/alias.
aliases
Questions, comments and whining but not complaining can be sent to @Aracat1 or find me on irc.canternet.org #mlpccg
Changes
Apr 18: Added fields for title and subtitle
Apr 8: Various backend changes
Mar 18: Added allids field
Mar 1: Rewrote a bunch of stuff so card_version_guids are actually static. Had to wipe the DB to fix this :<
Jan 22: Added status field to deal with ban list