Documentation The Livelox public API

The Livelox public API

We provide a public REST API for application developers that want to integrate their applications with Livelox. To request API access, send an email to info@livelox.com. Provide a brief description of your application, why you would like to integrate it with Livelox, and the preferred access method (API key or user delegation). Make sure that the application's usage of the API complies with the API terms and conditions section below.

API terms and conditions

  • Applications should be intended for public use and not compete with Livelox.
  • API keys must be kept secret and should therefore not be embedded in end-user applications (e.g. mobile apps or client-side scripts).
  • We have sole discretion over the decision to approve or disapprove API access requests.
  • We do not provide API access for personal use.
  • Please use the API responsibly. Do not send an excessive number of requests. Cache data on your side when possible.
  • We reserve the right to suspend applications not adhering to these rules without prior notice.

Authorization

There are two ways to access the API.

  • Authorization through API key
  • Authorization through user delegation

Accessing the API through an API key

Your application's API key should be included as an ApiKey HTTP header with each request. Make sure to use your unique API key instead of the example API key below.

ApiKey: 559FCA56B17E48DDB971DEEF1E90C8F2

Accessing the API through user delegation

For end-user applications, authorization to access the API should be given by the users rather than by using an API key. The OAuth2 protocol is used, applying the Authorization Code with PKCE Flow. This means that users will experience a one-time redirection to the Livelox website, where they allow your application to access Livelox on their behalf.

OAuth2 endpoints

Authorization endpoint: https://api.livelox.com/oauth2/authorize
Token endpoint: https://api.livelox.com/oauth2/token
Token revocation endpoint: https://api.livelox.com/oauth2/revoke
User info endpoint: https://api.livelox.com/oauth2/userinfo

Scopes

events.import - lets the application import course setting information to Livelox events on behalf of a user

Token life lengths

Authorization codes are valid for 10 minutes. Access tokens are valid for 24 hours. Refresh tokens do not expire. Users can revoke tokens or change scopes in their Livelox account settings.

For further information regarding OAuth2, check out these resources:

Bidirectional event integration

Livelox can be integrated with event management systems and entry/result web portals. Those systems provide event information such as classes, courses, start lists and result lists to Livelox, which in turn provides URLs to the Livelox viewer for the classes in the event. It is possible to make a fully-featured bidirectional automatic integration, like the Eventor event management system, but also simpler ones where only part of the event information is exchanged. Learn more about event integration.

API endpoints

GET https://api.livelox.com/events

Returns events in Livelox in JSON format.

Querystring parameters

All parameters are optional.

Name Type Description
from datetime, yyyy-mm-ddThh:mm:ssZ The start of the time interval in UTC to search within.
to datetime, yyyy-mm-ddThh:mm:ssZ The end of the time interval in UTC to search within. The time interval is considered to end immediately before this time.
q string A string used to search for event names or event organisers.
modifiedSince datetime, yyyy-mm-ddThh:mm:ssZ Returns only events that were modified later than this UTC time.
latitude number The latitude of a circle center point to search within. Used together with longitude and radius.
longitude number The longitude of a circle center point to search within. Used together with latitude and radius.
radius number The radius in meters to search within. Used together with latitude and longitude.
south number The latitude of the south edge of a bounding box to search within. Used together with north, west and east.
north number The latitude of the north edge of a bounding box to search within. Used together with south, west and east.
west number The longitude of the west edge of a bounding box to search within. Used together with south, north and east.
east number The longitude of the east edge of a bounding box to search within. Used together with south, north and west.
countryId integer/string The ID of the country where the event is organised. You can use either Livelox's internal country IDs or ISO 3166-1 alpha-3 codes. For a list of country IDs, see the endpoint GET https://api.livelox.com/countries.
onlySearchable boolean Filters the result to only include the events that have been marked as searchable from the Livelox start page. Events without valid map and class course connections are considered non-searchable. Defaults to false.
onlyHavingValidMapAndCourses boolean Filters the result to only include the events that contain a map and courses. Defaults to false.
includeClasses bool Whether to include the event's classes in the response. Defaults to true.
includeProperties bool Whether to include the event's key-value properties in the response. Defaults to true.
cultureCode string Returns culture-specific values (e.g. country names) in this language. Defaults to en-US.
sorting string, property:order Sorts the result. property is one of time (start time of event; default), duration (length of event's time interval), distance (distance from geo search parameters), participantcount; order is the sorting order, ascending (default) or descending. Example: time:descending will list the most recent event first.
paging string, index:size Paginates the result. index is the zero-based page index; size is the number of search results per page. Example: 1:20 will return search results 21-40.

GET https://api.livelox.com/event/{eventId}

Returns details about a specific event in Livelox in JSON format.

Path parameters

Name Type Description
eventId integer The ID of the event.

Querystring parameters

All parameters are optional.

Name Type Description
includeClasses bool Whether to include the event's classes in the response. Defaults to true.
includeProperties bool Whether to include the event's key-value properties in the response. Defaults to true.
cultureCode datetime, yyyy-mm-ddThh:mm:ssZ Returns culture-specific values (e.g. country names) in this language. Defaults to en-US.

GET https://api.livelox.com/orienteering/courses/iofxml

Returns information about the courses for an event in IOF XML format. Information that is not yet public is not returned.

Querystring parameters

Name Type Description
eventId integer The ID of the event. Required.
projectionEpsgCode integer The code of the EPSG projection that the control coordinates should be expressed in. Omit to use WGS84.
includeControls boolean Whether to include controls for the courses or not.
includeClassConnections boolean Whether to include class connections (i.e. a number of IDs for classes) for the courses or not. Set includeClasses to true to also include class sub objects.
includeClasses boolean Whether to include classes for the courses or not.

GET https://api.livelox.com/countries

Returns all countries present in Livelox in JSON format.

Querystring parameters

Name Type Description
cultureCode string The language that country names should be presented in. Defaults to en-US.
onlyHavingEvents boolean Whether to return only countries that have at least one event related to it.