API Endpoints

Overview Authentication GET /api/ranking GET /api/trials GET /api/routeStats

Vestigio API Documentation

RESTful API for accessing Vestigio route rankings and athlete data

v1.0 Base URL: https://vestigio.app

Overview

The Vestigio API provides programmatic access to route rankings, trial data, and athlete information. All endpoints return JSON responses and follow RESTful conventions.

Note: This API is currently in active development. Additional endpoints and features will be added over time.

Authentication

Currently, the API endpoints are publicly accessible. Future versions may require API keys or OAuth authentication.

Rate Limiting: Please use the API responsibly. Rate limits may be implemented in the future.

GET /api/ranking

Returns the complete ranking for a specific route, including all trial details and athlete information.

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The route GUID (not the numeric ID)

Request Example

GET /api/ranking?id=abc123-def456-ghi789

Response

Returns a JSON object with route information and an array of ranking entries.

Success Response (200 OK)

{
  "route": {
    "id": 1,
    "name": "Cerro San Cristóbal",
    "description": "Ruta desde Plaza Italia hasta la cumbre",
    "meters": 3500,
    "minutes": 45,
    "city": "Santiago",
    "country": "Chile",
    "guid": "abc123-def456-ghi789"
  },
  "ranking": [
    {
      "trialId": 123,
      "seconds": 1845,
      "timeFormatted": "00:30:45",
      "startMillis": 1704067200000,
      "endMillis": 1704069045000,
      "daysOld": 5,
      "valid": true,
      "suspicious": false,
      "discipline": "Running",
      "user": {
        "id": 45,
        "guid": "user-guid-123",
        "email": "athlete@example.com",
        "publicName": "John Doe",
        "alias": "SpeedRunner",
        "gender": 1,
        "age": 28,
        "city": "Santiago",
        "country": "Chile",
        "instagram": "@speedrunner"
      },
      "startLocation": {
        "id": 10,
        "name": "Plaza Italia",
        "latLong": "-33.4378,-70.6504",
        "city": "Santiago",
        "country": "Chile"
      },
      "endLocation": {
        "id": 11,
        "name": "Cerro San Cristóbal",
        "latLong": "-33.4245,-70.6389",
        "city": "Santiago",
        "country": "Chile"
      }
    }
  ]
}

Error Responses

400 Bad Request

Missing required parameter

{
  "error": "Missing routeId parameter"
}

404 Not Found

Route not found

{
  "error": "Route not found for id=abc123-def456-ghi789"
}

Response Schema

Root Object

route (object) - Route information
ranking (array) - Array of trial/ranking entries, sorted by time (fastest first)

Route Object

id (number) - Route numeric ID
name (string) - Route name
description (string) - Route description
meters (number) - Route distance in meters
minutes (number) - Estimated time in minutes
city (string) - City where route is located
country (string) - Country where route is located
guid (string) - Route unique identifier (use this for API calls)

Ranking Entry Object

trialId (number) - Trial ID
seconds (number) - Elapsed time in seconds
timeFormatted (string) - Formatted time (HH:MM:SS)
startMillis (number) - Start timestamp in milliseconds
endMillis (number) - End timestamp in milliseconds
daysOld (number) - Days since the trial was completed
valid (boolean) - Whether the trial is valid
suspicious (boolean) - Whether the trial is flagged as suspicious
discipline (string|null) - Discipline name (e.g., "Running", "Cycling")
user (object|null) - Athlete/user information
startLocation (object|null) - Start location details
endLocation (object|null) - End location details

User Object

id (number) - User numeric ID
guid (string) - User unique identifier
email (string) - User email address
publicName (string) - Public display name (alias or email prefix)
alias (string|null) - User alias/username
gender (number) - Gender (0 = female, 1 = male)
age (number) - User age
city (string|null) - User city
country (string|null) - User country
instagram (string|null) - Instagram handle

Location Object

id (number) - Location numeric ID
name (string) - Location name
latLong (string) - Coordinates in "lat,lng" format
city (string|null) - City
country (string|null) - Country

Notes

The ranking is sorted by time (fastest first)
Only trials from the last 10 years are included
Maximum of 1000 results are returned
Use the route guid (not the numeric id) in API calls
Timestamps are in milliseconds since Unix epoch

GET /api/trials

Returns the last 1000 trials for a specific user/athlete, including trial details and route information.

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The user/athlete GUID

Request Example

GET /api/trials?id=user-guid-123-456-789

Response

Returns a JSON object with user information and an array of their trials.

Success Response (200 OK)

{
  "user": {
    "id": 45,
    "guid": "user-guid-123-456-789",
    "email": "athlete@example.com",
    "publicName": "John Doe",
    "alias": "SpeedRunner",
    "gender": 1,
    "age": 28,
    "city": "Santiago",
    "country": "Chile",
    "instagram": "@speedrunner"
  },
  "trials": [
    {
      "trialId": 123,
      "seconds": 1845,
      "timeFormatted": "00:30:45",
      "startMillis": 1704067200000,
      "endMillis": 1704069045000,
      "daysOld": 5,
      "valid": true,
      "suspicious": false,
      "discipline": "Running",
      "comments": "Great run today!",
      "route": {
        "id": 1,
        "guid": "route-guid-abc-123",
        "name": "Cerro San Cristóbal",
        "description": "Ruta desde Plaza Italia hasta la cumbre",
        "meters": 3500,
        "minutes": 45,
        "city": "Santiago",
        "country": "Chile"
      },
      "startLocation": {
        "id": 10,
        "name": "Plaza Italia",
        "latLong": "-33.4378,-70.6504",
        "city": "Santiago",
        "country": "Chile"
      },
      "endLocation": {
        "id": 11,
        "name": "Cerro San Cristóbal",
        "latLong": "-33.4245,-70.6389",
        "city": "Santiago",
        "country": "Chile"
      }
    }
  ]
}

Error Responses

400 Bad Request

Missing required parameter

{
  "error": "Missing user id parameter"
}

404 Not Found

User not found

{
  "error": "User not found for id=user-guid-123-456-789"
}

Response Schema

Root Object

user (object) - User/athlete information
trials (array) - Array of trial entries, sorted by most recent first

User Object

id (number) - User numeric ID
guid (string) - User unique identifier
email (string) - User email address
publicName (string) - Public display name (alias or email prefix)
alias (string|null) - User alias/username
gender (number) - Gender (0 = female, 1 = male)
age (number) - User age
city (string|null) - User city
country (string|null) - User country
instagram (string|null) - Instagram handle

Trial Entry Object

trialId (number) - Trial ID
seconds (number) - Elapsed time in seconds
timeFormatted (string) - Formatted time (HH:MM:SS)
startMillis (number) - Start timestamp in milliseconds
endMillis (number) - End timestamp in milliseconds
daysOld (number) - Days since the trial was completed
valid (boolean) - Whether the trial is valid
suspicious (boolean) - Whether the trial is flagged as suspicious
discipline (string|null) - Discipline name (e.g., "Running", "Cycling")
comments (string|null) - User comments on the trial
route (object|null) - Route information
startLocation (object|null) - Start location details
endLocation (object|null) - End location details

Route Object

id (number) - Route numeric ID
guid (string) - Route unique identifier
name (string) - Route name
description (string) - Route description
meters (number) - Route distance in meters
minutes (number) - Estimated time in minutes
city (string|null) - City where route is located
country (string|null) - Country where route is located

Location Object

id (number) - Location numeric ID
name (string) - Location name
latLong (string) - Coordinates in "lat,lng" format
city (string|null) - City
country (string|null) - Country

Notes

Trials are sorted by end time (most recent first)
Only completed trials (with end time) are included
Maximum of 1000 results are returned
Use the user guid (not the numeric id) in API calls
Timestamps are in milliseconds since Unix epoch

GET /api/routeStats

Returns comprehensive statistics for a specific route, including time analysis, percentiles, gender breakdown, and more.

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The route GUID (not the numeric ID)

Request Example

GET /api/routeStats?id=abc123-def456-ghi789

Response

Returns a JSON object with route information and comprehensive statistics.

Success Response (200 OK)

{
  "route": {
    "id": 1,
    "guid": "abc123-def456-ghi789",
    "name": "Cerro San Cristóbal",
    "description": "Ruta desde Plaza Italia hasta la cumbre",
    "meters": 3500,
    "city": "Santiago",
    "country": "Chile"
  },
  "statistics": {
    "totalTrials": 150,
    "uniqueAthletes": 85,
    "times": {
      "best": {
        "seconds": 1245,
        "formatted": "00:20:45"
      },
      "worst": {
        "seconds": 5400,
        "formatted": "01:30:00"
      },
      "mean": {
        "seconds": 2100,
        "formatted": "00:35:00"
      },
      "median": {
        "seconds": 1980,
        "formatted": "00:33:00"
      },
      "standardDeviation": 650.5
    },
    "percentiles": {
      "p10": {
        "seconds": 1350,
        "formatted": "00:22:30"
      },
      "p25": {
        "seconds": 1620,
        "formatted": "00:27:00"
      },
      "p50": {
        "seconds": 1980,
        "formatted": "00:33:00"
      },
      "p75": {
        "seconds": 2520,
        "formatted": "00:42:00"
      },
      "p90": {
        "seconds": 3240,
        "formatted": "00:54:00"
      }
    },
    "gender": {
      "male": {
        "count": 100,
        "uniqueAthletes": 60,
        "best": 1245,
        "mean": 2000,
        "median": 1900
      },
      "female": {
        "count": 50,
        "uniqueAthletes": 25,
        "best": 1380,
        "mean": 2300,
        "median": 2200
      }
    },
    "dateRange": {
      "firstTrial": "2023-01-15T10:30:00Z",
      "lastTrial": "2024-01-10T14:45:00Z"
    }
  }
}

No Data Response (200 OK)

When the route exists but has no finished trials

{
  "route": {
    "id": 1,
    "guid": "abc123-def456-ghi789",
    "name": "Cerro San Cristóbal"
  },
  "message": "No finished trials for this route",
  "stats": null
}

Error Responses

400 Bad Request

Missing required parameter

{
  "error": "Missing route id parameter"
}

404 Not Found

Route not found

{
  "error": "Route not found for id=abc123-def456-ghi789"
}

Response Schema

Root Object

route (object) - Route information
statistics (object) - Comprehensive statistics for the route

Route Object

id (number) - Route numeric ID
guid (string) - Route unique identifier
name (string) - Route name
description (string) - Route description
meters (number) - Route distance in meters
city (string|null) - City where route is located
country (string|null) - Country where route is located

Statistics Object

totalTrials (number) - Total number of completed trials
uniqueAthletes (number) - Number of unique athletes
times (object) - Time statistics (best, worst, mean, median, stdDev)
percentiles (object) - Percentile breakdown (p10, p25, p50, p75, p90)
gender (object) - Statistics grouped by gender
dateRange (object) - First and last trial dates

Times Object

best (object) - Best (fastest) time with seconds and formatted string
worst (object) - Worst (slowest) time
mean (object) - Average time
median (object) - Median time (50th percentile)
standardDeviation (number) - Standard deviation in seconds

Percentiles Object

p10 (object) - 10th percentile (top 10% cutoff)
p25 (object) - 25th percentile (top 25% cutoff)
p50 (object) - 50th percentile (median)
p75 (object) - 75th percentile
p90 (object) - 90th percentile

Gender Object

Contains keys: male, female, other (if data exists)

count (number) - Number of trials by this gender
uniqueAthletes (number) - Unique athletes of this gender
best (number) - Best time in seconds
mean (number) - Average time in seconds
median (number) - Median time in seconds

DateRange Object

firstTrial (string|null) - ISO 8601 date of the first trial
lastTrial (string|null) - ISO 8601 date of the most recent trial

Notes

Statistics are calculated using Apache Commons Math for accuracy
Only valid, completed trials are included in statistics
Percentiles help understand performance distribution (e.g., P10 = top 10%)
Gender statistics only appear if data exists for that gender
Use the route guid (not the numeric id) in API calls
Time values are provided both as seconds (number) and formatted strings (HH:MM:SS)

Support

For questions, issues, or feature requests related to the API, please contact us.