This initial API includes a limited yet powerful set of calls allowing developers to make use of our state-of-art math and physics engine that powers our public site www.thepacingproject.com.
At this time our API is in a closed beta phase. We will be evaluating and updating the technologies and looking at potential partnerships.
If you are interested in using our API for software development or hardware integration please contact us with the following information:
1.0
The Pacing Project API is organized around REST. Our API is designed to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.
The following demonstrates how to retrieve a specific course's information and groups of courses based on search parameters.
You can pull information on a single course by sending the course's unique ID as courseId in the request parameters. In this example the course ID of 23 is passed in as a request parameter.
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/course?
courseId=23
Course information returned as JSON for the course with the specific id passed as courseId in the request parameters.
{
courses:[
{
"courseId": 23, // course unique identifier
"courseName": "Boston Marathon", // course name
"courseCity": "Hopkinton", // course city (start)
"courseState": "MA", // course state
"courseCountry": "US", // course country
"startLatitude": 42.22978, // course latitude (start)
"startLongitude": -71.5182, // course longitude (start)
"courseDistance": 42474.8565, // course distance (meters)
"raceDate": "2016-04-18", // date of race (YYYY-MM-DD)
"minElevation": 2.8, // minimum elevation (meters)
"maxElevation": 140.4, // maximum elevation (meters)
"avgElevation": 48.493, // average elevation (meters)
"gainElevation": 336.6, // overall elevation gain (meters)
"lossElevation": 471.8 // overall elevation loss (meters)
}
]
}
You can pull information for a group of courses by sending one or more request parameters with out a specific course ID parameter. In this example the request parameter for the course's distance as courseDistance is passed in. (note: to pull all courses, simply send the request with no search parameters)
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/course?
courseDistance=42500
Course information returned as JSON for the courses that matched the supplied courseDistance request parameters.
{
courses:[
{
"courseId": 23, // course unique identifier
"courseName": "Boston Marathon", // course name
"courseCity": "Hopkinton", // course city (start)
"courseState": "MA", // course state
"courseCountry": "US", // course country
"startLatitude": 42.22978, // course latitude (start)
"startLongitude": -71.5182, // course longitude (start)
"courseDistance": 42474.8565, // course distance (meters)
"raceDate": "2016-04-18", // date of race (YYYY-MM-DD)
"minElevation": 2.8, // minimum elevation (meters)
"maxElevation": 140.4, // maximum elevation (meters)
"avgElevation": 48.493, // average elevation (meters)
"gainElevation": 336.6, // overall elevation gain (meters)
"lossElevation": 471.8 // overall elevation loss (meters)
},
{
"courseId": 19,
"courseName": "Chicago Marathon",
"courseCity": "Chicago",
"courseState": "IL",
"courseCountry": "US",
"startLatitude": 41.88085,
"startLongitude": -87.6207,
"courseDistance": 42743.2991,
"raceDate": "2016-05-30",
"minElevation": 175.2,
"maxElevation": 184,
"avgElevation": 180.1146,
"gainElevation": 115.2,
"lossElevation": 114
}
]
}
| Parameter | Description | Required |
|---|---|---|
| Authorization |
A unique key to authorize use of the Pacing Project API. If you or your company is interested in working with our API, please contact us for details. | Yes |
| courseId integer |
Specifies the exact course to pull. Course Id overrides all other search parameters. If no course Id is supplied then search parameters are used to pull courses based on those parameters. | No |
| courseGroup integer |
Filter courses by the following groups. (range: 1 to 4, default: 1) 1 = your courses 2 = public courses 3 = your public courses 4 = your private courses |
No |
| courseName string |
Filter courses by name. (example: "Boston Marathon") | No |
| courseCity string |
Filter courses by city. (example: "Hopkinton") | No |
| courseState string |
Filter courses by state. (example: "MA") All US states are standard 2 character abbreviations. | No |
| courseCountry string |
Filter courses by country. (example: "US") | No |
| courseDistance integer |
Filter courses by distance in meters (example: "42000"). If a distance is supplied, all courses within +/- 3000 meters of that distance will be pulled. | No |
The Pacing Project requires a BASE64 encoded .GPX file (or a gzipped BASE64 encoded file) and a course name to process a new course into the system. These are stored in the system and can be retrieved for use in the race pacing engine. The system returns the basic information about the course as well as the new assigned course ID.
The parameters courseName and courseFile are required for this call. This process can be complex and may take several seconds for long or hilly courses.
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/upload-course
courseName=Boston Marathon courseFile=PHhtbD48ZGF0YSBzaWxseT0iaW5mbyIgLz48L3htbD4...
Course information returned as JSON for the uploaded GPX file. The course can now be referenced by the returned course ID.
{
"result":[
{
"courseId": 23, // course unique identifier
"courseName": "Boston Marathon", // course name
"courseCity": "Hopkinton", // course city (start)
"courseState": "MA", // course state
"courseCountry": "US", // course country
"startLatitude": 42.22978, // course latitude (start)
"startLongitude": -71.5182, // course longitude (start)
"courseDistance": 42474.8565, // course distance (meters)
"raceDate": "2016-04-18", // date of race (YYYY-MM-DD)
"minElevation": 2.8, // minimum elevation (meters)
"maxElevation": 140.4, // maximum elevation (meters)
"avgElevation": 48.493, // average elevation (meters)
"gainElevation": 336.6, // overall elevation gain (meters)
"lossElevation": 471.8 // overall elevation loss (meters)
}
]
}
| Parameter | Description | Required |
|---|---|---|
| Authorization |
A unique key to authorize use of the Pacing Project API. If you or your company is interested in working with our API, please contact us for details. | Yes |
| courseName string |
A descriptive "official" name for this course. (example: "Melborn 70.3") Course names should generally match the event's name. | Yes |
| courseFile string |
A base64 encoded course file. (example: "GPX") Currently we only accept GPX files. | Yes |
| raceDate string |
Race date formatted as YYYY-MM-DD. (example: "2016-04-18") | No |
| clientDesc string |
An open field that may be used by the client for a description or an additional filter variable. (255 max characters) | No |
| coursePublic integer |
An optional boolean setting (0 = false, 1 = true) to allow courses to be available to the public. (range: 0 to 1, default: 0) | No |
| maxSegments integer |
Maximum number of allowed segments in the course. (range: 1 to 200, default: course distance in kilometers) | No |
This POST call generates a segmented race power plan for an individual runner based on the required inputs: courseId, modelType and (raceGoalTime or raceGoalNGS). To fine tune the runner's plan we also allow several additional optional parameters.
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/generate-raceplan
courseId=23 modelType=1 raceGoalTime=12600
Race plan totals, segment information and gradient based pace hints are returned as JSON for the course and supplied modelType and raceGoalTime request parameters.
{
totals:[
{
"distance": 42474.86, // total distance (meters)
"time": 12599.724, // total time (seconds)
"speed": 3.3711, // average speed (meters per second)
"NGS": 3.36, // Normalized Graded Speed (meters per second)
"rIF": 0.93, // run Intensity Factor
"rTSS": 346 // run Training Stress Score
}
],
segments:[
{
"id": 1, // segment count
"distance": 800.61, // segment distance (meters)
"time": 217.0804, // segment time (seconds)
"speed": 3.688 // segment speed (meters per second)
"gradient": -4.772 // segment average gradient
},
{
"id": 2,
"distance": 668.62,
"time": 207.7306,
"speed": 3.219,
"gradient": 1.631
},
{
"id": 3,
"distance": 659.669,
"time": 184.4547,
"speed": 3.576,
"gradient": -2.742
}
],
gradientDistribution:[
{
"gradientLow": -6, // low range (degrees)
"gradientHigh": -4, // high range (degrees)
"speed": 6.92912, // speed for range (meters per second)
"percentageTime": 0.01605 // percentage of time in range
},
{
"gradientLow": -4,
"gradientHigh": -2,
"speed": 6.62461,
"percentageTime": 0.07248
},
{
"gradientLow": -2,
"gradientHigh": 0,
"speed": 6.01223,
"percentageTime": 0.56846
}
]
}
| Parameter | Description | Required |
|---|---|---|
| Authorization |
A unique key to authorize use of the Pacing Project API. If you or your company is interested in working with our API, please contact us for details. | Yes |
| courseId integer |
Specifies the course to use for this plan. | Yes |
| modelType integer |
Specifies the model type to use for this plan. (range: 1 to 2) 1 = Goal Time Model 2 = Goal Normalized Pacing Model |
Yes |
| Please note that only one of the following two parameters is required and is dependent on the modelType that is requested. | ||
| raceGoalTime integer |
Total race goal time in seconds. (range: 90 to 144000) | Yes |
| raceGoalNGS integer |
Normalized graded speed in meters per second. (range: 1 to 10) | Yes |
| thresholdSpeed integer |
Threshold speed in meters per second. (range: 1 to 10, default: 4) | No |
| raceMinSpeed integer |
Minimum speed in meters per second (range: 1 to 10, default: 1) | No |
| raceMaxSpeed integer |
Maximum speed in meters per second (range: 1 to 10, default: 10) | No |
This POST call generates a NGS (normalized graded speed) and a TS (threshold speed) for an individual runner based on the required inputs: goalDistance, raceDistance1 and raceTime1. For greater accuracy a second raceDistance2 and raceTime2 can be posted.
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/pace-calculator
goalDistance=42164.81 raceDistance1=21082.41 raceTime1=5100
Pace information is returned as JSON for the supplied goalDistance, raceDistance1 and raceTime1 request parameters.
{
paces:[
{
"raceGoalNGS": 3.97, // race goal normalized graded speed (meters per second)
"thresholdSpeed": 4.22 // threshold speed (meters per second)
}
]
}
| Parameter | Description | Required |
|---|---|---|
| Authorization |
A unique key to authorize use of the Pacing Project API. If you or your company is interested in working with our API, please contact us for details. | Yes |
| goalDistance integer |
Goal race distance in meters. (range: 800 to 200000) | Yes |
| raceDistance1 integer |
Past race distance in meters. (range: 800 to 200000) | Yes |
| raceTime1 integer |
Past race time in seconds. (range: 90 to 144000) | Yes |
| raceDistance2 integer |
Past race distance in meters. (range: 800 to 200000) | No |
| raceTime2 integer |
Past race time in seconds. (range: 90 to 144000) | No |
The following demonstrates how to retrieve a specific course's segment details based on search parameters.
You can pull segment details on a single course by sending the course's unique ID as courseId in the request parameters. In this example the course ID of 23 is passed in as a request parameter.
Authorization: xxxxxxxxxxxxxxxxxx
https://api.thepacingproject.com/v1/course-segments?
courseId=23
Segment details returned as JSON for the course with the specific id passed as courseId in the request parameters.
{
courseSegments:[
{
"courseId": 23, // course unique identifier
"avgElevation": 120.6, // segment elevation (meters)
"segmentDistance": 800.6096, // segment distance (meters)
"startDistance": 0, // segment start point distance from start (meters)
"endDistance": 800.6096, // segment end point distance from start (meters)
"segmentGrade": -4.9462, // segment grade (degrees)
"segmentDirection": 52.8024, // segment direction (degrees)
"startElevation": 140.4, // segment start point elevation (meters)
"endElevation": 100.8, // segment end point elevation (meters)
"startLatitude": 42.22978, // segment start point latitude
"startLongitude": -71.5182, // segment start point longitude
"endLatitude": 42.234, // segment end point latitude
"endLongitude": -71.51069 // segment end point longitude
},
{
"courseId": 23,
"avgElevation": 99.8,
"segmentDistance": 185.864,
"startDistance": 800.6096,
"endDistance": 986.4736,
"segmentGrade": -1.0761,
"segmentDirection": 57.3896,
"startElevation": 100.8,
"endElevation": 98.8,
"startLatitude": 42.234,
"startLongitude": -71.51069,
"endLatitude": 42.2349,
"endLongitude": -71.50879
}
]
}
| Parameter | Description | Required |
|---|---|---|
| Authorization |
A unique key to authorize use of the Pacing Project API. If you or your company is interested in working with our API, please contact us for details. | Yes |
| courseId integer |
Specifies the course to pull segment details for. | Yes |
The Pacing Project API uses the standard set of HTTP response codes. For convenience, the most relevant ones are listed here.
Note that, in the event of an error, a message is returned in the response body.
| Code | Type | Description |
|---|---|---|
| 200 | OK | Success! |
| 400 | Bad Request | The request could not be understood due to malformed syntax. |
| 401 | Unauthorized | Authentication credentials were missing or incorrect. |
| 403 | Forbidden | The request is understood but it has been refused due to insufficient permission. |
| 404 | Not Found | The URI requested is invalid or the resource requested, such as a user, does not exist. |
| 405 | Method Not Allowed | The URI requested does not support the specific HTTP method used in the request. |
| 500 | Internal Server Error | Something is broken. Please contact us so the The Pacing Project team can investigate. |
| 502 | Bad Gateway | The server is down or being upgraded. |
| 503 | Service Unavailable | The servers are up, but overloaded with requests. Try again later. |