HOW TO ACCESS RACE DATA VIA JSON API

Introduction
 
This enables you to easily create your own web page using race data from the Webscorer website.
You can obtain the following in JSON format:

- You get access to the results, start list and registration data posted to your Webscorer account
- You will also be able to access data for races posted by others by specifying the correct “raceid”
- The raceid is the set of digits at the end of the posted results URL
- If the raceid is 255350 and your JSON API Is 86255, here’s the JSON URL for a results page:

 https://www.webscorer.com/json/race?raceid=255350&apiid=86255
 
Your JSON API ID
 
Each request to get JSON data requires your JSON API ID to be passed as a query parameter.
 
To find your JSON API ID:
 
- Navigate to Organizers / My organizer settings
- Find the item labelled "Unique organizer URL”
- Your ID is the digits at the end of the URL
- In this example, the JSON API ID is 86255
 

 
Using your JSON API ID
 
- Each request for JSON data uses a standard GET with a URL
- One of the supplied query parameters must be "apiid=n" where n is your JSON API ID
- For example, for results raceid=255350 and JSON API ID=86255, the JSON URL is
 
Getting the list of posted results
 
To get a list of your posted results use


Where n after apiid= is replaced with your API ID
 
This will return JSON data including:
- "OrganizerInfo"
    - This includes "OrganizerPage" which is the URL of your public page on Webscorer
- "ResultList"
    - This is an array of objects - one per result
    - Each result object includes
      - RaceId, Name, Date, Sport, DisplayURL
      - the Display URL links to the page on Webscorer website.
 
Getting results data
 
To get results data for a specific race, use:
 
To get the taps recorded data for a specific race, use:

https://www.webscorer.com/json/fasttaps?raceid=r&apiid=n

Where n after apiid= is replaced with your JSON API ID
Where r after raceid= is replaced with the raceId
 
This will return JSON data including:
 
RaceInfo
- This includes RaceId, Name, Date, Sport, DisplayURL
- Many other results properties similar to what is shown on the Webscorer results page
- To get access to the "private" fields (email & info 1 - Info 5), add &apipriv=1 as follows:

 
Results
- This is an array of objects
- The number of objects depends on whether the result uses distances, categories, or gender grouping
- Each object has "Grouping" and "Racers"
  - The "Grouping" object includes information about the grouping of racers
  - This may include "Distance", "Category", "Gender"
 
Notes:
 
- For races with multiple distances that have results for all categories
- "Overall": true may be included to indicate the grouping includes multiple categories
- For races with laps and multiple distances, the "LapCount" will also be included
- The "Racers" object is an array of racer objects - one per racer in this grouping
- Each racer object may include "Place", "Bib", "Name", "Time", "LapTimes"
- The exact set of properties per racer varies depending on the race settings
- It is a reflection of what is shown on the Webscorer results pages

Getting the list of start lists or registration lists

To get a list of your posted start lists and registrations use

https://www.webscorer.com/json/mystartlists?apiid=n

Where n after apiid= is replaced with your API ID

 This will return JSON data including:
      - "OrganizerInfo"
- This includes "OrganizerPage" which is the URL of your public page on Webscorer
      - "StartLists"
- This is an array of objects - one per start list or registration
      - Each start list object includes
      - RaceId, Name, Date, Sport, DisplayURL, Public (true or false), Type (Start list or Registration)
      - the Display URL links to the page on Webscorer website.

To filter the list to return only Start lists use

https://www.webscorer.com/json/mystartlists?apiid=n&filt=S 

To filter the list to return only Registrations use

https://www.webscorer.com/json/mystartlists?apiid=n&filt=R

Getting start list or registration list data

To get the data for a specific start list or confirmation list for a registration use

https://www.webscorer.com/json/startlist?raceid=r&apiid=n

https://www.webscorer.com/json/registerlist?raceid=r&apiid=n

Where n after apiid= is replaced with your JSON API ID
Where r after raceid= is replaced with the raceId 

This will return JSON data including:

RaceInfo

- This includes RaceId, Name, Date, Sport, DisplayURL
- Many other properties similar to what is shown on the Webscorer start list page 

StartList

- This is an array of objects
- The number of objects depends on number of racers in the start list
- Each racer object may include "Bib", "Name", “Distance”, “Category”, etc
- The exact set of properties per racer varies depending on the start list or registration settings
- It is a reflection of what is shown on the Webscorer start list pages

Getting data from a results series

The JSON URL for a results series is as follows:

 
Where n after apiid= is replaced with your JSON API ID
Where r after seriesid= is replaced with the seriesid
 
This will return JSON data including:
 
SeriesInfo
- This includes SeriesId, Name, Date, Sport, DisplayURL
- Many other series results properties similar to what is shown on the Webscorer results page
 
Results
- This is an array of objects
- The number of objects depends on whether the series uses distances, categories, or gender grouping
- Each object has "Grouping" and "Racers"
  - The "Grouping" object includes information about the grouping of racers
  - This may include "Distance", "Category", "Gender"
- The "Racers" object is an array of racer objects - one per racer in this grouping
- Each racer object may include "Place", "Name", "RacesCounted", "TotalPoints", and "Races"
The "Races" property is an array of objects with one entry for each race that is included in the series for this racer
 
Errors
 
- If the request cannot return JSON for some reason, then an error JSON is returned instead 
- This is a simple object with a property "Error" that contains a message with the reason for the error
- Example:
  { "Error": “PRO Results subscription required to use this API has expired" }
  
How to view JSON for any results page
 
To see the JSON that matches the results page posted on Webscorer:
 
- Use any browser to navigate to the results page, e.g. https://www.webscorer.com/race?raceid=255350
- Edit the page URL on the address bar as follows:
  - Insert json/ after webscorer.com/
  - Add &apiid=n at the end where n is your JSON API ID
- For example if your JSON API ID is 86255, you’d enter this URL to get the JSON
  https://www.webscorer.com/json/race?raceid=255350&apiid=86255
 
Formatting notes
 
- The JSON returned is not formatted to be easily read
- There are online tools that will format JSON to make it easier to read
- For example: navigate to https://formatjson.com/ and copy the JSON to get proper formatting
 
Encoding notes
 
- If a URL contains the '&' character, it is encoded as \u0026
- If a race name contains a single quote, it is encoded as \u0027
- Note that this is not a complete list, just showing how the encoding is done

PRO subscription required

- To access the JSON data, the organizer's account must have a valid PRO Results subscription
- Note that this subscription is different / additional to the PRO timing subscription
- Link to subscription page: Purchase PRO Results subscription

Example JSON (on Webscorer.com & pasted to Formatjson.com):