Child’s Play JSON API

This is a bit different from my usual WordPress/PHP posts, but I still wanted to share as a general development exercise and also to hopefully let other people know what I discovered about working with Child’s Play.

Childs Play Logo

I am friends with the couple who runs the Game On Marathon, a 100-hour video gaming marathon which raises money every year for the Child’s Play charity. As part of the festivities when the event is happening, they needed the ability to trigger different giveaways based on when we hit certain milestones in the fundraising effort. There is a C++ script which handles these giveaways, but it needs to be told what dollar amount the event is at and that was game on marathoncurrently being done by hand. Child’s Play has a website widget which displays the info, but there didn’t seem to be a way of easily getting their hands on the donation total at different points in time for the program so they asked if I may be able to help.

At first I tried to scrape the website via remote POST, but that was a bust. Since the Child’s Play widget is driven by a `.js` script include, none of the generated markup was available in the DOM when you hit the page from a remote script. While looking through the js source, however, I found reference to a JSON API endpoint which looked promising. I had initially tried googling for such a thing, but came up empty, so my guess is that this is an API they possibly only mean to use internally / by their own tools.

While there is documentation to be found at https://donate.childsplaycharity.org/api/, I strongly recommend being respectful of this API to ensure it keeps working for everyone involved. Do not abuse calls to this!

I plugged the discovered URI into my browser with our eventID, and found success! The following is the result of accessing https://donate.childsplaycharity.org/api/event/969562d55ee65704934fc96c389a2ebd/json/ (Line breaks added in the code below for ease of reading)

{
  "c":"T",
  "id":"969562d55ee65704934fc96c389a2ebd",
  "approval":1,
  "prefix":"",
  "title":"Game On Marathon III",
  "description":"Join us while we are battling it out in the attempt save various princesses. We hand picked our favorite games to play from start to finish, and this year we will be doing it for 100 Hours! You are part of the marathon, Twitch chat is displayed in the gaming room for everyone to see! We are going to have hand made prizes, exciting events, trivia, challenges, etc... that you get to participate in!",
  "start_date":"2015-10-15 00:01:00",
  "end_date":"2015-10-19 14:00:00",
  "currency":"USD",
  "symbol":"US $",
  "contributions":6,
  "total":261,
  "goal":5000,
  "percentage":5
}

As another aside: If you remove the `/json/` from the end of the URI, you will get an html-based version of the same data visible in the browser, aka: https://donate.childsplaycharity.org/api/event/969562d55ee65704934fc96c389a2ebd/

Now I just had to get the data into something usable. We needed to access this data from something that would create a local text file to be read by the C++ program, so I wrote off web scripting as a solution. Since my background is originally in classic ASP and vbscript, I went with what was most familiar and decided to roll a quick `.vbs` file. Sure I probably could have used a “newer” technology, and probably a language that actually has native support for reading the JSON response… but this was meant as a quick-and-dirty “get it done” project.

'****************************************************************************
'****************************************************************************
' Consume data for Game On Marathon III
'****************************************************************************
'****************************************************************************


'****************************************************************************
' Variables
' You should only need to adjust variables in this section of the file
'****************************************************************************
targetURL = "https://donate.childsplaycharity.org/api/event/969562d55ee65704934fc96c389a2ebd/json/"
outFile = "c:\users\dave.mchale\desktop\gom_results.txt"


'****************************************************************************
' Initialize FSO for file writing
'****************************************************************************
Set objFSO=CreateObject("Scripting.FileSystemObject")
Set objFile = objFSO.CreateTextFile( outFile, True )


'****************************************************************************
' HTTPS post to Child's Play JSON API
'****************************************************************************
dim xHttp: Set xHttp = createobject("MSXML2.ServerXMLHTTP")
xHttp.Open "GET", targetURL, False

' 2 stands for SXH_OPTION_IGNORE_SERVER_SSL_CERT_ERROR_FLAGS
' 13056 means ignore all server side cert error
xHttp.setOption 2, 13056
xHttp.Send

' read response body
content = xHttp.responseText


'****************************************************************************
' Janky string manipulation for parsing our JSON data
' VBScript sucks with JSON and we didn't need much data (or complicated data)
' so we just get away with this BS :)
'****************************************************************************  
contribution_loc = InStr( content, """contributions""" ) + 16
next_comma = right(content, len(content)-contribution_loc)
contribution_val = mid( content, contribution_loc, InStr(next_comma, ",") )

total_loc = InStr( content, """total""" ) + 8
next_comma = right(content, len(content)-total_loc)
total_val = mid( content, total_loc, InStr(next_comma, ",") )

goal_loc = InStr( content, """goal""" ) + 7
next_comma = right(content, len(content)-goal_loc)
goal_val = mid( content, goal_loc, InStr(next_comma, ",") )

percentage_loc = InStr( content, """percentage""" ) + 13
next_comma = right(content, len(content)-percentage_loc)
percentage_val = mid( content, percentage_loc, InStr(next_comma, "}") )

'WScript.echo contribution_val & " contributions, $" & total_val & " total raised of $" & goal_val & " which is " & percentage_val & "% of goal."

'****************************************************************************
' Write the contribution total value to file
'****************************************************************************
objFile.Write total_val
objFile.Close

The `.vbs` file will be attached to a scheduled task for refreshing the value stored in the text file, and the C++ script will run on its own scheduled task to read that file for the latest value and do whatever it needs to do with that data.

While this script accesses the “general” event endpoint and then pulls apart the results to discover different values, it’s important to note that I also could have used the “total”-specific endpoint to only pull that data. https://donate.childsplaycharity.org/api/event/total/969562d55ee65704934fc96c389a2ebd/json (again, refer to the documentation link at the root /api/ path for information on all available endpoints) I wanted this script to be as flexible as possible, so I felt it was best to query all the data and then only use as much or as little as I wanted.

With luck, knowledge of this API and/or the example code in the `.vbs` file above helps someone else who wants or needs to do something similar. Happy programming!

Leave a Reply