Onemap8

Devices

The main artifact of the system is the device. A device is a physical or virtual entity that can be tracked, monitored and controlled.

Devices are managed by the system and can be assigned to users and groups.

The Devices Model

A devices is represented by the following schema:

Scheme

  • Name
    id
    Type
    integer
    Description
  • Name
    name
    Type
    string
    Description
  • Name
    uniqueId
    Type
    string
    Description
  • Name
    status
    Type
    string
    Description
  • Name
    disabled
    Type
    boolean
    Description
  • Name
    lastUpdate
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    positionId
    Type
    integer
    Description
  • Name
    groupId
    Type
    integer
    Description
  • Name
    phone
    Type
    string
    Description
  • Name
    model
    Type
    string
    Description
  • Name
    contact
    Type
    string
    Description
  • Name
    category
    Type
    string
    Description
  • Name
    attributes
    Type
    object
    Description
GET/devices

Retrieve devices information

Without any params, returns a list of the user's devices

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Query Parameters

  • Name
    all
    Type
    boolean
    Description
    Can only be used by administrators or managers to retrieve all Device objects.
  • Name
    userId
    Type
    integer
    Description
    Standard users can use this only with their own userId
  • Name
    id
    Type
    integer
    Description
    To fetch one or more devices. Multiple params can be passed like id=1&id=2
  • Name
    uniqueId
    Type
    string
    Description
    To fetch one or more devices. Multiple params can be passed like uniqueId=1&uniqueId=2
  • Name
    excludeAttributes
    Type
    boolean
    Description
    Exclude attributes field from device payload
  • Name
    limit
    Type
    integer
    Description
    Limit the number of returned results
  • Name
    offset
    Type
    integer
    Description
    Offset for pagination
  • Name
    keyword
    Type
    string
    Description
    Search keyword filter (searches name, uniqueId, phone, model, contact)

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Array of Device
  • Name
    400
    Type
    error
    Description
    Not permission

Request

GET
/devices
curl --location 'https://gw.onemap8.com/api/devices?all=<boolean>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

[
{
"id": 0,
"name": "string",
"uniqueId": "string",
"status": "string",
"disabled": true,
"lastUpdate": "2019-08-24T14:15:22Z",
"positionId": 0,
"groupId": 0,
"phone": "string",
"model": "string",
"contact": "string",
"category": "string",
"attributes": { }
},
{
...
}
]
POST/devices

Create a device

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
  • Name
    name
    Type
    string
    Description
  • Name
    uniqueId
    Type
    string
    Description
  • Name
    status
    Type
    string
    Description
  • Name
    disabled
    Type
    boolean
    Description
  • Name
    lastUpdate
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    positionId
    Type
    integer
    Description
  • Name
    groupId
    Type
    integer
    Description
  • Name
    phone
    Type
    string
    Description
  • Name
    model
    Type
    string
    Description
  • Name
    contact
    Type
    string
    Description
  • Name
    category
    Type
    string
    Description
  • Name
    attributes
    Type
    object
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Device

Request

POST
/devices
curl --location 'https://gw.onemap8.com/api/devices' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"uniqueId": "<string>",
"status": "<string>",
"disabled": "<boolean>",
"lastUpdate": "<dateTime>",
"positionId": "<integer>",
"groupId": "<integer>",
"phone": "<string>",
"model": "<string>",
"contact": "<string>",
"category": "<string>",
"attributes": {}
}'

Response

{
"id": 0,
"name": "string",
"uniqueId": "string",
"status": "string",
"disabled": true,
"lastUpdate": "2019-08-24T14:15:22Z",
"positionId": 0,
"groupId": 0,
"phone": "string",
"model": "string",
"contact": "string",
"category": "string",
"attributes": { }
}
PUT/devices/{id}

Update a device

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer
    Description
    required

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
  • Name
    name
    Type
    string
    Description
  • Name
    uniqueId
    Type
    string
    Description
  • Name
    status
    Type
    string
    Description
  • Name
    disabled
    Type
    boolean
    Description
  • Name
    lastUpdate
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    positionId
    Type
    integer
    Description
  • Name
    groupId
    Type
    integer
    Description
  • Name
    phone
    Type
    string
    Description
  • Name
    model
    Type
    string
    Description
  • Name
    contact
    Type
    string
    Description
  • Name
    category
    Type
    string
    Description
  • Name
    attributes
    Type
    object
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Device

Request

PUT
/devices/{id}
curl --location --request PUT 'https://gw.onemap8.com/api/devices/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"uniqueId": "<string>",
"status": "<string>",
"disabled": "<boolean>",
"lastUpdate": "<dateTime>",
"positionId": "<integer>",
"groupId": "<integer>",
"phone": "<string>",
"model": "<string>",
"contact": "<string>",
"category": "<string>",
"attributes": {}
}'

Response

{
"id": 0,
"name": "string",
"email": "string",
"phone": "string",
"readonly": true,
"administrator": true,
"map": "string",
"latitude": 0,
"longitude": 0,
"zoom": 0,
"password": "string",
"coordinateFormat": "string",
"disabled": true,
"expirationTime": "2019-08-24T14:15:22Z",
"deviceLimit": 0,
"userLimit": 0,
"deviceReadonly": true,
"limitCommands": true,
"fixedEmail": true,
"poiLayer": "string",
"attributes": { }
}
DELETE/devices/{id}

Delete a device

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer
    Description
    required

Responses

  • Name
    204
    Type
    success
    Description
    No content

Request

DELETE
/devices/{id}
curl --location --request DELETE 'https://gw.onemap8.com/api/devices/<integer>' \
--header 'Authorization: Basic {your_access_token}'

Response

No content
PUT/devices/{id}/accumulators

Update device accumulators

Update total distance and hours of the Device.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description
    Device ID

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    deviceId
    Type
    integer
    Description
    Device identifier for the accumulator entry
  • Name
    totalDistance
    Type
    number
    Description
    Total distance in meters
  • Name
    hours
    Type
    number
    Description
    Total engine hours recorded by the device

Responses

  • Name
    204
    Type
    success
    Description
    No content

Request

PUT
/devices/{id}/accumulators
curl --location --request PUT 'https://gw.onemap8.com/api/devices/<integer>/accumulators' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"deviceId": <integer>,
"totalDistance": <number>,
"hours": <number>
}'

Response

No content
POST/devices/{id}/image

Upload device image

Upload or update a device image. The image will be stored and associated with the device.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description
    Device ID

Request body schema

  • Name
    image/*
    Type
    schema
    Description
    Binary image data (JPEG, PNG, etc.)

Responses

  • Name
    200
    Type
    success
    Description
  • Name
    text/plain
    Type
    response schema
    Description

    • Filename of the uploaded image (e.g., device.png)

  • Name
    400
    Type
    error
    Description
    Invalid image type or size
  • Name
    404
    Type
    error
    Description
    Device not found

Request

POST
/devices/{id}/image
curl --location 'https://gw.onemap8.com/api/devices/<integer>/image' \
--header 'Content-Type: image/png' \
--header 'Authorization: Basic {your_access_token}' \
--data-binary '@/path/to/image.png'

Response

device.png
GET/devices/{id}

Fetch a Device

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Device
  • Name
    401
    Type
    error
    Description
    Unauthorized
  • Name
    404
    Type
    error
    Description
    Not found

Request

GET
/devices/{id}
curl --location 'https://gw.onemap8.com/api/devices/<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"status": "<string>",
"disabled": true,
"lastUpdate": "<date-time>",
"positionId": "<int64>",
"groupId": "<int64>",
"phone": "<string>",
"model": "<string>",
"contact": "<string>",
"category": "<string>",
"attributes": {}
}