TBA API for upcoming matches

I am using the TBA API v3 in Python for some scouting/strategy work. I need to pull a list of upcoming qualification matches (with teams on each alliance) for a given event. I see the API has a function to read all the matches (/event/{event_key}/matches), but it is out of order and using this would require a lot of post processing. I was wondering if there was an easier way to read specifically the upcoming matches. Thanks.

The API itself returns matches in order - you might look to query the API directly if whatever Python library you’re using doesn’t respect order (I’m not entirely sure why it wouldn’t).

I think I know what you mean. @Zach_O, the API does not return them in order (I was surprised, too).

They are returned by the API in alphabetical order by match key. This is fine for qualifications but gets a little tricky in elims. It is a bit screwed up within quals, too, actually since match numbers are single digits sorted alphabetically rather than numerically.

Lists are sorted like:

eventcode_f1m1
eventcode_f1m2
…
eventcode_qf1m1
eventcode_qf2m1
…
eventcode_qm1
eventcode_qm10
eventcode_qm11
…
eventcode_qm2
eventcode_qm20
eventcode_qm21
…
eventcode_sf1m1
eventcode_sf2m1
…

I don’t know what the answer is, but trying to provide some more context.

1 Like

I ran into the same issue. I have a work around for teams that aren’t in elimination rounds. If you get a list of teams just in qualification matches and you sore by the length it will pull the qm1 to the top. I haven’t found a good way to deal with elimination matches yet. I am using the tbapy library

matches = tba.team_matches(team=int(team), event=event, year=2019, keys=True)
matches.sort(key=len)

Edit: We can sort these by scheduled time

def match_sort_key(match):
    return match['time']

print([x['key'] for x in sorted(tba.event_matches('2019mike2'), key=match_sort_key)])
2 Likes

That makes sense. Thanks everyone for the quick response!

If you want to know of a match happened or not, check to see if actual_time is null. Or in your case, None.

1 Like

There are two orders TBA displays matches (this may also vary a bit by surface, IIRC).

While events are live, TBA will display matches in “play order” (qf1m1, qf2m1, etc).

Afterwards, however, matches are displayed in “logical order”, which is generally easier to follow (qf1m1, qf1m2, qf2m1, etc).

Since we don’t have a consistent standard sort order (intentionally), we decided not to impose one on API responses, and instead return matches sorted lexicographically by match key. It’s usually pretty trivial to sort the list based on the criteria your use case calls for, so we didn’t worry about it too much.

That being said, I’m open to a pull request that decides to be opinionated on the subject (along with a rationale why) :smile:

1 Like

FWIW, this is only a valid check for recent(ish) events using a real FMS with data sync enabled. Not all offseasons (or historical events) have actual_time set, so it won’t be perfectly accurate.

The only reliable way to determine if a match has been played is to check the score blob and sure that neither alliance has a score of -1.

Aside: I really wish this had a better data model…

1 Like