Skip to content

Instantly share code, notes, and snippets.

@guregu
Last active October 15, 2023 19:59
Show Gist options
  • Save guregu/473acbe02b6ae6f956b2e8cc9177df2e to your computer and use it in GitHub Desktop.
Save guregu/473acbe02b6ae6f956b2e8cc9177df2e to your computer and use it in GitHub Desktop.

Welcome

FFTBG.com provides regularly updated unofficial information about the FFT Battleground stream, an ever ongoing Final Fantasy Tactics AI tournament. In addition to HTML-based information for end-users, we also provide a JSON API. Feel free to use these APIs for analysis or whatever you fancy.

Table of Contents

Tournaments API

Format: https://fftbg.com/api/tournaments[?limit=:n][&before=:id][&filter=complete]

Pagination

You can limit the number of results with limit.

Example: https://fftbg.com/api/tournaments?limit=50

The results are in descending order from the latest tournaments, so the first result is the newest tournament. To get tournaments before (but not including) a certain ID, use before.

Example: https://fftbg.com/api/tournaments?before=1581183844227&limit=50

In the response's Link HTTP header there will be a URL for the next page with rel="next", like so:

Link: <https://fftbg.com/api/tournaments?before=1581183844227&limit=50>; rel="next"

However, if there aren't any more pages, there won't be a Link header.

You can also use the ID of the last element in the results array as before to find the next page. If you get an empty array as results ([]), there aren't any more pages. It's possible that the last page will be empty.

Filtering

Additionally, you can now filter the results to only include completed tournaments with the winners list filled in (i.e. it excludes in-progress, aborted, and pre-winner.txt tournaments). Just use filter=complete:

Example: https://fftbg.com/api/tournaments?limit=50&filter=complete

(This paginates in the same way as above. All parameters are able to be mixed, and all are optional.)

Tournament API

Format: https://fftbg.com/api/tournament/:id

You can get the results for an individual tournament with this API.

Example: https://fftbg.com/api/tournament/1581360864550

(The old URL format, ex. https://fftbg.com/tournament/1581360864550/json will continue to work.)

Champions API

Format: https://fftbg.com/api/champions/[:season][?limit=:n][&after=:rank or id][&sort=latest]

Returns a list of champions. If season isn't specified, it will use the current season. By default, it's ordered by rank descending (rank #1 first). You can use sort=latest to get the newest champions first instead. Like the tournaments API, when limit is specified the Link HTTP header will contain the next page if there's more results.

Note that this API uses after for pagination. In rank mode (default), set it to the last champion's rank. In latest mode, set it to the last the champion's ID to get the next page (the Link header does this for you).

Example: https://fftbg.com/api/champions/1?limit=8&after=8 (returns champions ranked 9-16 for season 1)

Champion API

Format: https://fftbg.com/api/champion/:id

Returns a single champion. Champion IDs aren't reset between seasons.

Example: https://fftbg.com/api/champion/244 (returns champion 244)

Tips API

Format: https://fftbg.com/api/tips

Returns tooltip information about items, classes, abilities, skills.

Response format:

type Tips struct {
	Item             map[string]string // item name → item info
	ItemLastMod      time.Time
	Ability          map[string]string // ability name → ability info
	AbilityLastMod   time.Time
	UserSkill        map[string]string // user skill name → user skill info
	UserSkillLastMod time.Time

	MonsterSkills  map[string][]string // monster name → list of skills
	MonsterLastMod time.Time
}

Track (Now Playing) API

Format: https://fftbg.com/api/track

Returns currently playing track title, its start time, and its end time.

Response format:

type TrackStatus struct {
	Title   string
	Start   time.Time
	End     time.Time
	LastMod time.Time
}

Notes

Update timing

Data is generally updated every minute. Directly after the latest tournament finishes, I check more often so that we get an update before the first betting window ends for the new tournament.

LastMod

LastMod is the last modified time of the folder for the raw dump (official source data). It's not necessarily the last time a match was updated. (TODO: add that)

Times

Most times are provided as RFC3339 strings in the EST time zone (the "native" time zone of the stream). However, some IDs are in Unix milliseconds in the PST time zone (such as the tournament ID, and the defeat "ID" of champions). That's just how they are in the original data 🤷.

Completeness

Some tournaments are incomplete for various reasons. The oldest tournaments don't have winner data because it wasn't provided yet. Some tournaments were short tests or crashed and didn't complete. I'll look into flagging these later. You can be sure a tournament is complete when its Winners array has 8 items. The tournaments API provides an option to filter out incomplete tournaments.

Botting

Before you make a bot for Twitch that interacts with the stream, check the rules on the official FFTBG Discord or you will get banned. Most botting is explicitly forbidden, some is OK with permission. The rules are known to change so always double check.

Questions/Comments

I can be reached on Discord at tiko#9363. You can also find me in the #development channel on the official FFTBG Discord, where I post regular updates on changes to this site and its API.

API Update History

  • 2023-10-16: Added track API.
  • 2020-02-15: Added tips API.
  • 2020-02-12: Added champion(s) API.
  • 2020-02-11: Added pagination and filtering to the tournaments API.
  • 2020-02-02: Added tournaments API.
  • 2020-01-30: FFTBG.com launched.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment