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.

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
        }
    }
    ]
}

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

If the consumer will not follow the usage limits, the account will be first throttled for a moment and denied access to the resources. If, despite being cautioned by Firstbeat, API consumer continues to disuse the API in ways that stress the service excessively Firstbeat reserves the right to disable the consumer access permanently.

Currently, API consumer-specific limits are as follows and should be honored:

• 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 is appended to the returned JSON data, you may request the next set of data by providing a query parameter ?offset=OFFSET_NUMBER to the request, to get the next set of data. OFFSET_NUMBER = The amount of already fetched documents. For example 1000.

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

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

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 vectors: Values from each respective moment of the measurement period. For example [115,115,117,124,...].

Time series vectors 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 always use the query parameter list to get the data in an uncompressed format. If possible, please prefer uncompressing the data on the client side.

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 ¹⁾ need to be explicitly requested from the /results endpoints due to their data-heavy nature. To request them, use the ?var= query parameter.

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