🧢 Coach T's Recap
Tracksuit's API lets you connect your brand data with other platforms and data sets. This can provide deeper insights into the relationship between brand health and business outcomes, empowering you to make more unified data-driven decisions across your organization.
The Tracksuit API helps you to connect Tracksuit data with other reporting tools (like PowerBI, Looker, or Tableau) or with other data sets (like sales data or media spend).
This documentation provides guidelines for integrating with our API using the authorization header as the authentication mechanism.
3-month rolling averages
All of the data presented matches what is displayed in the dashboard.
I.e. the data displays 3-month rolling averages which is the same as the Tracksuit dashboard. We do not provide daily, weekly or monthly data.
Accessible data
The first version of the API allows you to access all Funnel metrics across all date ranges, competitors, and demographic filters.
The API does not currently include: Statements, Profile, or Imagery data.
Authentication Flow
#1: Obtain API Key
To integrate with Tracksuit's API, you need to obtain an API key. Below are the steps to generate an API key.
Pre-requisite:
To be able to generate an API key, you must be an “Admin” on your account. This will enable you to see the “Account Settings” page.
Steps:
Click the cog icon (top right) → Account Settings
Go to Tokens → click Generate new token
Copy the token and use it as the API Key in the following steps
The API Token generated has a validation period of 365 days.
#2: Include Authorization Header
In every API request, include the Authorization header with the value set to Bearer YOUR_API_KEY. Replace YOUR_API_KEY with the actual API key you obtained in the first step.
Available APIs
The Tracksuit API is built in accordance with OpenAPI standards, ensuring a standardized and developer-friendly approach to API design and documentation.
The OpenAPI Documentation Link below provides a comprehensive guide to understanding and interacting with our API using the OpenAPI Specification. OpenAPI, formerly known as Swagger, is a standard for documenting RESTful APIs.
Server Base Path
Request and Responses are documented in the Open API documentation.
#1: Account brands
#1: Account brands
The /account-brands API endpoint allows you to fetch a list of account brands associated with a specific user account. This endpoint provides information about various brands that the user has access to within their account.
Example request
http
GET /funnel/filters?accountBrandId=123
Authorization: Bearer YOUR_ACCESS_TOKEN
#2: Funnel Filters
#2: Funnel Filters
The /funnel/filters API endpoint provides information about available demographic filters for a specific account_brand and includes details about the dates since when the data is available.
Request Parameters accountBrandId (integer, required): The unique identifier of the account brand which obtained using
/account-brandsendpoint.Note: the ‘TOTAL’ filter is used to get unfiltered results (e.g. the results unfiltered for any specific demographic).
Example request
http
GET /funnel/filters?accountBrandId=123
Authorization: Bearer YOUR_ACCESS_TOKEN
#3: Funnel Metrics
#3: Funnel Metrics
The /funnel API endpoint allows you to retrieve Funnel data based on specified query parameters, including the account_brand, demographic filter, and wave dates.
You should not have to perform any calculations to recreate the percentages shown on the dashboard. The percentages are already calculated and displayed in the Percentage output.
Request Parameters
accountBrandId(integer, required): The unique identifier of the account brand for which funnel data is requesteddemographicFilter(integer, required): The unique identifier of the demographic filter applied to the funnel data.Note: the ‘TOTAL’ filter is used to get unfiltered results (e.g. the results unfiltered for any specific demographic).
waveStartDate(string, required): The start date of the wave for which funnel data is requested (format: "YYYY-MM-DD"). It should be on of the dates retrieved from/funnel/filtersAPI.waveEndDate(string, required): The end date of the wave for which funnel data is requested (format: "YYYY-MM-DD").It should be on of the dates retrieved from/funnel/filtersAPI.
Results
Percentagegives the % for the relevant metric, wave date, and filter (e.g. X% awareness for a specific date and demographic filter)Filteris the demographic filter applied.Note: the ‘TOTAL’ filter is used to get unfiltered results (e.g. the results unfiltered for any specific demographic).
questionTypeshows the relevant funnel metrics (e.g. PROMPTED_AWARENESS).brandNameshows the brand that the metric is being calculated for.waveDateshows the month the metrics is being calculated for.Populationmultiplies the percentage (e.g. X% awareness) by the # of people in the category (taken from the /category-metrics endpoint) to get the estimated # of people aware of the brand.
Example Request
GET /funnel?accountBrandId=123&demographicFilter=TOTAL&waveStartDate=2023-11-01&waveEndDate=2024-01-01
Authorization: Bearer YOUR_ACCESS_TOKEN
#4: Category Penetration
#4: Category Penetration
The /category-metrics/{accountBrandID} API endpoint allows you to retrieve Category Penetration based on the specified path and query parameters, including the account_brand, demographic filter, and wave dates.
You should not have to perform any calculations to recreate the percentages shown on the dashboard. The percentages are already calculated and displayed in the Percentage output.
Request Parameters
accountBrandId(integer, required): The unique identifier of the account brand for which funnel data is requesteddemographicFilter(integer, required): The unique identifier of the demographic filter applied to the funnel data.waveStartDate(string, required): The start date of the wave for which funnel data is requested (format: "YYYY-MM-DD"). It should be on of the dates retrieved from/funnel/filtersAPI.waveEndDate(string, required): The end date of the wave for which funnel data is requested (format: "YYYY-MM-DD").It should be on of the dates retrieved from/funnel/filtersAPI.
Results
PercentagePercentage gives the category penetration percentage for a given month and demographic filter.Filteris the demographic filter applied.Note: the ‘TOTAL’ filter is used to get unfiltered results (e.g. the results unfiltered for any specific demographic).
waveDateshows the month the metrics is being calculated for.categorySizegives the current adult population figure we use for the geography (e.g. ~20m adults in Australia)filterPopulationgives the # of people in the category, which is calculated by multiplying the category penetration percentage by the adult population (categorySize).
Example request
http
GET /category-metrics/123&demographicFilter=TOTAL&waveStartDate=2023-11-01&waveEndDate=2024-01-01
Authorization: Bearer YOUR_ACCESS_TOKEN
Error Handling and Security
Error Handling and Security
Error Handling
In case of authentication failure or any other errors, the API will respond with appropriate HTTP status codes and error messages. Make sure to handle errors gracefully in your integration.
Common HTTP status codes:
401 Unauthorized: Invalid or missing API key.
403 Forbidden: Insufficient permissions to access the requested resource.
404 Not Found: The requested resource does not exist.
500 Internal Server Error: An unexpected server error occurred.
Security Considerations
Keep your API key secure: Treat your API key as sensitive information. Do not expose it in public repositories or share it openly.
Use HTTPS: Always make API requests over HTTPS to ensure the security of transmitted data.
Token Expiry: Every token expires after 365 days after generation. If a request fails due to an expired token, obtain a new token and retry the request.