parkrun API early access

By Richard Leyton, parkrun systems engineer
— Thursday 5 September 2013

We're pleased to announce that we're taking applications to join the early access programme for the forthcoming parkrun API.

We would like to invite individuals or organisations interested in getting involved to complete this enquiry/proposal form, with a view to access for the successful applicants towards the end of September.

We'd expect this to be primarily of interest to:

  • Technically minded parkrunners who have innovative and interesting ideas for how we can add value and new services for the parkrunner, who don't mind a few rough edges or things changing without (much) warning.
  • Companies or organisations that feel they could add value to the parkrun data in some way.

A few important notes and caveats

  • This is not an open API. We take the privacy and preferences of our participants very seriously (see also, so in the first instance you should only expect to access your own data, and general summary data. We'll be limiting how many calls can be made in the early days.
  • We'll expect you to agree to some additional, tbc but vanilla terms and conditions, for this sort of thing.
  • Our date estimates are precisely that - estimates. They're subject to change. They should be liberally salted.
  • We need to emphasise up front we can't work with everybody who applies. Probably no more than 3 or 4 proposals. Even proposals that come through will have to sit at the back of the line. We're a tiny team, with a lot going on, and lots of work to do developing the API for our own scoped needs and partners.
  • We're looking for novel, intriguing or genuinely striking ideas - different from what we've already done or currently have planned. Please think differently. Think about adding value or slicing and dicing data in interesting ways.
  • In the early stages we'd like to work with developers who're able to spend time working with us. Over time we might relax this for some services (eg. meta information about our events; cancellations etc), but not initially.
  • Please consider deployment. We get a lot of traffic, particularly on Saturday's. There will be a lot of interest in new features. So if it passes muster we'll probably look to incorporate it into our environment in some way (with your agreement, and full credit). We've a model in mind for wider deployment models, but that's further down the line.
  • Even if you're accepted, please appreciate we might discover we're unable to continue or need to defer the proposal.

We expect the nature of the programme to evolve over time. We need to be strict early on so we can tackle the most important challenges first, and ensure our existing services work as expected with the new platform.

The shape of the API

We're still getting our documentation in shape. A few outline bits of info which might help you as you think things through:

  • It's a RESTful API
  • HTTPS only
  • JSON and XML formats
  • OAuth2
  • Is primarily read-only just now
  • paginated result sets
  • Has intuitively chainable resources for athletes, clubs, countries, events, geolocations, results, runs and volunteers
  • Others planned.
  • Rate limited for early-access candidates
  • Swagger documentation available.

In short, it's hopefully intuitive, easy to use and flexible.

Where we are

We're building the API to be useful to ourselves, and our partners. We're dogfooding just now - for example we're reworking how results updates appear on the website so they appear more promptly, and also pushing result update notifications to our Hipchat system. Once that's settled we'll open this sort of information to event teams so they can see what's actually happening on Saturday.

The main thing we're still to do is finalise the object structure. This is one of the main goals from the early access programme. It's good for our own use just now, but there are other considerations we want to factor in before we finalise it and open things up more widely.

A personal note

Ever since getting involved with parkrun in 2007, and as an Event Director since 2008, I've been interested and excited about the technical possibilities. I genuinely hope the API we're working on here will open up a whole new avenue to the parkrun experience, for parkrunners, organising teams, and all the geeks out there who I know have been itching for more detail. I want this to be done right, to follow best practices, and maybe cut some new ground too.

But we've obligations too: to the parkrunner, to protect their data; to our partners to deliver what we've agreed to; and to ourselves, to not overcommit what we can reasonably support.

The API opens up a huge realm of possibilities, and challenges. I've ideas of my own for things we'd like to see (and not see), and one or two things we're already planning to do ourselves (resources permitting), and I'm looking forward to sharing with you. But please bear with us whilst we work through this. It's a major change for us, and we've a lot to learn. We're bound to make some mistakes along the way.

So your patience appreciated, but really hope lots of you will be in touch with some fantastic ideas.

Thanks and look forward to hearing from you soon,

Richard Leyton
Systems Architect, UKTT
Twitter @rleyton

Here's the early access form URL:

Showing 21 to 30 of 102 entries