I love playing Hearthstone, and I love developing stuff. It seemed like a natural fit for me to want to develop something on top of Hearthstone.

This post is just some notes I have taken while researching Hearthstone APIs.

Hearthstone?

Hearthstone is a free to play online card game where you try and beat your opponent by playing cards that counteract their cards and gain board advantage. If you have ever played Magic the Gathering or even the Pokemon card games it is in the same area.

It is fun and while you can easily spend hours in the game the individual games only last 10 or so minutes, so you can get quick Hearthstone fixes!

The data I would love

In an ideal world the data that would be exposed is;

  • Card info
  • Match info
  • Player stats
  • Deck info

Each of these come with their own set of questions around what would players want, and some would be far harder to achieve than others. Like I say, an in an ideal world!

Official Hearthstone API

Unfortunately there isn't one, and I can't find any source from Blizzard that would suggest there is going to be on at any point in the future.

This means I am going to need to look at unofficial, fan-made APIs.

Lots of Dead Ends

Before I talk about the couple of APIs that I did manage to find. I must warn you that there are currently a lot of dead ends. A lot of old conversations that end in links which go nowhere.

Notable examples are hearthstone-api.com and hearthstoneapi.com – both of which promised so much but didn't stand the test of time!

Hearthstone JSON

The first result many people will come across is Hearthstone JSON, this is a great project which provides a JSON file that you can feed into your application to query card information.

It is updated regularly. At the time of writing this post Hearthsone JSON has been updated to reflect the Hearthstone changes as per patch 2.1.0.7628, which I believe are the newest changes currently available.

The JSON is generated using a tool which grabs the data straight from Hearthstone game files.

The only issue I can see with this is that you would want the JSON stored locally in your project, so you would need to either write something to attempt to see when the JSON file is updated or you would need to manually remember to look for updates. Thinking about it I guess you could just grab the latest JSON blindly every so often – I wouldn't want to put too much load on their server though if everyone was doing that.

IrythiaHS

IrythiaHS tries to solve the problem of keeping your data up to date by being a third party API which you can actively query. This means no local JSON files and when it gets updated all clients talking to it would be updated.

The API is hosted by MashApe which is a service which manages APIs for folk, I signed up (free) and it seems useful.

My main concern with Irythia is that the data didn't seem to be kept up to date. For example Madder Bomber wasn't found in its list of single cards.

This would make me unlikely to want to use it.

Room for improvement?

Unless Hearthstone comes out with an official API I don't think we will get many of the things on my wishlist, so focusing purely on card details I think if the two APIs I have found were to be combined that would be ideal.

I am tempted to make something on top of Hearthstone JSON that would make this possible.