Squiggle API

v1.5.0

The Squiggle API offers public access to raw data about AFL games and predictions made by popular online models. It is available in computer-friendly formats so you can automatically import it into a spreadsheet or similar program for your own analysis.

Selecting DataUsing DataAutomated UsageChangelog

Selecting Data

Query Type (required)

You must supply one of these values as the parameter "q":

teamsInfo about teams (e.g. Richmond, Geelong, West Coast)
gamesInfo about games (e.g. Round 1, 2019 Richmond v Carlton)
sourcesInfo about models (e.g. Matter of Stats, GRAFT, Swinburne)
tipsInfo about tips and predictions made by models
standingsInfo about team standings (i.e. the ladder)
ladderInfo about predicted ladders generated by models
virtualInfo about Virtually Season 2020
pavInfo about Player Approximate Value from HPN Footy

Format (optional)

You may specify a preferred output format using the parameter "format":

JSONJSON format (default)
XMLXML format
CSVComma-separated values

Additional Parameters (optional)

Each query type has additional parameters that you may specify in order to restrict the data to a particular subset that you're interested in. See below for details.

To exclude data, prepend the parameter value with an exclamation mark (!), e.g. 2020 games except Round 1.

Default behavior when parameters aren't specified (e.g. requesting "?q=games" with no "year=xxxx" parameter) is undefined and subject to change. For example, at present, "?q=games" returns data on all games, but in the future, it may default to the current year. For reliability, supply parameters to identify the exact data you want.

teams

Fetch info about one or more AFL teams.

https://api.squiggle.com.au/?q=teams

Examples:
Optional Parameters:
teamTeam ID

games

Fetch info about one or more games.

https://api.squiggle.com.au/?q=games

Examples:
Optional Parameters:
yearYear
roundRound
gameGame ID
completePercent of game complete

Note: The original 2020 fixture is available as "2020-original" — e.g. all originally fixtured 2020 games.

sources

Fetch info about one or more computer models.

https://api.squiggle.com.au/?q=sources

Examples:
Optional Parameters:
sourceSource ID

tips

Fetch info about one or more tips made by computer models.

https://api.squiggle.com.au/?q=tips

Examples:
Optional Parameters:
yearYear
roundRound
gameGame ID
gameSource ID
completePercent of game complete

standings

Fetch info about team standings at a point in time, i.e. the ladder.

https://api.squiggle.com.au/?q=standings

Examples:
Optional Parameters:
yearYear
roundRound

ladder

Fetch info about one or more projected ladders generated by computer models. For the actual ladder, see standings instead.

https://api.squiggle.com.au/?q=ladder

Examples:
Optional Parameters:
yearYear
roundRound
sourceSource ID

virtual

Fetch info about one or more games in Virtually Season 2020.

https://api.squiggle.com.au/?q=virtual

Examples:
Optional Parameters:
yearYear
roundRound
gameGame ID
completePercent of game complete

pav

Fetch info about players using HPN Footy's Player Approximate Value.

https://api.squiggle.com.au/?q=pav

Examples:
Optional Parameters:
firstnameExact Player First Name
surnameExact Player Surname
namePlayer Name (full or part)
matchIf set, match loosely on name and return summary info
yearYear
teamTeam ID
Limitations:

A maximum of 50 rows will be returned.

Data is provided by HPN Footy.

Additional Examples

Using Data

Google Sheets

To automatically import data into Google Sheets, enter a formula like this into a cell:

	=IMPORTXML("https://api.squiggle.com.au/?q=tips;year=2018;source=1;format=xml", "/*/*")
	

... wait a second and bam! Data appears.

Microsoft Excel

I believe you can do the same thing in Excel, although I don't own a copy so can't test. From what I've read, in newer versions you do: DataGet & TransformFrom FileFrom JSON and then can enter an URL (like https://api.squiggle.com.au/?q=tips;year=2018;source=1).

Excel can read JSON, XML, and CSV, so it shouldn't matter which you choose, so long as the URL matches the function. (That is, if you click "From JSON", don't give it an URL with ";format=xml".)

LibreOffice Calc

Use SheetLink to External Data and paste in the appropriate URL (like https://api.squiggle.com.au/?q=teams;format=csv). You may need to specify XML or CSV format (not JSON).

Automated Usage

Sometimes well-meaning scripts and bots spiral out of control and make hundreds or thousands of requests for data in a very short period. If you set your bot's UserAgent to something informative, I can contact you if this happens and explain the problem. If you don't, all I can do is block you. So if you're seeing a block message, that's why.

Please write a well-behaved bot:

  1. Set the UserAgent to something that identifies it and allows me to contact you.

  2. Cache and re-use the data you get. (I am looking right now at a bot that is fetching the names of all AFL teams in bursts of 18 identical requests, and another that asks the API every 9 seconds for every bit of data it has on everything.)

  3. Avoid making large numbers of simultaneous requests — if you need information on a season's worth of games, fetch it all in one request, not one request per game.

  4. Avoid fetching more data than you need — if you only need info on one game, don't ask for the whole season.

  5. Consider what your bot will do when it encounters an unexpected return code or data, and make it not repeat the same request over and over at maximum speed.

Changelog

June 20201.5.0Added pav for HPN Footy's Player Approximate Value ratings.
June 20201.4.1Restored original 2020 fixture as '2020-original'.
March 20201.4.0Added virtual for Virtually Season 2020.
June 20191.3.0Added standings for generating actual ladder at a point in time
June 20191.2.0Added support for output as comma-separated values (CSV)
May 20191.1.0Added ladder for outputting ladder predictions
April 20181.0.0Original version

Max Barry

squiggle.com.au

twitter.com/squiggleAFL