Want to build technology using data from Voost? We encourage it! Here are instructions for using our public API.
Note: This API is “beta” and may still change.
If you use this API, we strongly recommend that you join the Voost API mailing list. We post announcements of new features and potential changes here. It’s also a great place to ask questions.
This API is being developed on-demand. Want something more? Contact us.
Using the API
Making requests
All API endpoints are HTTP REST calls which return JSON. The base for all endpoints is https://api.voo.st/
. All requests require SSL.
You must include a parameter [email protected]
with all requests. This is so that we can contact you in case there are problems with your usage or need to make breaking changes to the API.
Responses
A successful response will return HTTP status code 200 and JSON structured like this:
{ "result" : /* Specific results vary depending on the call */ }
If an error occurs, you will receive a HTTP status code of 500 and JSON structured like this:
{ "error" : { "message" : "No entity was found matching the key: Key<?>(Event(123))", "type" : "NotFoundException", "types" : ["NotFoundException"] } }
This particular error shows a request for an event with an invalid shortKey/id. The message is intended to help the programmer but is not suitable for display to end-users. Message content may change arbitrarily over time; do not match directly on the text. Instead, use the type
to identify the specific problem. types
may hold multiple values in the case of errors that can be generalized; type
will always be the most specific value in types
.
A quick word about keys
At various times in this API you may see properties called key
and shortKey
. Internally, Voost uniquely identifies every object by a key
which looks something like aghzfnZvb3N0MHIKCxIDT3JnGME-DA
. However, we prefer human-readable URLs so you will often find a shortened version called a shortKey
. For example, https://www.voo.st/event/1-Time-Trial-By-Fire shows a shortKey
of 1
. Both keys and shortKeys are strings (not integers).
Events
Public Event Information
This method retrieves the public information about an event. For example, to obtain the information for the event at:
https://www.voo.st/event/1-Time-Trial-By-Fire
GET this url:
https://api.voo.st/event/[email protected]
Note that 1
is the shortKey
of the event.
Click on the link above and view the results. We recommend the JSONView extension for Chrome and Firefox to make the result readable.
Some things to note:
- Objects are polymorphic. For example, the properties for a
UsacRace
may be different than the properties for aMerchandise
. - The event type hierarchy is:
CyclingEvent
GenericCyclingEvent
UsacEvent
- The product group type hierarchy is:
RegistrationGroup
GenericRegistrationGroup
UsacRaceGroup
MerchandiseGroup
UsacLicenseGroup
- The product type hierarchy is:
Registration
GenericRegistration
UsacRace
Merchandise
UsacOneDayLicense
- Some fields are optional. For example, Products without field limits will have
limit
of null. registrationOpens
is an ISO-8601 date/time string relative to the local timezone of the event.registrationOpensAt
is a milliseconds-since-epoch instant in time, suitable for conversion into a javascript Date object. Be aware of timezone issues when working with these two formats.