Example requests

MOVE Backend APIs

This site shows example request between your project backend and Move SDK API.

Create a new user

Use your Move SDK Project Id and your API Key as Basic Auth to register a new User. The userId may be any arbitrary string, only : is forbidden. The maximum length of userId is 100 characters.

Request:

POST https://sdk.dolph.in/v20/user
content-type: application/json
Authorization: Basic {PROJECT_ID}:{API_KEY}

{
  "userId": "string"
}

Response:

{
  "accessToken": "{ACCESS_TOKEN}", // allows communication with MOVE SDK back-end
  "refreshToken": "{REFRESH_TOKEN}", // allows Move App to renew access token
  "userId": "{USER_ID}", 
  "audience": "{NAME_OF_API_KEY}", 
  "projectId": {PROJECT_ID}
}

Initialize your Move SDK App with these tokens.

Create a new user (authCode)

Use your Move SDK Project Id and your API Key as Basic Auth to register a new User. The userId may be any arbitrary string, only : is forbidden. The maximum length of userId is 100 characters.

Request:

POST https://sdk.dolph.in/v20/user/authcode
content-type: application/json
Authorization: Basic {PROJECT_ID}:{API_KEY}

{
  "userId": "string"
}

Response:

{
  "authCode": "{AUTHENTICATION_CODE}"
}

Fetch user timeline

Fetch user timeline easily with:

Request:

GET https://sdk.dolph.in/v20/timeline?userId={USER_ID}&projectId={PROJECT_ID}
content-type: application/json
Authorization: Basic {PROJECT_ID}:{API_KEY}

Response:

[
  {
    "projectId": {PROJECT_ID},
    "userId": "{USER_ID}",
    "startTs": "2022-10-16T08:06:00Z",
    "endTs": "2022-10-16T09:41:00Z",
    "type": "IDLE",
    "features": {
      "source": {
        "id": "",
        "name": "timeline"
      }
    }
  },
  {
    "projectId": {PROJECT_ID},
    "userId": "{USER_ID}",
    "startTs": "2022-10-17T05:58:00Z",
    "endTs": "2022-10-17T06:03:00Z",
    "type": "CYCLING",
    "features": {
      "startLocation": {
        "lat": 48.328016,
        "lon": 16.204514,
        "timeZone": "Europe/Vienna"
      },
      "endLocation": {
        "lat": 48.3338,
        "lon": 16.20949,
        "timeZone": "Europe/Vienna"
      },
      "source": {
        "id": "585497",
        "name": "trip"
      },
      "gpsStats": {
        "distance": 947,
        "maxSpeed": 23,
        "averageSpeed": 13
      },
      "metas": {},
      "dangerousAreas": {
        "areas": []
      }
    }
  }
]

Every timeline item has the following properties:

projectId: Move SDK Project ID
userId: Id of specific User
startTs: start timestamp as an ISO 8601 date time
endTs: end timestamp as an ISO 8601 date time
type: Mode of transport

Fetch specific timeline items

Convert the startTs of a given timeline item to a UNIX timestamp to fetch a specific timeline item. For example,

in the user timeline you find a timeline item with startTs in UTC time
```
"startTs":"2022-04-12T16:25:00Z"
```
Conversion into unix timestamp (UTC) is "1649780700" - this is your START_TS for fetching the specific timeline item.
Please note, if you want to display the trip in human readable form, you may want to translate the startTs to the local timezone (which you can find in "startLocation / timeZone"; e.g. "Europe/Vienna").

Request:

GET https://sdk.dolph.in/v20/timeline/{START_TS}?userId={USER_ID}&projectId={PROJECT_ID}
content-type: application/json
Authorization: Basic {PROJECT_ID}:{API_KEY}

Response:

{
  "projectId": {PROJECT_ID},
  "userId": "{USER_ID}",
  "startTs": "2022-10-17T05:58:00Z",
  "endTs": "2022-10-17T06:03:00Z",
  "type": "CYCLING",
  "features": {
    "startLocation": {
      "lat": 48.328016,
      "lon": 16.204514,
      "timeZone": "Europe/Vienna"
    },
    "endLocation": {
      "lat": 48.3338,
      "lon": 16.20949,
      "timeZone": "Europe/Vienna"
    },
    "source": {
      "id": "585497",
      "name": "trip"
    },
    "gpsStats": {
      "distance": 947,
      "maxSpeed": 23,
      "averageSpeed": 13
    },
    "metas": {},
    "dangerousAreas": {
      "areas": []
    }
  }
}

Fetch way points

Some timeline item types like CAR and CYCLING return way points.

Request:

GET https://sdk.dolph.in/v20/timeline/{START_TS}/points?userId={USER_ID}&projectId={PROJECT_ID}&withWayPointInfo=true
content-type: application/json
Authorization: Basic {PROJECT_ID}:{API_KEY}

Response:

[
  {
    "lat": 48.31712,
    "lon": 16.2256,
    "timestamp": "2022-09-01T14:50:08Z",
    "wayPointInfo": {
      "speed": 66,
      "speedLimit": 100,
      "wayType": "other",
      "origLat": 48.317138,
      "origLon": 16.225608
    }
  },
  {
    "lat": 48.31711,
    "lon": 16.22608,
    "timestamp": "2022-09-01T14:50:10Z",
    "wayPointInfo": {
      "speed": 67,
      "speedLimit": 100,
      "wayType": "other",
      "origLat": 48.317118,
      "origLon": 16.226084
    }
  }
]

Important: The Move SDK always tries to match GPS points to an existing road. For the original way points withWayPointInfo is required.

Label item

Relabel existing timeline items with a PATCH request:

PATCH https://sdk.dolph.in/timeline/label/{START_TS}/{NEW_MODE_OF_TRANSPORT}?userId={USER_ID}&projectId={PROJECT_ID}
Content-Type: application/json; charset=UTF-8
Authorization: Basic {PROJECT_ID}:{API_KEY}

Possible mode of transports:

UNKNOWN
DRIVING
TRAIN
TRAM
CAR
METRO
FAKETRIP
WALKING
IDLE
CYCLING

The response to this request is the existing timeline item with the new type.

Delete item

Delete a single timeline item.

DELETE https://sdk.dolph.in/v20/timeline/{START_TS}?userId={USER_ID}&projectId={PROJECT_ID}
Content-Type: application/json; charset=UTF-8
Authorization: Basic {PROJECT_ID}:{API_KEY}

Fetch last user location

Every user has 4 last locations, in different contexts:

car-end: last position of his car
timeline-end: end location of last timeline item
trip-position: updates live during a trip
user-pos: updates user walking position

GET https://sdk-test.dolph.in/v20/location?projectId={PROJECT_ID}&userId={USER_ID}
Content-Type: application/json; charset=UTF-8
Authorization: Basic {PROJECT_ID}:{API_KEY}

Response:

[
  {
    "context": "car-end",
    "lat": 48.322418,
    "lon": 16.203955,
    "timestamp": "2022-10-15T16:29:00Z"
  },
  {
    "context": "timeline-end",
    "lat": 48.3338,
    "lon": 16.20949,
    "timestamp": "2022-10-17T06:03:00Z"
  },
  {
    "context": "trip-position",
    "lat": 48.214684,
    "lon": 16.413719,
    "timestamp": "2022-10-17T07:04:41Z"
  },
  {
    "context": "userpos",
    "lat": 48.214723,
    "lon": 16.413646,
    "timestamp": "2022-10-17T07:03:10Z"
  }
]

PreviousMOVE Assistance Notifier NextFAQ

Last updated 1 year ago

hashtagCreate a new user

hashtagCreate a new user (authCode)

hashtagFetch user timeline

hashtagFetch specific timeline items

hashtagFetch way points

hashtagLabel item

hashtagDelete item

hashtagFetch last user location

Create a new user

Create a new user (authCode)

Fetch user timeline

Fetch specific timeline items

Fetch way points

Label item

Delete item

Fetch last user location