UIL-API

An API Reimplementation and frontend of the UIL Previous Year Scoring records, as UIL does not expose the API calls utilized by the scoring website to get the information.

This application came to rise in early 2021 as I realized I was unable to access any parsable data from the official UIL website. This "API" effectively reimplements backend PHP server used by the UIL website by crawling the website and obtaining data from calls made by the API. Unfortunately, due to the nature of this software, there is a risk that one day the format of the website.

Why does this exist

The UIL website is really weird. They seemingly don't have an API, but instead scores are stored on a remote server and an XHTML file is automatically generated by some PHP service on the serverside. This makes accessing the data pretty challenging, because you have to interpret the XHTML given instead.

This "API" interprets the XHTML generated by the remote server and compiles it into a JSONObject. It can currently pull user scores, schools, ranks, and other information that might be of use. The frontend started off very small but has grown into a semi-competent frontend (that i'd reason is better than the official website) with support for calculating odds of winning and calculating scores, alongside generating pie charts and getting statewide and regional wide results. This is the part that I'm working on expanding most.

Usage

Running the server isn't difficult. Git clone the repository by running this command:

    git clone https://github.com/Knucklesfan/UilAPI.git

cd into the uil-api-js folder: (TODO: Make this the main repo)

cd uil-api-js

Ensure that you have both nodejs and NPM installed:

• Windows:

  You can download the latest version of node.js and NPM from the Node.JS Website

• Ubuntu/Debian:

sudo apt install nodejs npm

• Arch Linux (i use arch btw.)

pacman -S nodejs npm

Inside the cloned folder, install the following packages:

npm install --save express cheerio

Last but not least, run the server:

node server.js

TODO

The following features are very possible in the near future.

1. Get scores from multiple years together for everyone or for a specific person
2. Improve formatting of page
3. Clean up the ugly code.

API Specification

The API server has two functions, /getScore and /getEvents. The following is an explaination of the functions of both.

/getScore

The getScore call takes 5 inputs, and returns one array of JsonObjects. Inputs:

Input	Type
subject	String
region	Number
conf	String
year	Number
district	String

Outputs:

Output	Type
people	Person[]

/getEvents

The getEvents call takes 0 inputs, and returns two arrays of Strings. Events is the internal name of the event, while words is the human legible equivalent. Inputs:

Input	Type
none	null

Outputs:

Output	Type
events	String[]
words	String[]

Person Class

The Person class is returned by the /getScore function. The person class is defined as this:

Public Variables:

Output	Type
year	String
name	String
school	String
event	String
district	String
score	Number
place	Number
region	Number

Public methods:

Method	Type
toString()	String