Biketerra API

Last updated

Biketerra has a simple JSON API you can use to pull your activities, events, race results, and profile data into your own tools and scripts.

Getting your API key

  1. Go to Settings → Profile.
  2. At the bottom, click the Show advanced settings button
  3. Scroll to the API key row and click Generate.
  4. Copy the key somewhere safe.

You can regenerate the key at any time from the same place. Regenerating invalidates your old key immediately, so any scripts using it will need the new one.

The basics

All requests go to:

https://api.biketerra.com/{endpoint}

Authenticate by sending your key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" "https://api.biketerra.com/activity/list"

Parameters can be sent as query string values, or as a JSON body via POST. Both of these are equivalent:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/activity/get?id=12345"

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"id": 12345}' \
  "https://api.biketerra.com/activity/get"

Every response is JSON with the same shape. ok tells you whether the call succeeded, and msg holds the data (or an error code):

{ "ok": true, "msg": { ... } }

{ "ok": false, "msg": "no_access" }

Pagination

List endpoints are paginated. Use paged for the page number (starting at 1) and per_page for the page size (default 12). Paginated responses include a pager object:

{
  "results": [ ... ],
  "pager": { "page": 1, "per_page": 12, "total_rows": 87, "total_pages": 8 }
}

Common endpoints

List your activities

activity/list returns your activities, newest first. It defaults to your own account, so no ID is needed. You can also pass athlete_id to view another athlete (if their activities are visible to you) and keywords to filter by title.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/activity/list?per_page=50&paged=1"

Each result includes distance (meters), duration (seconds), elevation gain, and when it was ridden.

Get a single activity

activity/get returns one activity by ID, including who rode it and its cheer count.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/activity/get?id=12345"

List events

event/list returns ongoing and upcoming events by default. Narrow it down with when (upcoming, ongoing, or ended), type (race covers races, team time trials, and individual time trials), and keywords. It's paginated like the other list endpoints.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/event/list?when=upcoming&type=race"

Each result includes the event's start time, duration, and the route it runs on.

Get race results

event/get_results returns the finish times for an event. Event IDs come from event/list or from the event's URL on the site.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/event/get_results?id=901"

The response includes the event summary (with a has_ended flag) and a results array sorted fastest first. Each entry has the rider's name, gender, age category, threshold w/kg, and their time in milliseconds. For team time trials, results are grouped by team instead, with each team's riders and whether the attempt was official (three or more finishers).

Event lists and results are public, so these two calls also work without an API key.

Get an athlete profile

athlete/get returns a public profile: name, trophies, team, clubs, and follower counts. Your own athlete ID is in your profile URL (biketerra.com/athletes/{id}).

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.biketerra.com/athlete/get?id=678"

A complete example

Fetch your 10 most recent activities and print a summary with JavaScript:

const resp = await fetch('https://api.biketerra.com/activity/list?per_page=10', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' },
});

const { ok, msg } = await resp.json();

if (ok) {
    for (const activity of msg.results) {
        const km = (activity.distance / 1000).toFixed(1);
        console.log(`${activity.title}: ${km} km on ${activity.route_title}`);
    }
}

Good to know

  • Keep your API key private. Anyone who has it can read and write data on your account.
  • Error responses return HTTP 400 with an error code in msg (for example no_id, no_access, or not_found).
  • If a request returns { "ok": false, "msg": "no_token" }, your key is missing or invalid. Regenerate it from Settings → Profile.