This page documents the CTLive API support for posting race results in General Results Upload (GRU) format.
A GRU file is a delimited text file with a header row followed by one row per athlete of demographics and results. Our API supports comma-delimited text files, json files and xml files. While you could submit a "GRU" in json or xml, its more efficient to just upload a standard csv.
The header row is very important. It is the only metadata we have about what data each column contains. In order for us to be able to correctly process your results file, you should name your column headers with the following conventions in mind.
Some columns don't exhibit much variation.
The country column is an example. Even city only
allows for one common alternative (town). However some can vary
quite a bit so we have written down patterns and examples in the following
table to help you understand how you can name your columns.
The Name Pattern column in the table below identifies one
or more tokens that can be combined to make a header name. Each token
represents one or more alternative spellings, with the alternatives separated
in the pattern by a pipe character. So in the table the token
{chrono|ctlive|entry} can be spelled as either
chrono, or ctlive, or entry. If a token
is optional, it is followed by a question mark in the table. If tokens are
surrounded by double braces ({{token}}) then the tokens can be
combined in any order, otherwise they must be in the order specified. Tokens
can be combined with a space, an underscore, or with no character at all. The
case of the letters is irrelevant to our pattern matcher (CTLive = CtLiVe =
CTLIvE), so we use all lowercase here.
Several of the timing and scoring column headers may specify an
[interval-spec], or an interval specifier that describes which
course interval the column data refers to. CTLive scores all the intervals on a
race course and ranks all athletes within all their brackets on all of those
intervals. To be able to capture that, we need a way to specify times, ranks
and paces for arbitrary intervals. The full course interval can be represented
with the token {fin|final|finish}. Other intervals should usually
be specified by the distance from the start line to the end of the interval. So
in a marathon where you've got multiple split points, you might represent the
intervals as {5K|13K|21K|32K|fin|final|finish}, for instance. If
no interval spec is provided, the full interval is assumed.
| Data Column | Name Pattern | Example Names |
|---|---|---|
| Identity & Demographics | ||
| ChronoTrack ID | {chrono|ctlive|entry} {id} | chrono id, chrono_id, chronoid, entry id, entry_id, entryid, ctlive id, ctlive_id, ctliveid |
| First Name | {f|first} {n|name} | first, first name, first names, first_name, firstname, fname, fn |
| Last Name | {l|last} {n|name} | last, last name, last names, last_name, lastname, lname, ln |
| Bib Number | {bib|race}? {#|no|num|number} | bib, bib #, bib num, bib number, bib#, bib_num, bib_number, bibnum, bibnumber, no, no., no_, num, number, race num, race number, race_num, race_number, racenum, racenumber |
| Tag Number | {tag|chip} {#|no|num|number|own|owner} | chip num, chip number, chip own, chip owner, chip_num, chip_number, chip_own, chip_owner, chipnum, chipnumber, chipown, chipowner, tag num, tag number, tag own, tag owner, tag_num, tag_number, tag_own, tag_owner, tagnum, tagnumber, tagown, tagowner |
| USAT Number | {usat|usatf} {#|id|no|num|number} | usat, usat #, usat id, usat num, usat_id, usat_num, usatid, usatnum, usatf, usatf #, usatf id, usatf num, usatf_id, usatf_num, ustafid, usatfnum |
| Age | {age} | age |
| Date of Birth |
{dob|birth|birthday}
{birth} {date}
{date} {of} {birth}
|
bdate, birth, birthdate, birthday, dob, d.o.b., date of birth, date_of_birth, dateofbirth |
| Gender | {gender|sex} | gender, sex |
| Division | {} | agdesc, age group, age_group, agegroup, class, div, div name, div_name, division, division name, division_name, divisionname, divname, bracket, primary bracket, primary_bracket, primarybracket |
| City | {city|town} | city, town |
| State | {state|province} | state, province |
| Country | {country} | country |
| Zip | {post|postal|zip} {code}? | postal code, postal_code, postalcode, post code, post_code, postcode, zip, zip code, zip_code, zipcode |
| Timing & Scoring | ||
| Chip Time | {{chip|tag|net}} {{time}}? {{[interval-spec]}}? | chip, chip final, chip time, chip_final, chip_time, chipfinal, chiptime, finish net, finish time net, finish_net, finish_time_net, finishnet, net, net time, net_time, nettime, time net, time_net, timenet, t_time, tag, tag final, tag time, tag_final, tag_time, tagfinal, tag_5K, 5k_tag_time |
| Chip Pace | {{chip|tag|net}} {{pace}} {{[interval-spec]}}? | chip_pace, tag_pace_5k, 15K_pace_net |
| Clock Time | {{clock|gun}} {{time}} {{[interval-spec]}}? | clock_time, gun_time, gun_time_15k, clock time 5k, 5k gun time |
| Clock Pace | {{clock|gun}} {{pace}}? {{[interval-spec]}}? | gun_pace, clock_pace_5k, 15K_pace_clock |
| Overall Place | {o|o all|over all}}? {{pl|plc|rnk|pos|rank|place|position}} {{[interval-spec]}}? | o all place, o_all_place, oallplace, oplace, overall place, place_overall, overallrank, place, position, opl_5k |
| Gender Place | {{g|s|gender|sex}} {{pl|plc|rnk|pos|rank|place|position}} {{[interval-spec]}}? | sex_place, splace, splc, gender rank, sex position, sex_rnk, gender_plc_5k |
| Division Place | {{div|class|division|bracket}} {{pl|plc|rnk|pos|rank|place|position}} {{[interval-spec]}}? | divpl, div_place, classplace, division_plc, bracket rank, class position, div_plc_5k, 15k_place_div |
The GRU file header does not contain enough metadata to properly display results for an event in CTLive. Some additional information is helpful, like the race type, start time of the race, end time of the race, the pace units for a given interval, the distance from the start of a given interval's end timing point. If you need to provide this data you can do so by using the following custom HTTP headers that you can include with your API request.
| HTTP Header | Meaning |
|---|---|
| X-Race-Type | Type of race ('running','biking','swimming','multisport','other') |
| X-Race-Start-Time | Start time of the race in format M/D/YYYY h:mm:ss.hs am/pm (eg. 3/7/2014 7:32:34.54 am) |
| X-Race-End-Time | End time of the race in format M/D/YYYY h:mm:ss.hs am/pm (eg. 3/7/2014 5:00:00 pm) |
| X-Pace-Unit-[interval-spec] | Pace unit that should be used for interval [interval-spec] (eg. X-Race-Pace-Unit-10k: min/mi). Admissable pace units include:
|
| X-Interval-Distance-[interval-spec] | Distance for interval [interval-spec] (eg. X-Interval-Distance-10k: 10km). Values can be expressed in any of the following units:
|
