This page contains documentation on how to access First Sports data via API.

Is API the right choice for me?

If you are unsure what the Sports API can do and how it works please contact sports-cloud-api@firstbeat.com. There are use cases that the API does not support and it is better to check your requirements with us.

Sports API is available for Sports Premium and Premium+ customers.

An alternative method for getting data out from Firstbeat Sports is the Data Export functionality in the Sports Cloud (premium feature).

Possible limitations to be aware of:

• Some automated tools might not work out of the box with the encoded and compressed query result data or are they are not able to generate the needed API tokens on the fly.
• The concepts used in your software might be different (measurement, session, etc.) and mapping of the query results might not be straightforward.
• All metrics in the Firstbeat Sports are not available via API. Please refer to this documentation for the list of available metrics.
• All metric names in the Sports API and Cloud Data export are not the same. Differences are listed in this document.

In case you have any questions about the Sports API please contact sports-cloud-api@firstbeat.com. For general Firstbeat Sports questions, please contact support@firstbeat.com.

We are happy to help you with any questions you might have.

It is possible to try the Sports API with a test account. After registering as an API user, you will also get access to a test account that you can use for development and testing purposes.

Test Account is a sandbox meant only for testing purposes.

The Firstbeat Sports Cloud API uses URL versioning, where the API version is included in the base URL.

https://api.firstbeat.com/v1/

One API version is officially supported at a time unless otherwise communicated. This means that bug fixes are made to the latest version while old versions might still be available for some time.

The following are breaking changes and will not change in the same API version:

• Removing or renaming an endpoint
• Removing or renaming a parameter
• Adding new required parameters
• Changing data format types
• Making a previously required response field optional

The following changes can be made on the same version:

• Adding an operation/endpoint
• Adding an optional parameter
• Adding a parameter that changes the response to new format. For example: results?responseformat=v2
• Adding an optional request header
• Adding a response field
• Adding a response header
• Adding or removing result variables, either scalars or time series

To get started, you need to register as a Sports API consumer. First, you need to select your API consumerName and then make an API request to account/register endpoint to create id and sharedSecret.

Your API consumerName can be at most 100 character long and must uniquely identify your team or organization so that it is not likely to be mistaken for some other entity. Your API consumerName will be visible in the Sports Cloud.

Base URI of the API is:

https://api.firstbeat.com/v1/

Example:

curl 'https://api.firstbeat.com/v1/account/register' \
    --data '{"consumerName": "your_api_consumer_name"}' 

On Windows command prompt you need a workaround for the single quotes:

curl -d "{"consumerName": "your_api_consumer_name"}" https://api.firstbeat.com/v1/account/register 

After a successful API call you should get a response similar to:

{ "id": "87a05c83-d5b7-46ba-aa4a-32f56cd284d5", "consumerName":"your_api_consumer_name", "sharedSecret":"8d5b6d12-61c5-4303-9ae3-c1837a15034b" }`

• The generated id field is the primary field used for identifying you as an API user.

• sharedSecret is used later for generating a token to access the API.

Please store your sharedSecret securely. You don't need to send the sharedSecret to Firstbeat Support.

After you have created your API consumer, please send the

• 1. consumerName,
• 2. id and
• 3. name(s) of the Firstbeat Sports customer account(s) you need access to

to sports-cloud-api@firstbeat.com. Please contact us using an email address that you have previously used to communicate with Firstbeat Sales or Customer Success Managers and include them as recipient in CC field of the email, if applicable.

After you have received an e-mail that your id has been approved by the Sports API staff you are ready to proceed to the next step.

Next, you need to grant the API consumer access to your Sports account data. This is done at Sports Cloud (https://sports.firstbeat.com).

If you don’t have access to Sports Cloud, please ask a person who owns the account to complete the steps below.

In Sports Cloud, do the following:

1. Click the settings menu on the top left corner of the screen. Go to the Cloud API section of the screen.

2. Read and accept the license agreement.

3. Select the API consumer from the list to grant access to account data (select the account checkbox).

4. Finally, save settings.

After the access has been approved, you can proceed to create JWT Tokens and adding an API Key.

The API token is needed for creating an API key and for making request to the Sports API.

Every Firstbeat Cloud API endpoint (except /register) will require authentication in the form of JWT Token (JSON Web Token) in the Authorization header.

The format for passing the token in headers is as follows:

Authorization Bearer xxxxxxxxxxxxxxxx.yyyyyyyyyyyyy.zzzzzzzzzzzzzzz

JWT Token is a standardized way of generating a token. Currently, Firstbeat Cloud API supports HMACSHA256 encoded JWT tokens, with a shared secret. The token must be valid for at the most five minutes after generation.

JWT Token format consists of three parts separated by a . (dot). The first part is the Base64 encoded header information, the second part is Base64 encoded Payload data and the last part is HMAC – encoded combination of HMACSHA256 encoding the headers, payload, and a shared secret text string.

For more information about JWT Tokens, check https://jwt.io/

You need your id and sharedSecret to create an API token.

Examples of how to create a JWT token are provided in the next chapter.

As a result, you should have a token generated. A token looks like this (your token will be unique).

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjMzhlMjU2ZC0xMWVlLTRmNWQtYWI0NS1iNjJkMDU3NGE3ZmQiLCJpYXQiOjE1ODg2NzQxNzYsImV4cCI6MTU4ODY3NDQ3Nn0.BQpPdmyM4KikNFIRisKdOkFRCADCA1bQpKUzBUWy3QA

Note: Token is valid only until the expiration you set for it, which can be at most five minutes from issuance. You can create a new token even for each time you invoke the API.

Exaples for Generating a JWT Token

Here are some examples with commonly used programming languages on how to generate a JWT Token with the help of some open source JWT libraries:

Java

Create a JWT token with Java (java-jwt):

import java.util.Date;
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

try {
Algorithm algorithm = Algorithm.HMAC256("YOUR_SHARED_SECRET");
Date now = new Date();
Date expires = new Date();
expires.setSeconds(expires.getSeconds() + 300);

String token = JWT.create()
    .withIssuer("YOUR_CONSUMER_ID")
    .withIssuedAt(now)
    .withExpiresAt(expires)
    .sign(algorithm);
} catch (UnsupportedEncodingException exception){
//UTF-8 encoding not supported
} catch (JWTCreationException exception){
//Invalid Signing configuration / Couldn't convert Claims.
}

Node.js / JavaScript

Create a JWT token with Node.js (jsonwebtoken):

'use strict';

const jwt = require('jsonwebtoken');
const SECRET = 'YOUR_SHARED_SECRET';
const issuedAt = Date.now() / 1000;
const payload = {
iss: 'YOUR_CONSUMER_ID',
iat: issuedAt,
exp: issuedAt + 300
};

// default algorithm (HMAC SHA256)

const token = jwt.sign(payload, SECRET);

Python

Create a JWT token with Python (pyJwt):

import jwt #pyjwt
import time

secret = 'YOUR_SHARED_SECRET'
now = int(time.time())
expires = now + 300

payload = {
    'iss': 'YOUR_CONSUMER_ID',
    'iat': now,
    'exp': expires
}

token = jwt.encode(payload, secret)

R script

Create a JWT token with R script (jose):

library(openssl)
library(jose)

id <- "YOUR_CONSUMER_ID"
sharedSecret <- "YOUR_SHARED_SECRET"

now <- as.numeric(Sys.time())
after_five_minutes <- now + 300

claim <- jwt_claim(iss = id, iat = now, exp = after_five_minutes)
secret <- charToRaw(sharedSecret)

token <- jwt_encode_hmac(claim, secret)

Next, create your API key using the account/api-key endpoint.

For this step, you need a valid API token you generated earlier. Please remember the five minute expiration period for the token. Generate a new token in case more than five minutes have passed.

You create an API key only once.

Example curl command:

curl 'https://api.firstbeat.com/v1/account/api-key' \
    --request GET \
    --header 'Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjMzhlMjU2ZC0xMWVlLTRmNWQtYWI0NS1iNjJkMDU3NGE3ZmQiLCJpYXQiOjE1ODg2NzQxNzYsImV4cCI6MTU4ODY3NDQ3Nn0.BQpPdmyM4KikNFIRisKdOkFRCADCA1bQpKUzBUWy3QB'

For this command, you make a GET request with a header “Bearer token” string.

If the request is successful, you get an API key as a response:

{"apikey":"cXvpCBUzG64orvHXA5taA2Et2hWGr6Gh1LqL90hx"}

Your API key doesn't change if you call the api-key end point again.

At this point:

1. You have registered as a Sports API user and your account has been approved by Firstbeat
2. You have granted your API consumer access to your Sports account data in the Sports Cloud
3. You have generated an API token to add an API key

Now you can access the Sports Cloud API.

Each API request needs to include an API key and a valid token in the header.

Example curl command to list accounts linked for your API consumer:

curl 'https://api.firstbeat.com/v1/sports/accounts' \
    --request GET \
    --header 'Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjMzhlMjU2ZC0xMWVlLTRmNWQtYWI0NS1iNjJkMDU3NGE3ZmQiLCJpYXQiOjE1ODg2NzQxNzYsImV4cCI6MTU4ODY3NDQ3Nn0.BQpPdmyM4KikNFIRisKdOkFRCADCA1bQpKUzBUWy3QA' \
    --header 'x-api-key: cXvpCBUzG64orvHXA5taA2Et2hWGr6Gh1LqL90hx'

Successful operation returns:

{
    "accounts": [
    {
        "accountId": "1-1",
        "name": "Some account",
        "authorizedBy": {
        "coachId": 0
        }
    }
    ]
}

You can swap the shared secret to a new value. You might do this if there is a chance that the value has leaked or as a regular process according to your policy. Start by invoking GET /account/new-secret using a JWT token generated using your current secret value. This will return a new value that is not yet valid for use. Generate a token using the new secret and invoke POST /account/new-secret/confirm with it. This will invalidate the previous secret value and replace it with the new value.

Please store the secret securely, never share it, and make sure you have the new secret stored before confirming it. If you lose access to the shared secret, Firstbeat API Support will advise making a new registration.

Each API consumer will have usage limits of how frequently it is allowed for the consumer to request Firstbeat Cloud API resources.

Currently, API consumer-specific limits are as follows:

• Max. 60 requests / minute
• Max. 5000 requests / day

Some endpoints are limited to 1000 results per request. To fetch more results, the API provides an attribute “more” with the results.

If “more: true” attribute appears in the returned JSON data, you may request the next page by providing query parameter ?offset=OFFSET_NUMBER to the request. OFFSET_NUMBER is the amount of already fetched records, for example 1000.

All returned time fields follow RFC3339 specification. Data is always returned in UTC time.

Measurements can be filtered by time, exercise type aka title, measurement type, sports or event type. Different filters can be combined in order to have better results.

Measurement type is a fundamental categorization that determines how Firstbeat Sports handles a particular measurement. Possible values are as follows.

Sessions can be filtered by time or type. Different filters can be combined in order to have better results.

Measurements and sessions can be categorized based on sports discipline and type of event. Possible values for these fields can be retrieved from endpoints https://api.firstbeat.com/v1/sports/sports-types and https://api.firstbeat.com/v1/sports/event-types respectively. They are also listed below.

Sports type indicates the sports discipline practised during the measurement. Possible values are

• football
• americanFootball
• rugbySevens
• rugbyUnion
• rugbyLeague
• fieldHockey
• iceHockey
• ringette
• baseball
• basketball
• futsal
• volleyball
• beachVolleyball
• floorball
• handball
• lacrosse
• softball
• gaelicFootball
• australianFootball
• cricket
• tennis
• badminton
• squash
• ultimate
• trailRunning
• running
• treadmillRunning
• orienteering
• strength
• cardio
• xcSkiing
• biathlon
• roadCycling
• indoorCycling
• mountainBiking
• bmx
• alpineSkiing
• swimming
• walking
• nordicWalking
• snowboarding
• rowing
• mountaineering
• hiking
• multisport
• triathlon
• golf
• inlineSkating
• climbing
• iceSkating
• taekwondo

Event type indicates what kind of event the measurement is from. Possible values are

• race
• game
• rehab
• recovery
• training

You can find full list of available result variables below. There are two types of variables:

1. Scalars: Single values calculated from the measurement. For example, 64.
2. Time series: Values from each respective moment of the measurement period. For example [115,115,117,124,...].

Time series are Base64 encoded and zlib compressed.

Here is a code example how to work with time series data in JavaScript.

import pako from 'pako';
import atob from 'atob';
const decompress = series => {
  const bytes = pako.inflate(
    new Uint8Array(
      atob(series.data)
        .split('')
        .map(x => x.charCodeAt(0))
    )
  );
  const buffer = new ArrayBuffer(bytes.length);
  const view = new DataView(buffer);
  bytes.forEach((b, i) => view.setUint8(i, b));
  const readValueFromByteArray = {
    Float: {
      64: (dataView, index) => dataView.getFloat64(index * 8),
      32: (dataView, index) => dataView.getFloat32(index * 4)
    },
    Unsigned: {
      16: (dataView, index) => dataView.getUint16(index * 2),
      8: (dataView, index) => dataView.getUint8(index)
    },
    Signed: {
      16: (dataView, index) => dataView.getInt16(index * 2)
    }
  };
  const result = [];
  for (let i = 0; i < bytes.length / (series.bits / 8); i++) {
    result[i] = readValueFromByteArray[series.type][series.bits](view, i);
  }
  return result;
};

You may also use the query parameter format=list to get the data in an uncompressed format. The binary format is default and recommended because the API is only able to return a response at largest 6 MB. With long measurements and large number series, it is possible to exceed that. If you receive status code 500 while querying analysis results, switch to format=binary or reduce the set of series requested in a single query.

For example: ...results?var=rmssd1MinSeries,vlfSeries,lfSeries,hfSeries&format=list

Last column of the table below shows the corresponding variable name in Sports Cloud data export (excel export). Note the differences in some variable names, for example training zone times.

Note: Names of the heart rate zone variables are different than in the rest of the system!

NOTE: TimeSeries variables marked with an ¹⁾ are not included by default in the response from /results endpoints due to their data-heavy nature. To request them, use the ?var= query parameter.

For example: .../results?var=trimpPerMinuteSeries,heartRatePercentageSeries