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"
  }
]