komoot API documentation version v007

https://external-api.komoot.de/v007/

General

This API is only available to partners, who signed a corresponding partner contract. It is prohibited to use the API without such a contract.

Authentication

Clients need a valid oauth2 authentication to retrieve data from the api. You have to establish an oauth2 connect to retrieve the necessary access token. Once you have it, add a header to your request:

Authorization: Bearer <oauth2 access token>

OAuth Scopes

The API uses different scopes to verify access to resources. The required scopes for you application need to be requested in the authorization process via the scope field. Currently these scopes exist:

  • profile - is required to fetch the user's tour list as well as the details to individual tours
  • tour-upload - is required to upload new tours to the user's account

General information

  • The API returns HAL/json
  • The server may add new properties to json documents. Clients must ignore unknown properties (backwards compatible)
  • Json properties that hold enumerations or types (e.g. sport types or direction types) can be extended in future. Clients must handle unknown types and provide suitable defaults (backwards compatible).
  • The headers Cache-control, Last-modified and etags are set if applicable.
  • If resources contain i18n content, the Accept-Language header is used to return the most suitable content.
  • For further help you can contact partner@komoot.de

User

get

Retrieve a list of tours the user has created, recorded or participated on. Items are sorted by tour date, descending. If the list is long, it may be paginated. In this case, next and prev HAL links provide URLs for the next and previous pages.

get

URI Parameters

  • username: required (string)

    Example:

    tobias, 104567979941

Query Parameters

  • limit: (integer)

    number of items per page

  • page: (integer)

    page number starting at 0

  • status: (one of public)

    Whether to return only public tours. Must be set if requesting tours from a different user.

  • type: (one of tour_planned, tour_recorded)

    Optional parameter for filtering tours by type.

  • only_unlocked: (boolean)

    Whether only unlocked tours should be shown. All recorded tours are unlocked. For planned tours, the tour is unlocked if the user possesses a valid region for the tour. For a user with the complete package, all tours are unlocked. Default is false.

  • center: (string)

    Optional center point coordinates, format: lat,lng

  • max_distance: (number)

    Optional (required if center is set) max distance from the center point to return tours from.

  • sport_types: (string)

    Optional sport types to include in the returned tours.

  • start_date: (date)

    Optional ISO 8601 start date to include tours from

  • end_date: (date)

    Optional ISO 8601 end date to include tours to

  • name: (string)

    Optional tour name filter, will search for tours that contain this input string ignoring case

  • sort_direction: (one of asc, desc)

    Optional sort direction (default is desc), this will change the sort direction of the resulting tours

  • sort_field: (one of name, elevation, duration, date, proximity)

    Optional sort field (default is date), this will change the field to sort on. Proximity search needs center parameter set.

HTTP status code 200

Body

Type: application/hal+json

Schema

HTTP status code 403

Requesting both public and private tours from a different user is forbidden.

Tour

post

Uploads a tour via uploading a FIT or GPX file. The file's byte data is sent as POST body.

post

This resource needs authentication

This resource needs authentication

Headers

  • User-Agent: required (string)

    Tour uploads require a User-Agent to be set. We don't enforce a specific schema but please choose one that uniquely identifies your application or device.

    Example:

    com.my-oauth2-application/0.0.1

Query Parameters

  • data_type: required (string)

    The file data type ("fit" for .fit files, "gpx" for .gpx files and "tcx" for .tcx files)

    Example:

    fit
  • sport: (string)

    Only exists for GPX files, in other file types this can be specified in the file itself - The sport of the tour. See sport type list for possible values.

    Example:

    mtb
  • time_in_motion: (integer)

    Only exists for GPX files, in other file types this can be specified in the file itself. The time in motion in seconds. This is the time the user was active, so the overall duration minus the pauses. It must not be larger than the overall duration of the tour.

    Example:

    32
  • name: (string)

    The title of the tour. If the parameter is not specified it is read from the file. This is also the recommended way. However if your fit file does not contain a name specified via the workout message you can use this to specify the name. For GPX and TCX you should always specify the name in the file.

    Example:

    My super cool tour

Body

Type: application/octet-stream

Example:

The binary data of the file e.g. FIT file

HTTP status code 201

201 CREATED, with the tour body and tour id in the response.

Body

Type: application/hal+json

Schema

HTTP status code 202

202 Accepted, with the tour body and tour id in the response if the tour upload is a duplicate of an already uploaded tour

Body

Type: application/hal+json

Schema

HTTP status code 400

400 Bad Request, the file is not present, could not be read or another parameter is not set

HTTP status code 401

Unauthorized (resource requires authentication)

HTTP status code 403

Forbidden

get

Retrieve a tour. A tour may be a planned tour or a recorded tour.

get

URI Parameters

  • id: required (string)

Query Parameters

  • _embedded: (string)

    optional list of comma-separated resources to embed, available values: coordinates, way_types, surfaces, directions, participants

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/hal+json

Schema

Type: application/vnd.ant.fit

Example:

FIT file bytes

Type: application/gpx+xml

Example:

GPX file

HTTP status code 403

Requesting a private tour of a different user is forbidden. Embedding coordinates, waytypes, directions or surfaces is forbidden for locked, planned tours. A tour is locked if the user has not purchased either the complete package or the region in which the tour starts.

Body

Type: application/hal+json

Example:

{
  "error": "TourAccessDenied",
  "message": "Tour is locked",
  "status": 403
}

get

Retrieve a tour as a FIT file. Only planned tours are supported currently

get

URI Parameters

  • id: required (string)

Query Parameters

  • max_bytes: (number)

    Number of bytes (integer) that the file size should be at max. If file is larger, the geometry of the tour is simplified in order to be smaller than max_bytes.

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/vnd.ant.fit

Example:

FIT file bytes

HTTP status code 403

Requesting a private tour of a different user is forbidden.

get

Retrieve a tour as a GPX file. A tour may be a planned tour or a recorded tour.

get

URI Parameters

  • id: required (string)

Query Parameters

  • max_bytes: (number)

    Number of bytes (integer) that the file size should be at max. If file is larger, the geometry of the tour is simplified in order to be smaller than max_bytes.

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/gpx+xml

Example:

GPX file

HTTP status code 403

Requesting a private tour of a different user is forbidden.

get

get

Retrieve the ordered coordinate sequence of a tour. Each coordinate has latitude, longitude, altitude (in meters) and a time offset from tour start (in milliseconds). The index of a coordinate in the returned items array is the index referenced by the other tour sub-resources (way_types, surfaces, directions).

Retrieve the ordered coordinate sequence of a tour. Each coordinate has latitude, longitude, altitude (in meters) and a time offset from tour start (in milliseconds). The index of a coordinate in the returned items array is the index referenced by the other tour sub-resources (way_types, surfaces, directions).

URI Parameters

  • id: required (string)

Query Parameters

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/hal+json

Schema

HTTP status code 403

Requesting a private tour of a different user is forbidden. Accessing coordinates is also forbidden for locked, planned tours. A tour is locked if the user has not purchased either the complete package or the region in which the tour starts.

HTTP status code 404

Requested tour does not exist.

get

get

Retrieve detailed way type information along a tour. Returns an ordered list of segments, each covering a contiguous range of indices (from inclusive, to exclusive) in the tour coordinates array.

Only available for planned tours.

Retrieve detailed way type information along a tour. Returns an ordered list of segments, each covering a contiguous range of indices (from inclusive, to exclusive) in the tour coordinates array.

Only available for planned tours.

URI Parameters

  • id: required (string)

Query Parameters

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/hal+json

Schema

HTTP status code 403

Requesting a private tour of a different user is forbidden. Accessing way types is also forbidden for locked, planned tours. A tour is locked if the user has not purchased either the complete package or the region in which the tour starts.

HTTP status code 404

Requested tour does not exist or has no way type information (e.g. recorded tours).

get

get

Retrieve detailed surface information along a tour. Returns an ordered list of segments, each covering a contiguous range of indices (from inclusive, to exclusive) in the tour coordinates array.

Only available for planned tours.

Retrieve detailed surface information along a tour. Returns an ordered list of segments, each covering a contiguous range of indices (from inclusive, to exclusive) in the tour coordinates array.

Only available for planned tours.

URI Parameters

  • id: required (string)

Query Parameters

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/hal+json

Schema

HTTP status code 403

Requesting a private tour of a different user is forbidden. Accessing surfaces is also forbidden for locked, planned tours. A tour is locked if the user has not purchased either the complete package or the region in which the tour starts.

HTTP status code 404

Requested tour does not exist or has no surface information (e.g. recorded tours).

get

get

Retrieve turn-by-turn directions along a tour. Each direction instruction is anchored at a coordinate index in the tour coordinates array.

Only available for planned tours.

Retrieve turn-by-turn directions along a tour. Each direction instruction is anchored at a coordinate index in the tour coordinates array.

Only available for planned tours.

URI Parameters

  • id: required (string)

Query Parameters

  • share_token: (string)

    Optional share token which (when active) always grants access to a specific tour, ignoring visibility rules.

HTTP status code 200

Body

Type: application/hal+json

Schema

HTTP status code 403

Requesting a private tour of a different user is forbidden. Accessing directions is also forbidden for locked, planned tours. A tour is locked if the user has not purchased either the complete package or the region in which the tour starts.

HTTP status code 404

Requested tour does not exist or has no directions (e.g. recorded tours).