Getting Started

Welcome to the Motion-S Platform!

We help teams across the mobility sector to generate mobility data and gain deep insights from simple location data.

The Motion-S REST API serves as an interface to our platform that enables you to submit your mobility data and get deep insights.

ℹ️Covered in this guide
Manage your subscription
Components of the API Suite
Administration

Manage Your Subscription

Contact us to obtain your credentials to get started and explore the full power of our analytics API. For more information on pricing and packages, check our plans.

Components of the API Suite

The basic building blocks of our platform are the following.

Administration

User, access, and entity management

User management

Organization

It represents your organization. When we create an organization for you, we will provide you with the organization details, default fleet details, and admin user credentials. With admin user credentials, you can create entities, new API keys and access the API. You can also modify the details for your organization and get the consumption in terms of the number of active assets (devices) and the number of calls made towards our API, grouped by months.

curl --request PATCH \
     --url https://api.motion-s.com/platform/v1/organizations/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
[
  {
    "name": "TestCollection",
    "owner_id": 0,
    "display_name": "Default TestCollection",
    "context_callback_url": "http://192.168.178.78:80/",
    "context_callback_used": true,
    "profile_callback_url": "http://192.168.178.78:80/",
    "profile_callback_used": true,
    "created_at": "2021-02-19T15:29:58.939435",
    "id": 1
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/organizations/consumption/ \
     --header 'Accept: application/json'
[
  {
    "number_of_assets": {
      "2020-9": 1
    },
    "number_of_calls": {
      "2020-9": 2
    }
  }
]
curl --request GET \
     --url 'https://api.motion-s.com/platform/v1/fleets/?skip=0&limit=100' \
     --header 'Accept: application/json'
[
  [
    {
      "organization_fleet_identifier": "default_api_fleet_identifier",
      "name": "default_api_fleet",
      "display_name": "Default API fleet",
      "organization_id": 1,
      "created_at": "2021-02-19T15:29:58.946709",
      "id": 1,
      "fleet_type": "teltonika"
    },
    {
      "organization_fleet_identifier": "default_app_fleet_identifier",
      "name": "default_app_fleet",
      "display_name": "Default APP fleet",
      "organization_id": 1,
      "pin_code": "638106",
      "created_at": "2021-02-19T15:30:58.946709",
      "id": 2,
      "fleet_type": "default"
    }
  ]
]

Access management

Keys

An API key is used to access API endpoints by setting it in the header or query parameters of the requests you send. Organizations can have an unlimited number of API keys, you can only create API keys using your user credentials.

curl --request POST \
     --url https://api.motion-s.com/platform/v1/keys/ \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "key": "1dd3cd65-c15a-4feb-96b4-2ebe3d49f31b",
    "is_valid": true,
    "created_at": "2021-02-19T15:49:49.118871",
    "organization_id": 1,
    "id": 1
  }
]

Sessions

Users can create a session that represents logging into our system. As a response, you will get an access token and refresh token, with which you can access API endpoints by setting the access token in the headers or query parameters of the request being sent.

Authentication

The authentication can be done using:

  • Access token
    • In the header as bearer token: Authorization: Bearer <access_token>
    • In the query parameters using keyword access_token
  • API key
    • In the header using API key authorization (X-Api-Key)
    • In the query parameters using keyword api_key
curl --request POST \
     --url https://api.motion-s.com/platform/v1/sessions/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJOc21ZVlltQWF0SnJNL",
    "expires_in": "300",
    "refresh_expires_in": "1800",
    "refresh_token": "yJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiM2I0OWJiNC05YjFlL",
    "token_type": "bearer"
  }
]
curl --request POST \
     --url https://api.motion-s.com/platform/v1/sessions/logout \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
curl --request POST \
     --url https://api.motion-s.com/platform/v1/sessions/refresh_token/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJOc21ZVlltQWF0SnJNL",
    "expires_in": "300",
    "refresh_expires_in": "1800",
    "refresh_token": "yJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiM2I0OWJiNC05YjFlL",
    "token_type": "bearer"
  }
]

Entity management

Fleet

A fleet represents a collection of devices. One organization can create multiple fleets. At the start, you will get the default fleet created by us.

curl --request POST \
     --url https://api.motion-s.com/platform/v1/fleets/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: <Your API Key>' \
     --data '
{
     "fleet_type": "default"
}
'
[
  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJOc21ZVlltQWF0SnJNL",
    "expires_in": "300",
    "refresh_expires_in": "1800",
    "refresh_token": "yJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiM2I0OWJiNC05YjFlL",
    "token_type": "bearer"
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/fleets/fleet_id/ \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_fleet_identifier": "default_api_fleet_identifier",
    "name": "default_api_fleet",
    "display_name": "Default API fleet",
    "organization_id": 1,
    "created_at": "2021-02-19T15:29:58.946709",
    "id": 1,
    "fleet_type": "teltonika"
  },
  {
    "organization_fleet_identifier": "default_app_fleet_identifier",
    "name": "default_app_fleet",
    "display_name": "Default APP fleet",
    "organization_id": 1,
    "pin_code": "638106",
    "created_at": "2021-02-19T15:30:58.946709",
    "id": 2,
    "fleet_type": "default"
  }
]
curl --request PATCH \
     --url https://api.motion-s.com/platform/v1/fleets/fleet_id/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: <Your API Key>' \
     --data '
{
     "fleet_type": "default"
}
'
[
  {
    "organization_fleet_identifier": "default_api_fleet_identifier",
    "name": "default_api_fleet",
    "display_name": "Default API fleet",
    "organization_id": 1,
    "created_at": "2021-02-19T15:29:58.946709",
    "id": 1,
    "fleet_type": "teltonika"
  },
  {
    "organization_fleet_identifier": "default_app_fleet_identifier",
    "name": "default_app_fleet",
    "display_name": "Default APP fleet",
    "organization_id": 1,
    "pin_code": "638106",
    "created_at": "2021-02-19T15:30:58.946709",
    "id": 2,
    "fleet_type": "default"
  }
]

Devices

The device represents the actual device that recorded the trip. This is a mandatory field when submitting a trip.

curl --request POST \
     --url 'https://api.motion-s.com/platform/v1/devices/?app_request=false' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_device_identifier": "org-device-identifier",
    "name": "SM-A720F",
    "os": "Android",
    "version": "8.0.0",
    "fleet_id": 1,
    "created_at": "2021-02-22T10:24:12.864978",
    "metadata": {
      "plate_number": "23HY7D"
    },
    "id": 1
  }
]
curl --request GET \
     --url 'https://api.motion-s.com/platform/v1/devices/?skip=0&limit=100' \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  [
    {
      "organization_device_identifier": "org-device-identifier",
      "name": "SM-A720F",
      "os": "Android",
      "version": "8.0.0",
      "fleet_id": 1,
      "created_at": "2021-02-22T10:24:12.864978",
      "metadata": {
        "plate_number": "23HY7D"
      },
      "id": 1
    }
  ]
]
curl --request GET \
     --url 'https://api.motion-s.com/platform/v1/devices/device_id?app_request=false' \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_device_identifier": "org-device-identifier",
    "name": "SM-A720F",
    "os": "Android",
    "version": "8.0.0",
    "fleet_id": 1,
    "created_at": "2021-02-22T10:24:12.864978",
    "metadata": {
      "plate_number": "23HY7D"
    },
    "id": 1
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/devices/organization_device_identifier/organization_device_identifier \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_device_identifier": "org-device-identifier",
    "name": "SM-A720F",
    "os": "Android",
    "version": "8.0.0",
    "fleet_id": 1,
    "created_at": "2021-02-22T10:24:12.864978",
    "metadata": {
      "plate_number": "23HY7D"
    },
    "id": 1
  }
]
curl --request PATCH \
     --url 'https://api.motion-s.com/platform/v1/devices/device_id/?app_request=false' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_device_identifier": "org-device-identifier",
    "name": "SM-A720F",
    "os": "Android",
    "version": "8.0.0",
    "fleet_id": 1,
    "created_at": "2021-02-22T10:24:12.864978",
    "metadata": {
      "plate_number": "23HY7D"
    },
    "id": 1
  }
]

Driver

The driver represents a person that is creating a trip. It is not mandatory when submitting the trip to our platform, but providing the device is mandatory.

curl --request POST \
     --url https://api.motion-s.com/platform/v1/drivers/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "username": "test-marko",
    "name": "test-marko",
    "email": "[email protected]",
    "phone_number": "+352 33333333",
    "app_driver": false,
    "created_at": "2021-02-22T09:28:56.287862",
    "updated_at": "2021-02-22T09:28:56.287862",
    "id": 1
  }
]
curl --request GET \
     --url 'https://api.motion-s.com/platform/v1/drivers/?skip=0&limit=100' \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  [
    {
      "username": "test-driver-1",
      "name": "test-driver-1",
      "email": "[email protected]",
      "phone_number": "+352 4444444444",
      "organization_driver_identifier": "Driver 1"
    }
  ]
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/drivers/username \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "username": "test-marko",
    "name": "test-marko",
    "email": "[email protected]",
    "phone_number": "+352 33333333",
    "app_driver": false,
    "created_at": "2021-02-22T09:28:56.287862",
    "updated_at": "2021-02-22T09:28:56.287862",
    "id": 1
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/drivers/organization_driver_identifier/organization_driver_identifier \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "username": "test-marko",
    "name": "test-marko",
    "email": "[email protected]",
    "phone_number": "+352 33333333",
    "app_driver": false,
    "created_at": "2021-02-22T09:28:56.287862",
    "updated_at": "2021-02-22T09:28:56.287862",
    "id": 1
  }
]
curl --request PUT \
     --url https://api.motion-s.com/platform/v1/drivers/driver_id \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "username": "test-marko",
    "name": "test-marko",
    "email": "[email protected]",
    "phone_number": "+352 33333333",
    "app_driver": false,
    "created_at": "2021-02-22T09:28:56.287862",
    "updated_at": "2021-02-22T09:28:56.287862",
    "id": 1
  }
]
curl --request DELETE \
     --url https://api.motion-s.com/platform/v1/drivers/driver_id \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "username": "test-marko",
    "name": "test-marko",
    "email": "[email protected]",
    "phone_number": "+352 33333333",
    "app_driver": false,
    "created_at": "2021-02-22T09:28:56.287862",
    "updated_at": "2021-02-22T09:28:56.287862",
    "id": 1
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/drivers/driver_id/devices \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  [
    {
      "organization_device_identifier": "org-device-identifier",
      "name": "SM-A720F",
      "os": "Android",
      "version": "8.0.0",
      "fleet_id": 1,
      "created_at": "2021-02-22T10:24:12.864978",
      "metadata": {
        "plate_number": "23HY7D"
      },
      "id": 1
    }
  ]
]

Vehicles

The vehicle represents the actual vehicle with its specific details.

curl --request POST \
     --url https://api.motion-s.com/platform/v1/vehicles/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --header 'X-Api-Key: <Your API Key>'
{
  "organization_vehicle_identifier": "string",
  "brand": "string",
  "model": "string",
  "engine": "string",
  "organization_id": 0,
  "created_at": "2022-02-23T07:56:23.002Z",
  "id": 0
}
curl --request GET \
     --url 'https://api.motion-s.com/platform/v1/vehicles/?skip=0&limit=100' \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
[
  {
    "organization_vehicle_identifier": "string",
    "brand": "string",
    "model": "string",
    "engine": "string",
    "organization_id": 0,
    "created_at": "2022-02-23T07:56:23.002Z",
    "id": 0
  }
]
curl --request GET \
     --url https://api.motion-s.com/platform/v1/vehicles/vehicle_id \
     --header 'Accept: application/json'
     --header 'X-Api-Key: <Your API Key>'
{
  "organization_vehicle_identifier": "string",
  "brand": "string",
  "model": "string",
  "engine": "string",
  "organization_id": 0,
  "created_at": "2022-02-23T07:56:23.002Z",
  "id": 0
}