API

Integrate your own app with Map the Paths...

v1 of the API has been designed to built for use with the MTP Desktop Uploader. If you have feature requests for v2, please submit them on the forum.

Data Types

JSON is the default format for all resources. If other formats are avaliable, you can request it by specifying the format in the request's Accept header.

Root Endpoint

All resources are accessible through the root endpoint prefixed with current version v1. All URLs referenced in the documentation have this endpoint as base path.

https://www.mapthepaths.com/api/v1

Client ID

Map the Paths uses a client ID to allow access to API v1. You can register an application at your developer registration page. The MTP API expects that the client_id parameter is present in all requests.

OAuth

The MTP API lets you interact with MTP on the behalf of a user. This is achieved by using OAuth 2.0. MTP supports the implicit and code flow of the OAuth 2.0 specification.

MTP OAuth tokens do not have any expiration time. The user can at any time revoke the token directly from the settings page.

Request Authorization

get
Authorize

/accounts/authorize?client_id=<client_id>&response_type=<response_type>
The OAuth authorization endpoint. Your app redirects a user to this endpoint, allowing them to delegated access to their account.
Request
Response
Request
Query Parameters
response_type
required
string
implicit of token
client_id
required
string
The client ID generated when creating the application on Map the Paths Web. Create a new app here.
Response
200: OK

Example Request

curl --location --request GET 'https://MTPDOMAIN/api/v1/authorize?client_id=98fgjsjduf89388&response_type=token'

Sequences

post
Create Sequence

/sequence/create
Creates a temporary sequence. Sequence is only published after PUT Mapillary sequence data sent. Will respond with a Map the Paths unique sequence ID.
Request
Response
Request
Path Parameters
source
optional
string
Always="mtpdu"
name
optional
string
Name of sequence
description
optional
string
Description of sequence
transport_type
required
string
See available transport_types below.
tag
required
object
List of tags [tag1,tag2]
Response
200: OK

Example request

curl --location --request POST 'https://MTPDOMAIN/api/v1/sequence/create' \
--form 'name=<name>' \
--form 'description=<description>' \
--form 'transport_type=<transport_type>' \
--form 'tag=<tags>
--form 'source=mtpdu`

The name of the sequence generated by Map the Paths Uploader (or other app)

The description of the sequence generated by Map the Paths Uploader (or other app).

Transport type

Here are currently available transport_types:

PARENT

CHILD

API_VALUE

1

BASE Jump

Air

"BASE Jump"

2

Glider

Air

Glider

3

Hang Glide

Air

"Hang Glide"

4

Parachute

Air

Parachute

5

Paraglide

Air

Paraglide

6

Wingsuit

Air

Wingsuit

7

Helicopter

Air

Helicopter

8

Plane

Air

Plane

9

Drone

Air

Drone

10

Bicycle

Earth

Bicycle

11

Rollerskate

Earth

Rollerskate

12

Scooter

Earth

Scooter

13

Skateboard

Earth

Skateboard

14

Walk

Earth

Walk

15

Rock Climbing

Earth

"Rock Climbing"

16

Car

Earth

Car

17

Electric Bicycle

Earth

"Electric Bicycle"

18

Electric Scooter

Earth

"Electric Scooter"

19

Electric Car

Earth

"Electric Car"

20

Wheelchair

Earth

Wheelchair

21

Ski

Snow

Ski

22

Snowboard

Snow

Snowboard

23

Snowshoe

Snow

Snowshoe

24

Ice Skating

Snow

"Ice Skating"

25

Snowmobile

Snow

Snowmobile

26

Canoe

Water

Canoe

27

Kayak

Water

Kayak

28

Kiteboard

Water

Kiteboard

29

Paddleboard

Water

Paddleboard

30

Row

Water

Water

31

Scuba Dive

Water

Scuba Dive

32

Sail

Water

Sail

33

Surf

Water

Surf

34

Swim

Water

Swim

35

Windsurf

Water

Windsurf

36

Boat

Water

Boat

37

Freedive

Water

Freedive

38

Other

Unlisted

Other

Tag

You can pass any tag to the API as long as it contains a-z, 1-9 or "-" characters.

We also maintain a default list of recommended tag(s) to use:

type

description

beach

a sloping shoreline consisting of sand, gravel, soil or other sediment.

canal

a man-made waterway connecting two bodies of water and is designed to shorten travel time or irrigate

canyon

narrow valley with steep sides; usually created by erosion

cave

a hallow space in the ground or mountain with an opening to enter.

cliff

a high, steep slope of rock or soil

coast

land along the sea or ocean

cove

a small bay with a restricted entrance.

crevasse

is a large crack in a glacier that can be seen from the surface.

dam

a wall built across a stream or river to hold back water

desert

dry, barren region usually sandy and without trees, little rainfall or practical use of land unless irrigated

"dry lake"

a lake that is dry all year or most of the year with the dry layer being mud or salt.

dune

a pile of sand created by wind or waves (underwater dunes)

estuary

where a river runs into the ocean or other types of salt water.

fjord

a narrow inlet of the sea between high banks or cliffs created by glaciers

floodplain

a flat are of land around a river that floods when the river gets high.

forest

a large tract of land covered with trees and underbrush; extensive wooded area

geyser

an opening in the ground that ejects hot water and steam due to volcanic activity.

glacier

a large body of slow moving ice which alters the land around it through displacement

gorge

a deep valley with steep rocks on each side. also referred to as a valley or canyon.

harbor

a sheltered area of water where ships may anchor safely

headland

a large area of land extending into a large area of water

hill

a raised part of the earth‰¥Õs surface with sloping sides; old mountain which because of erosion has become rounder and shorter

iceberg

a large mass of floating ice that has broken off from a glacier, most of this is underwater

island

an are of land completely surrounded by water

lake

a large body of water surrounded by land

"lava field"

area of land covered by lava flow.

marsh

a wetland with grasses and little or no trees

mountain

high, rocky land, usually with steep sides and a pointed or rounded top, higher than a hill

"mouth (of a river)"

place where a river empties into a larger body of water; the end of a river

"natural arch"

rock that forms together with a natural rock bridge usually caused by erosion.

oasis

a fertile place in the desert where there is water and some vegetation

ocean

largest body of salt water; these cover 3/4 of the earth‰¥Õs surface.

peninsula

piece of land that extends into a body of water and is surrounded on three sides by water.

plain

a broad, flat or gently rolling area; usually low in elevation.

plateau

flat highland area with one steep face; elevated plain.

pond

a small body of water surrounded by land.

port

man-made place along the coastline where ships can load and unload cargo; not a natural harbor.

prairie

a large plains region with tall grass.

rapids

a part of a river, generally shallow, where the currents move swiftly over rocks.

ravine

a smaller form of a valley with steep sides.

reef

a ridge of rock or sand at or near the surface of the water.

reservoir

a lake where water is collected and stored for future use.

river

a large stream of water flowing through the land into a lake, ocean, or other body of water.

sea

a large body of water, usually salt water, partly or completely surrounded by land.

swamp

an area of land that is always soaked with water; low, wet land that supports grass and trees.

valley

low land between hills or mountains.

volcano

a cone shaped mountain formed out of rock or ash thrown up from inside the arth, frequently with an opening or depression at the top.

waterfall

place where running water makes a sheer drop, usually over a cliff.

put
Sequence Integration Data

/sequence/import/<MTP_SEQUENCE_UNIQUE_ID>
This endpoint is designed for use with MTP Desktop Uploader. If the sequence has been synced with a 3rd party integration by MTPDU, then it will be updated in MTPW using this endpoint.
Request
Response
Request
Path Parameters
mapillary_user_token
optional
string
The Mapillary user token, required to import tour into MTPW.
strava
optional
string
If MPTDU uploaded to Strava the activity id of the uploaded activity.
google_street_view
optional
string
If MTPDU uploaded to Google Street View. If true shows GSV sharelink.
mapillary_sequence_key
optional
string
The Mapillary Sequence Key for the Sequence. Must be passed with `mapillary_user_token` value
Query Parameters
MTP_SEQUENCE_UNIQUE_ID
required
string
The unique MTP Sequence ID
Response
200: OK

"": ""

Example request

curl --location --request PUT 'https://MTPDOMAIN/api/v1/sequence/import/jjff8djf-jkld87-kls889' \
--data-raw '{
"mapillary_sequence_key": "<MAPILLARY_SEQ_KEY>",
"mapillary_user_token": "<MAPILLARY_USER_TOKEN>"
}'

Endpoint behaviour

Request to this endpoint PUT'ing existing values will overwrite existing data and append any new data.

For example (request 1)

curl --location --request PUT 'https://MTPDOMAIN/api/v1/sequence/import/jjff8djf-jkld87-kls889' \
--data-raw '{
"mapillary_sequence_key": "123",
"mapillary_user_token": "456",
"google_street_view": " FALSE,
"strava": "18273749957"
}'

Then (request 2)

curl --location --request PUT 'https://MTPDOMAIN/api/v1/sequence/import/jjff8djf-jkld87-kls889' \
--data-raw '{
"google_street_view": https://googleusercontent.com/something
}'

Will leave the following integration records against sequence.

  • mapillary_sequence_key=123

  • mapillary_user_token=346

  • google_street_view= https://googleusercontent.com/something

  • strava=18273749957

Token exchange endpoints

To support Map the Paths Uploader Oauth flow, the following endpoints exists so the MTP Uploader can act as a middle man for the token exchange workflow.

These endpoints are listening for tokens for logged in MTPW users. If user not logged in, will be prompted to login before token exchange happens.

They do not user the root endpoint. For example; /accounts/check-mapillary-oauth resolves to DOMAIN//accounts/check-mapillary-oauth

MTPW -> Mapillary

Used for users authenticating to Mapillary directly from web app

/accounts/check-mapillary-oauth

When token received is stored in app, and user continues intended workflow in the app.

MTPU -> Mapillary -> MTPW -> MTPU

/accounts/check-mtpu-mapillary-oauth

When token received is stored in app, token is then passed to Map the Paths web (and stored in MTPW) and user redirected to desktop app (redirect url = app.mtp.desktop://app)

See more about the MTPU Mapillary integration here.

MTPU -> Google Street View -> MTPW -> MTPU

/accounts/check-mtpu-google-oauth

When token received is stored in app, token is then passed to Map the Paths web (and stored in MTPW) and user redirected to desktop app (redirect url = app.mtp.desktop://app)

See more about the MTPU GSV integration here.

MTPU -> Strava -> MTPW -> MTPU

/exchange_token

When token received is stored in app, token is then passed to Map the Paths web (and stored in MTPW) and user redirected to desktop app (redirect url = app.mtp.desktop://app)

See more about the MTPU Strava integration here.