Documentação A API pública do Livelox

A API pública do Livelox

No Livelox, fornecemos uma REST API pública para desenvolvedores de aplicações que queiram integrar o Livelox nas suas aplicações.

Por favor, utilize a API de forma responsável. Não partilhe a sua chave API com outros. Não inclua a sua chave API em aplicações utilizadas diretamente pelos clientes (ex. apps móveis); guarde-a de forma segura no seu backend ou utilize uma autenticação baseada em OAuth2. Não faça um número excessivo de pedidos. Guarde dados em cache do seu lado sempre que possível. Reservamos o direito de suspender, sem aviso, utilizadores da nossa API que não respeitem estas regras.

Autorização

Existem duas formas de aceder à API.

  • Autorização por chave API
  • Autorização por atribuição a um utilizador

Acesso à API através de uma chave API

A chave API da sua aplicação deve ser incluída no cabeçalho do HTTP com o tipo ApiKey em todos os pedidos. Certifique-se que utiliza a sua chave API única e não a do exemplo abaixo.

ApiKey: 559FCA56B17E48DDB971DEEF1E90C8F2

Para obter uma chave API, por favor contacte info@livelox.com. Faça uma pequena descrição da sua aplicação e indique o porquê de querer integrar o Livelox. A chave API deve ser mantida secreta e, por essa razão, não deve ser descriminada em aplicações de frontend (ex. apps móveis).

Acesso à API por atribuição a um utilizador

Para aplicações de frontend, a autorização para aceder à API deve ser fornecida pelos utilizadores e não através de uma chave API. É utilizado o protocolo OAuth2, aplicando o Código de Autorização com PKCE Flow. Isto significa que os utilizadores vão ter um encaminhamento inicial único para o website do Livelox, onde deverão autorizar a sua aplicação a aceder ao Livelox em seu nome. Por favor, contacte info@livelox.com para obter um client_id. Forneça o seu redirect URI (não deve ser http, se não fôr localhost), uma breve descrição da sua aplicação e o porquê de querer integrar o Livelox.

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 - permite à aplicação carregar informação sobre o traçamento dos percursos para eventos do Livelox em nome de um utilizador

Tempo de vida dos Tokens

Os códigos de autorização são válidos por 10 minutos. Os tokens de acesso são válidos por 24 horas. 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.
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.