RunSignUp

RunSignUp API Documentation

Custom Results Page

Create a custom results page. You can use this to add your own division results, team results, etc. The request must be in JSON. An example request is shown below.

If you use the same year and id for custom results, old results with the same year and id will be automatically deleted.

The column count for each row in a segment must be the same for the column headers and all data rows.

The column_data_type array is optional. It provides additional data type information for the columns to make sorting more natural. The data type for a column may be "string", "float", "int", "uint", or "time".

The column_notification_placeholders array is optional. It maps a column to a placeholder in result notifications. The placeholders can be found on the Results > Customize Notifications dashboard for a race. If a segment has notification placeholders, a finish notification will be sent the first time a registration ID is seen (unless splits are defined). The registration IDs are specified through the row_registration_ids array. The registration ID for a row should not change after it is initially set.

The contains_split_time array is optional. It indicates which columns contain split times. The column must specify a data type of "time". If a segment has notification placeholders and at least one column includes split data, a split notification will be sent the first time a registration ID is seen with data for the split. You do not need to specify placeholders for the split times (although you can). In the split notification, the [CURRENT_SPLIT_NAME] and [CURRENT_SPLIT_TIME] placeholders will be automatically filled in. If splits are set up, the finishing notification will not be sent until the column specified as [TIME], [CLOCK_TIME], or [CHIP_TIME] in column_notification_placeholders is filled in. If both split and finish notifications are due to be sent for a single row, the split notifications will be skipped. You should NOT set up a split for the finish line as this can result in duplicate finish notifications.

The row_unique_ids array is optional and is a unique id within a segment that you assign to each row. This is used to allow you to update rows later. The id must be an unsigned 32-bit character.

You can set up automatic links to finish line video on YouTube by using the finish_line_videos parameter. The column_num parameter specifies column number that contains the finishing time (starting at index zero). The play_start_padding_sec parameter specifies the number of seconds ahead of the finisher’s time the video link should jump to. The start_clock_time parameter specifies the first clock time visible in the video. The start_clock_time_video_offset parameter specifies the time in the video at which this occurs. The end_clock_time parameter specifies the last clock time visible in the video. You can set up multiple videos for different finishing time ranges.

{
 "metadata" :
	{
		"id" : "@awards",
		"modified" : "2013-04-08 11:51:12",
		"origin" : "Optional description of software that produced the results.",
		"title" : "Custom Title",
		"year": 2013,
		"event_date": "2013-06-15"
	},
	"segments" :
	[
		{
			"header" :
			[
				"Vernon XX",
				"06/15/2013",
				"Weather: Hot and Humid, 99 deg.",
				"********** AWARDS LIST **************"
			]
		},
		{
			"header" : [ "********** FEMALE OVERALL RESULTS ***********" ],
			"columns" :
			[
				"Place",
				"First Name",
				"Last Name",
				"Age",
				"City",
				"State",
				"1 Mile",
				"2 Mile",
				"Finish"
			],
			"column_data_type" : [
				"uint",
				"string",
				"string",
				"int",
				"string",
				"string",
				"time",
				"time",
				"time"
			],
			"column_notification_placeholders": [
				"[PLACE]",
				"[FIRST_NAME]",
				"[LAST_NAME]",
				null,
				null,
				null,
				null,
				null,
				"[CLOCK_TIME]"
			],
			"contains_split_time": [
				false,
				false,
				false,
				false,
				false,
				false,
				true,
				true,
				false
			],
			"row_unique_ids" : [ 81 ],
			"row_registration_ids" : [ 123456 ],
			"rows" :
			[
				[ 1, "Karen", "Oats", "56", "Vernon", "NY", "6:00", "6:01", "1:04:37" ]
			]
		},
		{
			"header" : [ "********** MALE OVERALL RESULTS ***********" ],
			"columns" :
			[
				"Place",
				"First Name",
				"Last Name",
				"Age",
				"City",
				"State",
				"1 Mile",
				"2 Mile",
				"Finish"
			],
			"column_data_type" : [
				"uint",
				"string",
				"string",
				"int",
				"string",
				"string",
				"time",
				"time",
				"time"
			],
			"row_unique_ids" : [ 6 ],
			"rows" :
			[
				[ 1, "Dave", "Derry", "48", "Thompsonville", "RI", "5:00", "5:01", "56:33" ]
			]
		},
		{
			"header" : [ "MALE AGE GROUP  40 - 49" ],
			"columns" :
			[
				"Place",
				"Overall",
				"First Name",
				"Last Name",
				"Age",
				"City",
				"State",
				"1 Mile",
				"2 Mile",
				"Finish"
			],
			"column_data_type" : [
				"uint",
				"uint",
				"string",
				"string",
				"int",
				"string",
				"string",
				"time",
				"time",
				"time"
			],
			"column_notification_placeholders": [
				"[PLACE]",
				"[FIRST_NAME]",
				"[LAST_NAME]",
				null,
				null,
				null,
				null,
				null,
				null,
				"[CLOCK_TIME]"
			],
			"contains_split_time": [
				false,
				false,
				false,
				false,
				false,
				false,
				false,
				true,
				true,
				false
			],
			"row_unique_ids" : [ 8, 22, 11, 47 ],
			"row_registration_ids" : [ 111111, 222222, 333333, 444444 ],
			"rows" :
			[
				[ 1, 14, "Paul", "Winters", "43", "Mount Morrow", "NY", "5:02", "5:03", "1:07:20" ],
				[ 2, 17, "Andrew", "Olson", "43", "Westtown", "NY", "5:03", "5:04", "1:09:27" ],
				[ 3, 28, "John", "Smith", "44", "Carbondale", "PA", "5:04", "5:05", "1:13:24" ],
				[ 4, 35, "Bob", "Kellogg", "45", "", "", "5:05", "5:06", "1:15:47" ]
			],
			"finish_line_videos": [
				{
					"column_num": 9,
					"youtube_video_id": "zt31LvWz2QI",
					"play_start_padding_sec": 5,
					"start_clock_time": "1:05:00",
					"end_clock_time": "1:15:05",
					"start_clock_time_video_offset": "0:10"
				}
			]
		}
	]
}

You can update an existing custom page by specifying the same year and id in the metadata AND setting the update metadata to true. You MUST include all segments, although empty segments "{}" are allowed if not updates are required. However, you can add additional segments. Any existing rows in a segment with an id found in row_unique_ids array will be updated. Rows without a matching id will be appended to the bottom of the list of rows. Missing metadata, headers, and column definitions will remain unchanged. You cannot change the column order or add/remove columns, but you can update the column text.

If you want to clear all rows from every segment, you can set the clear_results metadata to true. You cannot use this with final_row_indices or delete_last_num_rows. The preferred option is to use the incremental update approach explained next.

You can update the row order using final_row_indices. This should be an object indicating the new row index (starting at zero) for any rows that has MOVED UP from it's original position. Any new rows are appending to the end of the list in the order received, so keep that in mind when calculating final_row_indices. Below is an example of this calculation.

CURRENT ORDER AFTER INSERTS          DESIRED ORDER
---------------------------          ---------------------------
Row Index    Unique ID               Row Index    Unique ID
0            000                     0            000
1            111                     1            444
2            222                     2            333
3            333                     3            111
4            444                     4            222

Build a working list from the current order after inserts.

WORKING LIST                         DESIRED ORDER
---------------------------          ---------------------------
Row Index    Unique ID               Row Index    Unique ID
0            000                     0            000
1            111                     1            444
2            222                     2            333
3            333                     3            111
4            444                     4            222

Compare index 0 in the working list and desired order.
They are the same, so nothing is added to final_row_indices.

Compare index 1 in the working list and desired order.
They differ, so set final_row_indices["444"] = 1.
Now update the working list by moving unique ID 444 up.

WORKING LIST                         DESIRED ORDER
---------------------------          ---------------------------
Row Index    Unique ID               Row Index    Unique ID
0            000                     0            000
1            444                     1            444
2            111                     2            333
3            222                     3            111
4            333                     4            222

Compare index 2 in the working list and desired order.
They differ, so set final_row_indices["333"] = 2.
Now update the working list by moving unique ID 333 up.

WORKING LIST                         DESIRED ORDER
---------------------------          ---------------------------
Row Index    Unique ID               Row Index    Unique ID
0            000                     0            000
1            444                     1            444
2            333                     2            333
3            111                     3            111
4            222                     4            222

Compare index 3 in the working list and desired order.
They are the same, so nothing is added to final_row_indices.

Compare index 4 in the working list and desired order.
They are the same, so nothing is added to final_row_indices.

We are done and final_row_indices = { "444": 1, "333": 2}.
	

By setting delete_last_num_rows to an integer X, you can delete the last X rows (after re-ordering) in the segment.

Update Example

{
 "metadata" :
	{
		"update": true,
		"id" : "@awards",
		"modified" : "2013-04-08 11:55:24",
		"year": 2013,
		"event_date": "2013-06-15"
	},
	"segments" :
	[
		{},
		{
			"row_unique_ids" : [ 81, 123 ],
			"rows" :
			[
				[ 1, "Karen", "Oats", "56", "New York", "NY", "6:00", "6:01", "1:04:37" ],
				[ 2, "Sarah", "Smith", "34", "New York", "NY", "6:10", "6:11", "1:06:19" ]
			]
		},
		{},
		{
			"header" : [ "MALE AGES  40 - 49" ],
			"columns" :
			[
				"Gender Place",
				"Overall Place",
				"First Name",
				"Last Name",
				"Age",
				"City",
				"State",
				"1 Mile",
				"2 Mile",
				"Finish Time"
			],
			"column_data_type" : [
				"uint",
				"uint",
				"string",
				"string",
				"int",
				"string",
				"string",
				"time",
				"time",
				"time"
			],
			"row_unique_ids" : [ 145, 192, 47 ],
			"final_row_indices": { "145": 3, "192": 4 },
			"delete_last_num_rows": 0,
			"rows" :
			[
				[ 4, 14, "John", "Paul", "42", "Mount Morrow", "NY", "5:04", "5:03", "1:15:17" ],
				[ 5, 17, "Kevin", "Burke", "47", "Westtown", "NY", "5:04", "5:06", "1:15:27" ],
				[ 6, 35, "Bob", "Kellogg", "45", "5:05", "5:06", "1:15:47" ]
			]
		}
	]
}

URL

https://runsignup.com/rest/race/:race_id/custom-results

HTTP Method

POST

Standard Parameters

Parameter HTTP Method Default Description Datatype
api_key GET API Key string
api_secret GET API Secret string
tmp_key GET Temporary API Key from login API call. This should NOT be used in combination with API Key. string
tmp_secret GET Temporary API Secret from login API call. This should NOT be used in combination with API Secret. string
format GET xml Format of response. format

Parameters

Parameter HTTP Method Default Description Datatype
race_id
Required
POST Id of race. uint
year
Required
POST Year that the results are for. int
request
Required
POST JSON of custom results data. string

Try It Now!

E-Mail
From Our Blog:
Nov 24th, 2017
2017 Thanksgiving Registration Stats

We are very thankful for all of the race directors, timers, partners, and runners who used RunSignUp yesterday. We are also thankful that our self-serve technology worked so well (and that we didn’t have too many support calls!). At RunSignUp, we always want to share our data on the trends and drivers of registrations to … Continue reading "2017 Thanksgiving Registration Stats"

Nov 22nd, 2017
Charity Payments Bug

We discovered a small bug in our software that has affected races using Braintree Marketplace for payment, who also have Charities setup to get paid directly, where the Charity is paying the processing fee. This affected: 19 races out of the 29,000 races held since this bug was introduced 460 Transactions out of the 5,376,000 … Continue reading "Charity Payments Bug"