> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/routes-api/core-concepts.md).

# Core concepts

Route templates, waypoints, pushed routes, updates, deletes and errors.

### Route templates

A route template is a named sequence of GPS waypoints. You create it once and push it to as many users as you like.

| Field                     | Required | Description                                                             |
| ------------------------- | -------- | ----------------------------------------------------------------------- |
| `name`                    | Yes      | Route name shown on the device, up to 255 characters                    |
| `sport`                   | Yes      | Sport type, lowercase (see [Sport types](#sport-types))                 |
| `waypoints`               | Yes      | 2 to 10,000 GPS points, in order                                        |
| `description`             | No       | Up to 2,000 characters. Garmin shows it; other providers ignore it.     |
| `elevation_gain_meters`   | No       | Total elevation gain in meters, 0 or more                               |
| `elevation_loss_meters`   | No       | Total elevation loss in meters, 0 or more                               |
| `speed_meters_per_second` | No       | Average speed of the course, above 0. Garmin uses it; others ignore it. |

If you leave out `elevation_gain_meters` and `elevation_loss_meters`, Terra works them out from the waypoints when every waypoint has `elevation_meters`. Otherwise they are 0.

{% hint style="warning" %}
Fields the API doesn't recognize are ignored without an error. Check field names against these tables: a misspelled field is dropped silently.
{% endhint %}

### Waypoints

| Field              | Required | Description                                        |
| ------------------ | -------- | -------------------------------------------------- |
| `latitude`         | Yes      | Decimal degrees, -90 to 90                         |
| `longitude`        | Yes      | Decimal degrees, -180 to 180                       |
| `elevation_meters` | No       | Meters above sea level, -500 to 9,000              |
| `course_point`     | No       | A point of interest at this waypoint. Garmin only. |

### Course points

A course point marks a point of interest on the route, such as a water stop:

```json
{
  "latitude": 51.5120,
  "longitude": -0.1220,
  "course_point": {
    "type": "water",
    "name": "Water Station"
  }
}
```

`type` is one of `generic`, `summit`, `valley`, `water`, `food`, `danger`, `first_aid`, `sprint`, `segment_start`, `segment_end`, `left`, `right`, `straight`, `left_fork` and `right_fork`. Any other value returns `400 Bad Request`.

Only Garmin shows course points, and it doesn't show `left`, `right`, `straight`, `left_fork` or `right_fork`. Other providers ignore course points; the rest of the route still arrives.

### Sport types

`running`, `trail_running`, `hiking`, `cycling`, `road_biking`, `mountain_biking`, `gravel_cycling` and `other`. Every provider accepts every sport. COROS groups them into running (`running`, `trail_running`, `hiking`) and cycling (everything else).

### Pushed routes

A pushed route is one user's copy of a route on their device. `POST /routes/{route_id}/push?user_id=X` creates it and returns two IDs:

* `pushed_route_id`: Terra's ID for this user's copy. Use it with the `/pushedRoutes` endpoints.
* `provider_route_id`: the ID the provider gave the route. It can change: Garmin, Wahoo and Hammerhead recreate a route the user deleted from their device under a new ID, and Hammerhead also replaces a route whose update keeps the same path (see [Provider compatibility](https://docs.tryterra.co/routes-api/provider-compatibility.md#hammerhead)).

Pushing the same route to the same user again re-sends their pushed route instead of creating a second one. The first push returns `201 Created`; a repeat returns `200 OK` with the same `pushed_route_id`. Both cost 10 Planned Workouts credits; a push the provider rejects is free.

To find a user's pushed routes later, call `GET /pushedRoutes?user_id=X`. Each item has `pushed_route_id`, `route_id`, `provider_route_id`, `created_at` and `last_updated_at`.

### Update a route

```
PUT /routes/{route_id}
```

Send only the fields you want to change. `waypoints`, if you send it, replaces the whole list. The same validation applies as on create.

Every update is re-sent to every user the route was pushed to, and each pushed route that comes back `updated` costs 10 Planned Workouts credits. The response lists each pushed route:

```json
{
  "status": "success",
  "route_id": "295581149349019648",
  "pushed_routes": [
    {
      "pushed_route_id": "295581443239706624",
      "provider_route_id": "1774538415035",
      "status": "updated"
    }
  ]
}
```

| Status    | Meaning                                                                                                                                                  |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `updated` | The provider has the new version.                                                                                                                        |
| `failed`  | The provider did not take it, and `error` has its reason. Repeat the request to re-send.                                                                 |
| `skipped` | Terra can no longer reach this user's device, for example because they disconnected or their provider authorization lapsed. The user needs to reconnect. |

If any pushed route failed, the response is `207 Multi-Status`, with a `message` in place of `status`:

```json
{
  "message": "1 of 2 pushed copies were not updated; the route itself is saved, so repeat the request to re-send them",
  "route_id": "295581149349019648",
  "pushed_routes": [
    { "pushed_route_id": "295581443239706624", "provider_route_id": "1774538415035", "status": "updated" },
    { "pushed_route_id": "295581443239706625", "provider_route_id": "117280.route.3f1c", "status": "failed", "error": "unprocessable request: hammerhead rejected route update (status 400)" }
  ]
}
```

The template is already saved, so repeating the same `PUT` re-sends it.

{% hint style="info" %}
An update can re-send to at most 50 pushed routes. For a route pushed to more users, `PUT` returns `422 Unprocessable Entity` and nothing changes. Create a new route instead.
{% endhint %}

### Delete routes

`DELETE /routes/{route_id}` removes the route from every user's device, then deletes the template, and returns `204 No Content`.

* If a provider refuses to delete a pushed route, the response is `207 Multi-Status` with each pushed route's `status` (`deleted`, `failed` or `skipped`). The template and the pushed routes that failed are kept, so repeat the request to finish.
* A `skipped` pushed route can't be reached (the user disconnected) and doesn't block the delete: it may stay on that user's device.

`DELETE /pushedRoutes/{pushed_route_id}?user_id=X` removes a route from one user's device. It always returns `204 No Content` and removes the pushed route from Terra, even if the provider could not delete its copy.

On COROS, deletes remove the route from Terra only. It stays on the device.

### Concurrent requests

Pushes, updates and deletes of the same route run one at a time. A request that arrives while another is still running on that route returns `409 Conflict`. Retry it after a short wait.

### Errors

Errors use the standard problem format: `type`, `title`, `detail` and `instance`, plus `errors` for validation failures.

| Status   | When                                                                                            | What to do                                       |
| -------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 400      | The request failed validation. `errors` lists why.                                              | Fix the request.                                 |
| 403      | Your account doesn't have the Planned Workouts add-on, or the user hasn't allowed route access. | Enable the add-on, or ask the user to reconnect. |
| 404      | The route or pushed route doesn't exist, or the user's provider doesn't support routes.         | Check the IDs and the provider.                  |
| 409      | Another request is changing the same route.                                                     | Retry after a short wait.                        |
| 422      | An update would re-send to more than 50 pushed routes.                                          | Create a new route instead.                      |
| 424      | The provider rejected a push. `detail` has its reason.                                          | Fix the route, or check the provider's limits.   |
| 429      | The provider rate-limited the request.                                                          | Retry later.                                     |
| 503, 504 | The provider is unavailable or timed out.                                                       | Retry later.                                     |

### Complete example

A 5 km running loop with elevation and a water stop:

```json
{
  "name": "Morning Run Loop",
  "sport": "running",
  "description": "5 km loop with slight elevation",
  "waypoints": [
    { "latitude": 51.5074, "longitude": -0.1278, "elevation_meters": 10 },
    {
      "latitude": 51.5120,
      "longitude": -0.1220,
      "elevation_meters": 30,
      "course_point": { "type": "water", "name": "Water Station" }
    },
    { "latitude": 51.5160, "longitude": -0.1180, "elevation_meters": 55 },
    { "latitude": 51.5120, "longitude": -0.1140, "elevation_meters": 70 },
    { "latitude": 51.5074, "longitude": -0.1278, "elevation_meters": 10 }
  ]
}
```
