What is this?
Have you ever wondered how many cards there are in The North Pacific? How many of them are legendary, epic, or ultra-rare? Or how many of them have golden badges?
Have you ever wanted to embark on collecting these sorts of cards, only to realize you do not even know which cards you need to collect? And how could you know - there are, after all, more than 350 thousand cards in both seasons, making it practically impossible to go through them one by one.
Card queries are here to help!
These pages make it easy to parse the official XML list of cards. For example, to get all the cards of The North Pacific, with the WA badge but without the delegate badge, and of uncommon rarity, you can open the card queries page, and enter the query:
How do I use the card queries pages?
Both the card queries and advanced ard queries pages include detailed use instructions. The pages also list all of the options you can use to search for cards. These include, among other things, badges, rarities, regions, trophies, and many more!
You can combine these options to form more complicated queries. Additionally, you can search for cards of either season. Finally, you can select from among a few different formatting options for the results, depending on what is the most convenient for you.
How is the advanced card queries page different?
Compared to the original version, the advanced card queries page allows making more complicated queries. In particular, whereas the original version allows only doing conjunctions (logical AND) between different (potentially negated, i.e., logical NOT) options, the advanced version allows using arbitrary combinations of disjunctions (logical OR) and conjunctions.
For example, using the advanced version, you can do a query of the form: "cards that have The North Pacific as region, and have either badge 'Admin' or badge 'Moderator'." Using the original version, this requires doing two queries, one for "cards that have The North Pacific as region, and have badge 'Admin'", another for "cards that have The North Pacific as region, and have badge 'Moderator'", and then manually merging the results from the two queries.
You can also use the advanced version to combine the decks of multiple puppets (use an OR to combine deck options), implement exclusive OR (XOR) operations (e.g., "cards that have either badge 'Admin' or badge 'WA', but not both), and so on. See this page for inspiration.
Which version should I use?
That is up to you to decide. The card queries uses (arguably) simpler syntax, very similar to the one used by NationStates for telegramming multiple nations. The advanced card queries page can do everything the simpler version can, and a lot more; but it uses (arguably) more complicated syntax.
You are welcome to use whichever version you prefer. You also do not have to commit to just one or the other version: both will remain available and you are welcome to switch back and forth as you like.
Can I call the card queries from my scripts?
Yes, you can! You can directly send GET requests to the daemon serving the advanced card queriespage. Here is an example GET request using cURL:
As with the regular page, you can specify your preferred output format, e.g., you can download the results directly in JSON output. Note that you need to use url-encoding for the "query" field of the GET request, because of the special characters it contains.
There are currently no hard-enforced rate limits for using the advanced card queries through scripts. However, please be reasonable and do not submit very large numbers of requests in short time intervals.
What if I still have questions?
Please feel free to contact Minister of Cards and Guildmaster Destructive Government Endorsing System. They would be happy to help!
This dispatch is updated automatically on a daily basis. Please do not edit manually.