SPARC API

Introduction

Sparc 2.0 is the new generation Sparc API.

The Interface is built on top of JSON-RPC 2.0 and can be used in a synchronous manner with HTTP POST requests to http://api.gosparc.com/2.0 or asynchronous with Web Sockets at ws://api.gosparc.com/2.0. Only WebSockets transport allows for notifications.

Requests must be JSON objects with following structure:

  • jsonrpc

    String, required, always equal '2.0'

  • id

    Number or String, required, used to match request and response.

  • method

    String, required. The name of the method to call. See below for a list of supported methods.

  • params

    Object, required. Only two allowed properties are:

    • transaction

      Object. Contains transaction specific data. Most significant use is transferring an authorization token. See authentication for more info.

      Also on supported transports client can subscribe to further notifications on the requested data by setting transaction.watch to true. See notifications.

    • args

      any value, optional. Method specific arguments. Consult each methods documentation for arguments structure.

Resources, Actions, Grants and Authorization Scopes

The semantics of the API revolves around the concept of resources and actions. Resources are:

  • Account

  • API Keys

    Associated with an Account and used to authenticate.

  • Devices

    Physical SPARC devices owned by the customer and operated by GoSparc.

  • Vehicles

    Vehicles registered by the customer.

  • drivers

    Drivers, passengers etc.

  • Routes

    Associated with vehicle, device and driver.

  • Parkings

    Associated with vehicle, device and driver.

  • Geofences

    A geofence. May be used for notifications.

Each resource has a set of properties and actions that can be performed on it, like create, list, modify, register, revoke. Properties can only be modified by performing actions. In most cases there are create and modify actions specifically for that. If a property is described as RW it can be modified using those actions. If it's marked as RO it either cannot be modified using the API or can be modified indirectly, by performing other actions. Most such cases are discussed in appropriate section of this document.

This basic ontology is reflected in:

  • method names

    e.g.: create keys, register vehicles

  • grants and authorization scopes

    API keys have associated grants, that may look like this:

      grants:
        vehicles: ['list', 'locate']
        parkings: ['list']
    

    When client authenticates, it claims the authorization scope, that has to fit in grants of a key being used, e.g.:

      scope:
        vehicles: ['list']
    

Tags

For additional flexibility any resource (except for the Account) can be tagged with a set of Strings.

The create and modify methods accept additional optional argument: tags - an array of Strings.

Query methods (list, locate, etc.) also accept tags argument. The result will be filtered against this Array.

Notifications

By setting the watch property of a transaction to true the client is subscribing to notifications about future changes to the data set. Each notification will have an id property matching the request id. There will be no jsonrpc property, as notifications are not compatible with this protocol.

Example:

Request:

{
  "jsonrpc": "2.0",
  "id": 111,
  "method": "get fences",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg==",
      "watch": true
    },
    "args": {
      "id": "8a4196b3-ff80-4b53-8035-66858325827b"
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 111,
  "result": {
    "data": {
      "fences": {
        "8a4196b3-ff80-4b53-8035-66858325827b": {
          "center": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                12.2344,
                52.3242
              ],
              "properties": {}
            }
          },
          "radius": 150,
          "vehicles": {
            "6ef69dd0-7864-4320-a510-e1446924a899": {
              "plate": "abcd123"
            },
            "8ae01010-0339-4811-924e-f71d0ce7bc40": {
              "plate": "fghi654"
            }
          }
        }
      }
    }
  }
}

Car with a plate fghi654 left the fence:

Notification:

{
  "id": 111,
  "result": {
    "data": {
      "fences": {
        "8ae01010-0339-4811-924e-f71d0ce7bc40": {
          "center": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                12.2344,
                52.3242
              ],
              "properties": {}
            }
          },
          "radius": 150,
          "vehicles": {
            "30ebebc9-34ad-4f0e-a813-c14b87d7cb9b": {
              "plate": "abcd123"
            }
          }
        }
      }
    }
  }
}

Car with a plate jklm456 entered the fence:

Notification:

{
  "id": 111,
  "result": {
    "data": {
      "fences": {
        "30ebebc9-34ad-4f0e-a813-c14b87d7cb9b": {
          "center": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                12.2344,
                52.3242
              ],
              "properties": {}
            }
          },
          "radius": 150,
          "vehicles": {
            "c850ffa4-a73d-4e31-a973-d00829ca07ad": {
              "plate": "abcd123"
            },
            "305e84fd-2b15-453a-90ef-e71bdc386d55": {
              "plate": "mkl456"
            }
          }
        }
      }
    }
  }
}

Authentication

The system uses AES-256 encrypted (JWT) tokens for authentication. In order to obtain a token client calls a get token method, providing following arguments:

  • apikey

    String, required. The master key of the account (provided to the customer when the account is created), or a key created by the account administrator using the master key or other key with keys: create grant. See API Keys Management for more information on keys.

  • account

    String, required. Customers account id.

  • scope

    Object or String, required. Authorization scope for the requested token. Each action has required authorization scope that must be covered by scope of the token. Scope must fit into grants of a key being used.

    In canonical form it is an Object with property names indicating resources, e.g. vehicles, drivers. The values of properties are Arrays of Strings, each string being the name of the action that a user can perform with the requested token, e.g. list, locate, create. See Resources, Actions, Grants and Authorization Scopes for an overview.

    There is a special wildcard scope described with '*' string. It will request a scope equal to the grants of the key. For security reasons we discourage using this feature.

Request:

{
  "jsonrpc": "2.0",
  "id": 112,
  "method": "get token",
  "params": {
    "args": {
      "apikey": "4bef81d1-52ae-4473-9f77-e567bc63366c",
      "account": "cd2c6ab1-03dc-42b6-aa75-36a9513e1615",
      "scope": {
        "keys": [
          "list",
          "create",
          "revoke"
        ],
        "vehicles": [
          "list",
          "locate",
          "register",
          "unregister"
        ]
      }
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 112,
  "result": {
    "data": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    }
  }
}

The received token will have to be used in all subsequent JSON-RPC requests in order to perform operations. For security reasons tokens expire after 5 minutes. In a typical session new token will be obtained more then once.

Example of an invalid authentication:

Request:

{
  "jsonrpc": "2.0",
  "id": 113,
  "method": "get token",
  "params": {
    "args": {
      "apikey": "invalid",
      "account": "b820ccb8-0a64-4e5b-941b-f0480d8453f0",
      "scope": {
        "keys": [
          "create"
        ]
      }
    }
  }
}

Error response:

{
  "jsonrpc": "2.0",
  "id": 113,
  "error": {
    "code": "401",
    "message": "Invalid account or API key provided"
  }
}

API Keys

Each customer can have multiple API keys with different grants. Keys with the keys: create grant can create new keys, with privileges equal or lower to their own.

Upon creation of an account a master key is assigned to it and delivered to the customer. This first key can (and for security reasons should) be used to create subsequent keys with lower grants. Only this keys should be used in day to day interaction with the API.

Properties

  • grants (RW Object)

Actions

  • create keys

  • list keys

  • revoke keys

Create keys

It is possible to create new API keys after obtaining a token with keys: create in it's scope. The grants of newly created keys cannot be broader then the scope of a token used (which in turn cannot be broader then the grants of the original key).

We strongly advise customers to create keys with limited scope and only use those to interact with the API. The master key is very powerful and in case of it getting leaked the consequences can be severe.

To create a new key, client can invoke create keys method with an Array of objects with properties:

  • grants

    Object, required. Each property name is a name of resource. Value is an array of Strings - names of actions. See the example below.

  • tags

    Object. See Tags API

Request:

{
  "jsonrpc": "2.0",
  "id": 114,
  "method": "create keys",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": [
      {
        "grants": {
          "vehicles": [
            "list",
            "locate"
          ],
          "routes": [
            "list"
          ]
        },
        "tags": {
          "note": "A key for the monitoring app."
        }
      },
      {
        "grants": {
          "routes": [
            "list"
          ]
        },
        "tags": {
          "note": "A key for the backup script."
        }
      }
    ]
  }
}

Required authorization scope:

keys: create

Successful response:

{
  "jsonrpc": "2.0",
  "id": 114,
  "result": {
    "data": {
      "keys": {
        "596e4fb8-5c09-4258-b473-21ff4b92b7e8": {
          "id": "596e4fb8-5c09-4258-b473-21ff4b92b7e8",
          "grants": {
            "vehicles": [
              "list",
              "locate"
            ],
            "routes": [
              "list"
            ]
          },
          "tags": "A key for the monitoring app."
        },
        "579e11b9-875e-4f0d-8b70-aef2a0cf6919": {
          "id": "579e11b9-875e-4f0d-8b70-aef2a0cf6919",
          "grants": {
            "routes": [
              "list"
            ]
          },
          "tags": "A key for the backup script."
        }
      }
    }
  }
}

Attempt to create key without required authorization scope will fail:

Request:

{
  "jsonrpc": "2.0",
  "id": 115,
  "method": "create keys",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": [
      {
        "grants": {
          "keys": [
            "create",
            "list",
            "revoke"
          ]
        },
        "tags": "Evi1 haxxxor script kiddie."
      }
    ]
  }
}

Required authorization scope:

keys: create

Error response:

{
  "jsonrpc": "2.0",
  "id": 115,
  "error": {
    "code": "403",
    "message": "Not authorized",
    "data": {
      "missing": {
        "keys": [
          "create"
        ]
      }
    }
  }
}

List keys

Keys of the customer can be retrieved using get keys method. Without arguments it will return all the keys. Accepted arguments are:

  • grants

    Object. Only keys allowing this authorization scope will be received

  • revoked

    Boolean. If set to true only revoked keys will be retrived. Otherwise only active ones.

  • tags

    See Tags API

Request:

{
  "jsonrpc": "2.0",
  "id": 116,
  "method": "get keys",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "grants": {
        "vehicles": [
          "list"
        ]
      }
    }
  }
}

Required authorization scope:

keys: list

Successful response:

{
  "jsonrpc": "2.0",
  "id": 116,
  "result": {
    "data": {
      "keys": {
        "a4a9edbc-96e3-4cdd-84af-dd4ee573467d": {
          "id": "a4a9edbc-96e3-4cdd-84af-dd4ee573467d",
          "tags": "notes:This is a key for Tom",
          "grants": {
            "vehicles": [
              "list",
              "locate"
            ],
            "routes": [
              "list",
              "update"
            ]
          }
        },
        "ae1610d4-e0b3-4c96-9f33-c097d57dfedf": {
          "id": "ae1610d4-e0b3-4c96-9f33-c097d57dfedf",
          "note": "Key for backup script",
          "grants": {
            "vehicles": [
              "list"
            ],
            "routes": [
              "list"
            ]
          }
        }
      }
    }
  }
}

It is useful to monitor creation and revocation of keys

Request:

{
  "jsonrpc": "2.0",
  "id": 117,
  "method": "get keys",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg==",
      "watch": true
    },
    "args": {}
  }
}

The client will immediately receive a response with all the keys:

Successful response:

{
  "jsonrpc": "2.0",
  "id": 117,
  "result": {
    "data": {
      "keys": {
        "17be4483-1b3c-4ab7-80cf-cacb64f69887": {
          "id": "17be4483-1b3c-4ab7-80cf-cacb64f69887",
          "notes": "This is a key for Tom",
          "grants": {
            "vehicles": [
              "list",
              "locate"
            ],
            "routes": [
              "list",
              "update"
            ]
          }
        },
        "06cf8511-6a60-4563-b49d-48936dad1a83": {
          "id": "06cf8511-6a60-4563-b49d-48936dad1a83",
          "note": "Key for backup script",
          "grants": {
            "vehicles": [
              "list"
            ],
            "routes": [
              "list"
            ]
          }
        }
      }
    }
  }
}

On supported transports (i.e. WebSockets) there will be a notification sent with the new data. So if a key for Tom is removed:

Notification:

{
  "id": 117,
  "result": {
    "data": {
      "keys": {
        "06cf8511-6a60-4563-b49d-48936dad1a83": {
          "id": "06cf8511-6a60-4563-b49d-48936dad1a83",
          "note": "Key for backup script",
          "grants": {
            "vehicles": [
              "list"
            ],
            "routes": [
              "list"
            ]
          }
        }
      }
    }
  }
}

Revoke keys

A revoked key cannot be used to obtain a token. There is no way to reverse this operation. Arguments is an Array of Strings, each representing a key to be revoked.

Request:

{
  "jsonrpc": "2.0",
  "id": 118,
  "method": "revoke keys",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": [
      "fa6ffaab-3e0c-4369-8ea5-bd29cb3f38e7"
    ]
  }
}

Required authorization scope:

keys: revoke

Successful response:

{
  "jsonrpc": "2.0",
  "id": 118,
  "result": {
    "data": {
      "keys": {
        "fa6ffaab-3e0c-4369-8ea5-bd29cb3f38e7": null
      }
    }
  }
}

Account

Actions

  • update contact details

  • get contact details

Update account details

Request:

{
  "jsonrpc": "2.0",
  "id": 119,
  "method": "update contact details",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "name": "Wayne Aerospace",
      "address": "Thomas Wayne st. 1\n13442 Gotham City",
      "country": "US",
      "email": "it@wayne.com",
      "phone": "31 023 343 444",
      "person": "Lucius Fox"
    }
  }
}

Required authorization scope:

account: update contact details

Successful response:

{
  "jsonrpc": "2.0",
  "id": 119,
  "result": {
    "data": {
      "name": "Wayne Aerospace",
      "address": "Thomas Wayne st. 1\n13442 Gotham City",
      "country": "US",
      "email": "it@wayne.com",
      "phone": "31 023 343 444",
      "person": "Lucius Fox"
    }
  }
}

If only some of the fields are provided, the server will merge them with existing details:

Request:

{
  "jsonrpc": "2.0",
  "id": 120,
  "method": "update contact details",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "phone": "31 023 343 445"
    }
  }
}

Required authorization scope:

account: update contact details

Successful response:

{
  "jsonrpc": "2.0",
  "id": 120,
  "result": {
    "data": {
      "name": "Wayne Aerospace",
      "address": "Thomas Wayne st. 1\n13442 Gotham City",
      "country": "US",
      "email": "it@wayne.com",
      "phone": "31 023 343 445",
      "person": "Lucius Fox"
    }
  }
}

Get contact details

Request:

{
  "jsonrpc": "2.0",
  "id": 121,
  "method": "get contact details",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {}
  }
}

Required authorization scope:

account: get contact details

Successful response:

{
  "jsonrpc": "2.0",
  "id": 121,
  "result": {
    "data": {
      "name": "Wayne Aerospace",
      "address": "Thomas Wayne st. 1\n13442 Gotham City",
      "country": "US",
      "email": "it@wayne.com",
      "phone": "31 023 343 445",
      "person": "Lucius Fox"
    }
  }
}

Devices

Properties:

  • serial (RO Number)

    Serial Number of a device.

  • status (RO String['active', 'retired'])

    Status of the device.

  • hw_version (RO String)

    Hardware version.

  • fw_version (RO String)

    Firmware version.

  • vehicle (RO Vehicle)

    A vehicle that the device is currently associated with.

Actions

  • get devices

  • modify devices

Get devices

Request:

{
  "jsonrpc": "2.0",
  "id": 122,
  "method": "get devices",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "fw_version": "12.5b"
    }
  }
}

Required authorization scope:

devices: list

Successful response:

{
  "jsonrpc": "2.0",
  "id": 122,
  "result": {
    "data": {
      "devices": {
        "f07474d3-4812-4d22-85d6-25ba57d4c897": {
          "id": "f07474d3-4812-4d22-85d6-25ba57d4c897",
          "serial": "123456",
          "status": "active",
          "hw_version": "1.0",
          "fw_version": "12.5b",
          "tags": [
            "note:Mary has it."
          ]
        },
        "64a52a6a-5ae6-48e2-a91f-675e3e7d1f3c": {
          "id": "64a52a6a-5ae6-48e2-a91f-675e3e7d1f3c",
          "serial": "123456",
          "status": "active",
          "hw_version": "1.0",
          "fw_version": "12.5b",
          "tags": []
        }
      }
    }
  }
}

Modify device

In this version of API all of the custom properties of the devices are read only. Modify is only suitable to tag devices. In future versions there may be additional properties that can be modified.

Request:

{
  "jsonrpc": "2.0",
  "id": 123,
  "method": "modify devices",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "64a52a6a-5ae6-48e2-a91f-675e3e7d1f3c": {
        "tags": [
          "note:Mary has it."
        ]
      }
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "data": {
      "devices": {
        "64a52a6a-5ae6-48e2-a91f-675e3e7d1f3c": {
          "id": "64a52a6a-5ae6-48e2-a91f-675e3e7d1f3c",
          "serial": "123456",
          "status": "active",
          "hw_version": "1.0",
          "fw_version": "12.5b",
          "tags": [
            "note:Mary has it."
          ]
        }
      }
    }
  }
}

Vehicles

Properties

  • plate (RW String)

  • millage (RW Number)

    Total number of kilometers or miles traveled by a vehicle

  • driver (RO maybe Person)

    A person currently associated with that the device as it's driver.

    May be null if the car is not currently on route.

  • location (RO Location)

    Last known latitude and longitude of a vehicle.

Actions

  • register vehicles

  • get vehicles

  • unregister vehicles

Vehicles are automatically added to the system when a driver first registers it trough a SPARC device.

If required, vehicles can also be manually registered, updated and unregistered trough API.

Register vehicles

Takes an array of Vehicles.

Request:

{
  "jsonrpc": "2.0",
  "id": 124,
  "method": "register vehicles",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": [
      {
        "plate": "P89T64",
        "mileage": 12321
      },
      {
        "plate": "D40F20",
        "mileage": 0,
        "tags": [
          "note: New car for Ana"
        ]
      }
    ]
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 124,
  "result": {
    "data": {
      "vehicles": {
        "9d7b0318-8ce3-424c-8a7a-d5958227fc8e": {
          "id": "9d7b0318-8ce3-424c-8a7a-d5958227fc8e",
          "plate": "P89T64",
          "mileage": 12321
        },
        "b309ef2b-f16e-4613-a3cd-9f6946a39d55": {
          "id": "b309ef2b-f16e-4613-a3cd-9f6946a39d55",
          "plate": "D40F20",
          "mileage": 0,
          "tags": [
            "note: New car for Ana"
          ]
        }
      }
    }
  }
}

Get vehicles

Request:

{
  "jsonrpc": "2.0",
  "id": 125,
  "method": "get vehicles",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "tags": [
        "manufacturer: Volkswagen"
      ]
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 125,
  "result": {
    "data": {
      "data": {
        "vehicles": {
          "f9296b51-3b13-4d77-a87c-101db7998d25": {
            "id": "f9296b51-3b13-4d77-a87c-101db7998d25",
            "plate": "P89T64",
            "millage": 34219,
            "location": {
              "types": "Feature",
              "geometry": {
                "type": "Point",
                "coordinates": [
                  4.92796603,
                  52.36276643
                ]
              },
              "properties": {
                "updated_at": "2015-02-19 10:23:42.000",
                "address": "Panamalaan, 12B",
                "city": "Amsterdam",
                "country": "NL"
              }
            },
            "tags": [
              "manufacturer: Volkswagen",
              "type: Golf"
            ]
          },
          "37f30dfd-5a05-4de0-a8d9-c71eaef4e725": {
            "id": "37f30dfd-5a05-4de0-a8d9-c71eaef4e725",
            "plate": "N492JK",
            "millage": 12076,
            "location": {
              "type": "Feature",
              "geometry": {
                "type": "Point",
                "coordinates": [
                  4.92796603,
                  52.36276643
                ]
              },
              "properties": {
                "updated_at": "2015-02-19 10:23:42.000",
                "address": "Panamalaan, 12B",
                "city": "Amsterdam",
                "country": "NL"
              }
            },
            "tags": [
              "manufacturer: Volkswagen",
              "type: UP!"
            ]
          }
        }
      }
    }
  }
}

Getting vehicles by location

Client can use reverse geocoded properties of the location to get cars by city or country.

Request:

{
  "jsonrpc": "2.0",
  "id": 126,
  "method": "get vehicles",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "location": {
        "properties": {
          "city": "Amsterdam"
        }
      }
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 126,
  "result": {
    "data": {
      "data": {
        "vehicles": {
          "8b96840b-5879-4212-aa96-64b56b505e60": {
            "id": "8b96840b-5879-4212-aa96-64b56b505e60",
            "plate": "P89T64",
            "millage": 34219,
            "location": {
              "types": "Feature",
              "geometry": {
                "type": "Point",
                "coordinates": [
                  4.92796603,
                  52.36276643
                ]
              },
              "properties": {
                "updated_at": "2015-02-19 10:23:42.000",
                "address": "Panamalaan, 12B",
                "city": "Amsterdam",
                "country": "NL"
              }
            },
            "tags": [
              "manufacturer: Volkswagen",
              "type: Golf"
            ]
          }
        }
      }
    }
  }
}

For more precise geospatial queries use Geofences API.

Unregister vehicle

Takes an array of Ids.

Example:

Request:

{
  "jsonrpc": "2.0",
  "id": 127,
  "method": "unregister vehicles",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": [
      "1c0f3149-89ed-4fe3-bd53-94045573cae8",
      "febb9801-7dac-4211-beac-ecfe0fb983e8",
      "2d0b98f4-5e58-4737-8c87-54f264fb50c5"
    ]
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 127,
  "result": {
    "data": {
      "vehicles": {
        "93999b36-8bb7-428c-a424-880d8e600c99": null,
        "42322581-802e-479e-95ca-e451963b134d": null,
        "3c8a382e-d4ae-46b5-8076-b42c98b2e84c": null
      }
    }
  }
}

Drivers

Properties

  • name (RW String)

    A full name of the person.

  • nfc (RO maybe String)

    NFC ID associated with the driver. To change the association a driver have to use new NFC device (e.g. a public transportation card) and enter his pin when prompted.

    null before first association.

  • pin (RO String)

    A new pin can be generated by calling get pin with an id of the person. See Getting New PIN below.

  • phone (RW String)

    Telephone number for automatic notifications, e.g. sending new PIN.

  • email (RW String)

    Email address for automatic notifications, e.g. sending new PIN.

Actions

  • register drivers ! drivers: register

  • get drivers ! drivers: list

  • get pin ! drivers: get pin

  • update personal information ! drivers: update

  • unregister drivers ! drivers: unregister

Get drivers

Request:

{
  "jsonrpc": "2.0",
  "id": 128,
  "method": "get drivers",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "name": "Gi%"
    }
  }
}

Successful response:

{
  "jsonrpc": "2.0",
  "id": 128,
  "result": {
    "data": {
      "drivers": {
        "07b03697-8b7d-44c1-b032-2eac1b6da5ad": {
          "id": "07b03697-8b7d-44c1-b032-2eac1b6da5ad",
          "pin": "34219",
          "nfc": "B65433",
          "name": "Gino Lino Pino",
          "phone": "+31634665476",
          "email": "ginopino@lino.org",
          "tags": [
            "truck driver",
            "notes: He is bald and dangerous."
          ]
        },
        "ff3363e2-9f40-45d8-bab4-4e1e0524981b": {
          "id": "ff3363e2-9f40-45d8-bab4-4e1e0524981b",
          "pin": "39932",
          "nfc": "D3303",
          "name": "Giancarlo John Bobbit",
          "phone": "+3144030233",
          "email": "sam@bobbitmail.org",
          "tags": [
            "notes: He is not afraid of anything."
          ]
        }
      }
    }
  }
}

Retrieve driver position

Request:

{
  "jsonrpc": "2.0",
  "id": 129,
  "method": "get vehicles",
  "params": {
    "transaction": {
      "token": "94xOySR2cpqUDdZb4+SCxcp8TrOrXSAOBl7wKChxDo0X1pmwsZVeE0nIsI7GWkZNWDJAIq+JBl/C3xts3cn0hHlWPe5vK4kFowTBXELTJrAtlPqeehqQICoqROHm4XpRQpKp3zt9NENsvlHpTl0DYrM/rl85l5V07AyzZd6DyCJ5W+JbhI+wGnaMX8kB9Zh5nnrn6R07JsfldYIYaQfQkg=="
    },
    "args": {
      "driver": {
        "name": "Nino Lino Pino"
      }
    }
  }
}

Routes

Properties

Routes are stored as geoJSON objects of type Feature with geometry type LineString. All the properties listed below are grouped in properties member of the feature. See examples below.

  • vehicle (RW Vehicle)

  • driver (RW Person)

  • period (RW Object)

    • start (RW Time)

    • end (RW Time)

  • from (RO Location)

    Calculated from geoJSON geometry. Includes reverse geocoded data.

  • to (RO Location)

    Calculated from geoJSON geometry. Includes reverse geocoded data.

  • length (RO Number)

    Total length in kilometers. Calculated from geoJSON geometry.

  • categories (RO Array String Category)

    List of categories (e.g. business, private)

Actions

  • get routes

  • modify routes

  • discard routes

Parkings

Properties

Parkings are stored as geoJSON objects of type Feature with geometry type Point. All the properties listed below are grouped in properties member of the feature. See examples below.

  • vehicle (RW Vehicle)

  • driver (RW Person)

  • period (RW Object)

    The period of this parking.

    • start (RW Time)

    • end (RW Time)

  • address (RW String)

    Reverse geocoded from geoJSON geometry.

  • city (RW String)

    Reverse geocoded from geoJSON geometry.

  • country (RW String)

    Reverse geocoded from geoJSON geometry.

  • category (RW String Category)

    A category (e.g. business, private)

Actions

  • get parkings

  • modify parkings

  • discard parkings

Geofences

Geofences can be used to query for vehicles by location. Combined with notifications API they can provide a building block for notifications.

At this point we only deal with circles, i.e. point with radius. In the future there may be more precise API.

Properties

  • center (RW Location)

  • redius (RW Number)

    Circle radius in meters.

  • vehicles (RO List Vehicles)

    A list of vehicles inside the fence.

Actions

  • create fences

  • get fences

  • delete fences