Introduction

The Skadii API is organized around REST. The API has resource oriented URLs, returns JSON encoded reponses and uses standard HTTP methods, response codes and authentication.

You can view code examples in the area to the right.

Please note that our API description covers everything that's potentially available, but specific features may differ depending on a customer's individual setup. If you have any questions or requests, please contact us and we'll provide you with further information.

Authentication

The Skadii API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials.

The process involves the following steps:

curl "https://auth.skadii.digital/oauth/token" -X POST

{
  "audience": "iot",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

1. Acquire an `access_token`

It is important that you keep the Client Secret secure, you MUST not share it publicly and you MUST not use it in client side code.

Request

POST https://auth.skadii.digital/oauth/token

Body

Parameter	Description	Format
audience	Api type. Must be `iot`.	string
grant_type	The type of credentials you're asking for. Must be `client_credentials`.	string
client_id	UUID representing your client id.	string
client_secret	The actual `Client Secret`. Must NOT be shared publicly.	string

Response

Parameter	Description	Format
access_token	JWT.	string
token_type	Token type. Will be `Bearer`	string
expires_in	Number of seconds until expiry eg. `86400`.	int

curl "https://api.skadii.digital/iot/v1/resorts" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
# Make sure to replace {ACCESS_TOKEN} with your Access Token.

2. Use the `access_token` to make authenticated requests

Authentication to the API is performed via Bearer Auth.

Use -h "Authorization: Bearer {ACCESS_TOKEN}". All API requests must be made over HTTPS.

Correlation Id

curl "https://api.skadii.digital/iot/v1/resorts" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Correlation-Id: {UUID}"
# Make sure to replace {UUID} with a random UUID.

Each API request should include a correlation id (a unique, randomly generated UUID) that allow to reference a particular request.

You can provide it via the X-Correlation-ID header: -h "X-Correlation-ID: {UUID}. If not provided it will be generated on the server.

Every response will have a Correlation ID.

Resorts

Get Resorts

curl "https://api.skadii.digital/iot/v1/resorts" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Correlation-Id: {UUID}"

{
  "data": [
    {
      "id": "4236ec11-1176-4fdf-af0e-5d17c0813831",
      "name": "Ski Resort Good Weather",
      "country": "IT",
      "timezone": "Europe/Rome",
      "plants": [
        {
          "id": "c7694ef6-a379-4725-892b-a8c4c05e44eb",
          "name": "Always Sunny Plant",
          "things": [
            {
              "id": "7e7f6616-7f55-4edd-8208-2c46a9ea972f",
              "name": "Sunny Ropeway",
              "type": "ropeway",
              "geo_position": "LINESTRING Z(11.07772922502772 47.3034717801813 500,11.08022689858626 47.30389666097983 510,11.081711769104002 47.303983964839716 520)"
            },
            {
              "id": "61f4ff99-1440-4353-a758-36fd2e80fe99",
              "name": "Wind Station Amazing View",
              "type": "wind_station",
              "geo_position": "POINT(11.080467147962983 47.3037254347031)"
            },
            {
              "id": "d091d9cf-e493-4fc7-aa62-44c5d6a8f46d",
              "name": "Strong groomer",
              "type": "vehicle",
              "metadata":
              {
                "internal_customer_id": "4029"
              }
            }
          ]
        }
      ]
    }
  ]
}

This endpoint retrieves your resorts.

Request

GET https://api.skadii.digital/iot/v1/resorts

Response

Parameter	Description	Format
id	UUID representing the id of the ropeway.	string
name	The resort name.	string
country	Two-letter ISO code representing the country of the resort.	string
timezone	The timezone of the resort.	string
plants.[].id	UUID representing the id of the plant.	string
plants.[].name	The plant name.	string
plants.[].things.[].id	UUID representing the id of the thing.	string
plants.[].things.[].name	The thing name.	string
plants.[].things.[].type	The thing type (eg. ropeway, wind_station, meteo_station, vehicle, ...).	string
plants.[].things.[].geo_position	The thing position in WKT format.	string optional
plants.[].things.[].metadata	Set of key-value pairs for additional, structured information on an object. For example your unique identifier from your system.	object optional

Assets

Get Assets

curl "https://api.skadii.digital/iot/v1/assets" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Correlation-Id: {UUID}"

{
  "data": [
    {
      "id": "7e7f6616-7f55-4edd-8208-2c46a9ea972f",
      "name": "Sunny Ropeway",
      "type": "ropeway",
      "geo_position": "LINESTRING Z(11.07772922502772 47.3034717801813 500,11.08022689858626 47.30389666097983 510,11.081711769104002 47.303983964839716 520)"
    },
    {
      "id": "61f4ff99-1440-4353-a758-36fd2e80fe99",
      "name": "Wind Station Amazing View",
      "type": "wind_station",
      "geo_position": "POINT(11.080467147962983 47.3037254347031)"
    },
    {
      "id": "d091d9cf-e493-4fc7-aa62-44c5d6a8f46d",
      "name": "Strong groomer",
      "type": "vehicle",
      "metadata":
      {
        "internal_customer_id": "4029"
      }
    }
  ]
}

This endpoint retrieves your available assets.

Request

GET https://api.skadii.digital/iot/v1/assets

Response

Parameter	Description	Format
data.[].id	UUID representing the id of the asset.	string
data.[].name	The asset name.	string
data.[].type	The asset type (eg. ropeway, wind_station, meteo_station, vehicle, ...).	string
data.[].geo_position	The asset position in WKT format.	string optional
data.[].metadata	Set of key-value pairs for additional, structured information on an object. For example your unique identifier from your system.	object optional

Get Sensor Information

curl "https://api.skadii.digital/iot/v1/assets/04d24f09-817e-4008-8748-5da0e1304c61/sensors" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Correlation-Id: {UUID}"

{
  "id": "04d24f09-817e-4008-8748-5da0e1304c61",
  "data": [
    {
      "id": "e64cb70c-2759-4205-869a-f51da1d9a72c",
      "type": "operating_hours",
      "name": "vehicle operating hours",
      "unit": "hours"
    },
    {
      "id": "26ae52ee-086b-4853-9b1a-7fdaf9950ea0",
      "type": "winch_hours",
      "name": "vehicle winch hours",
      "unit": "hours"
    }
  ]
}

This endpoint retrieves detailed sensors information of an asset. This information is normally static and should only change when sensors are getting added or removed to an asset.

Request

GET https://api.skadii.digital/iot/v1/assets/:id/sensors

Response

Parameter	Description	Format
id	UUID representing the id of the asset (could be a ropeway, vehicle, snowmaker, ...).	string
data.[].id	UUID representing the id of the sensor.	string
data.[].type	the type of the sensor. One of `operating_hours`, `winch_hours`	string
data.[].name	the name of the sensor.	string optional
data.[].unit	the unit of the value the sensor is transmitting.	string optional
data.[].schema	the data type of the sensor.	string optional

Ropeways

Get Ropeway Summary Data

curl "https://api.skadii.digital/iot/v1/ropeways/ce374b1e-60e9-4225-b2ec-93bba7b8b2fe/data/summary?end=2021-11-08T22:00:00Z" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Correlation-Id: {UUID}"

{
  "id": "ce374b1e-60e9-4225-b2ec-93bba7b8b2fe",
  "data": [
    {
      "end": "2021-11-08T22:00:00Z",
      "ropeway_state": {
        "operating_hours": 2964.4,
        "distance_rope_forward": 348.2,
        "distance_rope_backward": 76.8,
        "vehicle_clamping_counter": 312
      }
    }
  ]
}

This endpoint retrieves summary data of a ropeway.

Request

GET https://api.skadii.digital/iot/v1/ropeways/:id/data/summary{?end}

Parameter	Description	Format
end	ISO date/time representing the end of the interested time period.	string optional

Response

Parameter	Description	Format
id	UUID representing the id of the ropeway.	string
data.[].end	ISO date/time representing the end time of the period.	string
data.[].ropeway_state.operating_hours	the operating hours of the ropeway.	decimal optional
data.[].ropeway_state.distance_rope_forward	the forward distance of the rope in meter.	decimal optional
data.[].ropeway_state.distance_rope_backward	the backward distance of the rope in meter.	decimal optional
data.[].ropeway_state.vehicle_clamping_counter	the vehicle clamping counter.	integer optional

Vehicles

Get Vehicle Summary Data

curl "https://api.skadii.digital/iot/v1/vehicles/2b39862c-178e-4fad-b379-9f628a86dae6/data/summary?start=2021-11-08T20:00:00Z&end=2021-11-08T22:00:00Z&interval=3600" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Correlation-Id: {UUID}"

{
  "id": "2b39862c-178e-4fad-b379-9f628a86dae6",
  "data": [
    {
      "start": "2021-11-08T20:00:00Z",
      "end": "2021-11-08T21:00:00Z",
      "vehicle_state": {
        "duration_on": 2400,
        "duration_idle": 720,
        "duration_moving": 1680,
        "max_speed": 14,
        "avg_speed": 6,
        "fuel_consumption": 8,
        "distance": 38
      }
    },
    {
      "start": "2021-11-08T21:00:00Z",
      "end": "2021-11-08T22:00:00Z",
      "vehicle_state": {
        "duration_on": 1200,
        "duration_idle": 800,
        "duration_moving": 400,
        "max_speed": 12,
        "avg_speed": 4,
        "fuel_consumption": 7,
        "distance": 15
      }
    }
  ]
}

This endpoint retrieves summary data of a vehicle.

Request

GET https://api.skadii.digital/iot/v1/vehicles/:id/data/summary{?start,end,interval}

Parameter	Description	Format
start	ISO date/time representing the start of the interested time period.	string
end	ISO date/time representing the end of the interested time period.	string
interval	Representing the time interval of the summary in seconds eg. 3600 for hourly. Max summary count is 31	integer optional

Response

Parameter	Description	Format
id	UUID representing the id of the vehicle.	string
data.[].start	ISO date/time representing the start time of the period.	string
data.[].end	ISO date/time representing the end time of the period.	string
data.[].vehicle_state.duration_on	the vehicle was on in seconds.	integer optional
data.[].vehicle_state.duration_idle	the vehicle was on and idle in seconds.	integer optional
data.[].vehicle_state.duration_moving	the vehicle was on and moving in seconds.	integer optional
data.[].vehicle_state.max_speed	the maximum speed of the vehicle in m/s.	decimal optional
data.[].vehicle_state.avg_speed	the average speed of the vehicle in m/s.	decimal optional
data.[].vehicle_state.fuel_consumption	the fuel consumption of the vehicle in liters.	decimal optional
data.[].vehicle_state.distance	the distance driven in meters.	integer optional
data.[].vehicle_state.winch_duration_on	the winch was on in seconds.	integer optional
data.[].vehicle_state.surface_driven	the total surface driven in m².	decimal optional
data.[].vehicle_state.surface_worked	the surface worked in m².	decimal optional

Sensors

Get Sensor Information [DEPRECATED]

Please use the Get Sensor Information call inside Assets section.

curl "https://api.skadii.digital/iot/v1/sensors/04d24f09-817e-4008-8748-5da0e1304c61/info" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Correlation-Id: {UUID}"

{
  "id": "04d24f09-817e-4008-8748-5da0e1304c61",
  "data": [
    {
      "id": "e64cb70c-2759-4205-869a-f51da1d9a72c",
      "type": "operating_hours",
      "name": "vehicle operating hours",
      "unit": "hours"
    },
    {
      "id": "26ae52ee-086b-4853-9b1a-7fdaf9950ea0",
      "type": "winch_hours",
      "name": "vehicle winch hours",
      "unit": "hours"
    }
  ]
}

This endpoint retrieves detailed sensors information. This information is normally static and should only change when sensors are getting added or removed.

Request

GET https://api.skadii.digital/iot/v1/sensors/:id/info

Response

Parameter	Description	Format
id	UUID representing the id of the ropeway.	string
data.[].id	UUID representing the id of the sensor.	string
data.[].type	the type of the sensor. One of `operating_hours`, `winch_hours`	string
data.[].name	the name of the sensor.	string optional
data.[].unit	the unit of the value the sensor is transmitting.	string optional
data.[].schema	the data type of the sensor.	string optional

Get Sensor Data

curl "https://api.skadii.digital/iot/v1/sensors/e64cb70c-2759-4205-869a-f51da1d9a72c/data?datetime=2021-11-08T22:00:00Z" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Correlation-Id: {UUID}"

{
  "id": "e64cb70c-2759-4205-869a-f51da1d9a72c",
  "date_time": "2021-11-08T22:00:00Z",
  "data": [
    {
      "value": 1000,
      "timestamp": "2021-11-08T20:59:00.000Z"
    }
  ]
}

This endpoint retrieves recorded sensor data. You can use it in the following ways:

Using the datetime query parameter:
- Retrieve the latest value recorded on or before the provided datetime
- Example: ?datetime=2021-11-08T22:00:00Z
Using the start and end query parameters:
- Retrieve values recorded within the specified range
- Example: ?start=2021-11-08T00:00:00Z&end=2021-11-08T23:59:59Z

Important Notes:

The datetime parameter cannot be used in combination with the start and end parameters.
There can be a delay for the latest value(s) to be available.

Request

GET https://api.skadii.digital/iot/v1/sensors/:id/data{?datetime, start, end}

Parameter	Description	Format
datetime	ISO date/time representing of the interested time period (inclusive). Also value cannot be older than 24 hours from current date time.	string
start	ISO date/time representing the start of the interested time period (inclusive). Also value cannot be more than 24 hours from current date time.	string
end	ISO date/time representing the end of the interested time period (exclusive). Has to be greater than start. Default value is now.	string

Response

Parameter	Description	Format
id	UUID representing the id of the sensor.	string
date_time	ISO date/time representing of the entry inside the requested time period.	string
data.[].value	the value of the sensor.	object
data.[].timestamp	ISO date/time representing the acquisition time of the data point.	string optional

Errors

The Skadii API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- You don't have enough rights to access the resource.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're requesting too many requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Introduction

Authentication

1. Acquire an access_token

Request

Body

Response

2. Use the access_token to make authenticated requests

Correlation Id

Resorts

Get Resorts

Request

Response

Assets

Get Assets

Request

Response

Get Sensor Information

Request

Response

Ropeways

Get Ropeway Summary Data

Request

Response

Vehicles

Get Vehicle Summary Data

Request

Response

Sensors

Get Sensor Information [DEPRECATED]

Request

Response

Get Sensor Data

Request

Response

Errors

1. Acquire an `access_token`

2. Use the `access_token` to make authenticated requests