Developers

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).

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 a Merchandise.
• 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.