The basics of our API are included on the Documentation page. There is a section at the bottom entitled “Results Posting”. This gives a quick overview of how results work, but this guide goes into a bit more detail. The API Methods page lists all of our API methods. We have some example PHP scripts at https://github.com/RunSignUp-Team/OpenSource/tree/master/RunSignUpApiExamples.
The first thing you need to do is get access to the API. There are various ways to access the API. There are permanent keys for affiliates, partners, and timers. Secondly, there is a login API that returns temporary credentials, but that API is deprecated and may be removed in the future. The third and preferred option is OAuth 1.0 authentication.
Next, you'll want to get the list of races using the Races API. There are search parameters you can set, the most important being start_date, which defaults to the current date. Each race has a list of events (e.g. Fun Run, 5K, etc). This API only returns the most recent set of events. If you want all events for a particular race, you can use the Race API to get that specific race.
Once you have an event, you can use the Participants API to download participants (in pages). You will probably find the after_registration_id parameter useful for downloading new registrations since the last download.
Now for the actual results part. The results are linked to a specific event in the race. Each event can have any number of result sets. You might want to create a result set called “Live Results” or “Overall Results”. The API to create a new result set is here. The results source parameters lets you fill in a name and URL that will show up as a link on the results page. You might use this to link to your website or allow timers using your software to customize it to link to their site.
Finally, you can start posting results using the Results API. You can post as CSV, JSON, or XML. You can also get the response as CSV, JSON, or XML, but you should stay away from CSV here since it cannot provide as detailed of an error message. The recommended information to post includes registration_id, place, and clock_time at a minimum. We will match the registration id and fill in all the user information. We also match on bib or chip number, but since they may not be set up in RunSignup, it is safer to use registration_id.
That's the basics of posting results. You can use it for real-time results by just posting a few results at a time. There are more advanced features you can implement too. You can set up splits such as mile times, triathlon splits, etc. You can also set up race divisions such as age groups, clydesdale, etc. You can either let us automatically figure out division placement or you can post them. Lastly, you can create custom fields, which lets you post basically any other data that you want. If you need more details on any of these, take a look at the API Methods page and feel free to contact us with any questions.
