API docs by Redocly

Urban Sharing - Operations API (1.9.0)

Download OpenAPI specification:

Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com

The Operations API allows third party access to Urban Sharing operator functionality.

The API provides access to the following data:

  • Dock group static data e.g. name, address, position
  • Dock group dynamic data e.g. online, state
  • Vehicle static data e.g. name, category
  • Vehicle dynamic data e.g. battery level, state
  • Vehicle Trip data
  • Vehicle Commands e.g. unlock battery, assign to administrator

The Operations API sends events to webhooks. The available events are:

  • /operations/faults - Generated when a fault occurs
  • /operations/alerts - Generated when an alert occurs
  • /operations/lost - Generated when an asset is lost or found
  • /opreations/damages - Generated when an asset is damaged, broken or repaired
  • /operations/connectivity - Generated when an asset goes offline or comes online

Release History
DateVersionNotes
Thu Oct 31 20241.9.0Add isAvailable to vehicles
Mon Sep 02 20241.8.0Add title to dock-groups
Thu Aug 22 20241.7.0Add GET asset-types
Add tags and damage IDs to vehicle statuses
Add tags to dock groups
Mon Jul 29 20241.6.0Add vehicle location to vehicle endpoints
Add GET operation-location and GET operations-location/:operationLocationId endpoints
Thu Apr 18 20241.5.0Add vehicles/gbfs/:vehicleId endpoint
Add vehicles/qrCode/:qrCode endpoint
Mon Nov 20 20231.1.0Add operations API webhooks - trips, alerts, faults, connectivity, damage and lost
Wed Nov 15 20231.0.4Add reported and max virtual dock count to dock groups
Wed Aug 30 20231.0.3Update the description of the trips endpoint
Mon Aug 28 20231.0.2Remove deprecated "with_administrator" state from externalState
Sun Aug 27 20231.0.1Moved all array responses to row property. e.g. [ data ] -> { rows: [ data ] }
Tue Aug 15 20231.0.0Initial release
Sun Jan 22 20231.4.0Remove "operations/" prefix from all webhooks

Authentication

To use this API you must first obtain API credentials from Urban Sharing. These API credentials can then be used to generate a JWT token which must be passed in the Authorization header when accessing resources in this API.

For more information, please refer to the Urban Sharing Auth API


Webhook Authentication

Urban Sharing generates webhook signatures using a hash-based message authentication code (HMAC) with SHA-256. You can validate the signature of the request body as follows:

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v0 corresponds to the signature.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating: The timestamp (as a string) The character . The actual JSON payload - the body of the request

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use client secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Signature Validation Example

Here is an example of how to validate a webhook signature in Typescript. 
validateWebhookSignature(
  clientSecret: string,
  signature: string,
  data: unknown,
  maxAgeMs = 5000,
): boolean {
  const [timestampPair, ...signatures] = signature.split(',');

  const timestamp = +timestampPair.split('=')[1];

  // Check that the timestamp is not too old
  if (maxAgeMs > 0) {
    const latestTimestamp = new Date().getTime() - maxAgeMs;

    if (timestamp < latestTimestamp) {
      return false;
    }
  }

  // Convert signatures into an object
  const signatureObject: any = signatures.reduce((acc, curr) => {
    const [key, value] = curr.split('=');
    acc[key] = value;
    return acc;
  }, {});

  // Build the signed payload
  const signed_payload = `${timestamp}.${JSON.stringify(data)}`;

  // Validate the v0 signature
  if (signatureObject.v0) {
    const expectedSignature = crypto
      .createHmac('sha256', clientSecret)
      .update(signed_payload)
      .digest('hex');

    return signatureObject.v0 === expectedSignature;
  }

  return false;
}

Terminology

Urban Sharing APIs refer to docks, dock groups and vehicles as our platform is designed to support multiple modes of transport. In the case of bike share systems, docks are individual bike parking spots, dock groups are stations and vehicles are bikes.


Operations API

Get Vehicles

Returns a list of static vehicle data

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get vehicle statuses Deprecated

Returns a list of vehicle statuses

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get vehicle status Deprecated

Returns a single vehicle status

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 4554,
  • "assetModelId": 4112,
  • "name": "Vehicle 1",
  • "number": "42",
  • "category": "ebike",
  • "qrCode": "424242",
  • "externalId": "2469394",
  • "broken": true,
  • "state": "on_trip",
  • "location": {
    },
  • "charge": 95,
  • "lowBattery": false,
  • "tags": [
    ],
  • "damageIds": [
    ],
  • "lastSeen": "2020-01-01T00:00:00Z",
  • "isAvailable": true,
  • "blockedAt": "2020-01-01T00:00:00Z",
  • "lockMechanismState": "locked",
  • "iotCharge": 85
}

Get Vehicle

Returns a single vehicle

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 4554,
  • "assetModelId": 4112,
  • "name": "Vehicle 1",
  • "number": "42",
  • "category": "ebike",
  • "qrCode": "424242",
  • "externalId": "2469394",
  • "broken": true,
  • "state": "on_trip",
  • "location": {
    },
  • "charge": 95,
  • "lowBattery": false,
  • "tags": [
    ],
  • "damageIds": [
    ],
  • "lastSeen": "2020-01-01T00:00:00Z",
  • "isAvailable": true,
  • "blockedAt": "2020-01-01T00:00:00Z",
  • "lockMechanismState": "locked",
  • "iotCharge": 85
}

Vehicle command

Sends a command to a vehicle

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Request Body schema: application/json
required
operatorId
required
string

The ID of the operator performing the command. This is used for validation and logging purposes

commandType
required
string
Enum: "unlock" "battery_unlock"

The type of command to send to the vehicle

parameters
Array of strings

Optional parameters to send with the command

Responses

Request samples

Content type
application/json
{
  • "operatorId": "oper_2435",
  • "commandType": "battery_unlock",
  • "parameters": [ ]
}

Response samples

Content type
application/json
{
  • "status": "OK"
}

Perform vehicle repairs

Returns a list of vehicle repairs

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Request Body schema: application/json
required
operatorId
required
string

The ID of the operator performing the repair. This is used for validation and logging purposes

required
Array of objects (OperationsVehicleRepairDamageType)

The damage types that have been repaired

Array of objects (OperationsVehicleRepairType)

The repair types that have been performed. These are custom repairs performed outside of the necessary repairs dictated by the damageTypes. Repairs done as part of repairing a specific damage type should be specified inside the damageTypes instead. This property is used to log additional repairs that are not directly related to an active damage type.

startedAt
string <date-time>

When the maintenance operation was started

Responses

Request samples

Content type
application/json
{
  • "operatorId": "oper_2435",
  • "damageTypes": [
    ],
  • "repairTypes": [
    ],
  • "startedAt": "2024-12-31T23:59:59.999Z"
}

Response samples

Content type
application/json
{
  • "status": "OK"
}

Get trips

Returns a list of trips that have ended filtered by year, month and optional day. The timezone of the system is used for the trip end date.

Authorizations:
bearer
query Parameters
year
required
number [ 2000 .. 3000 ]
Example: year=2012

Select data for a specific year

month
required
number [ 1 .. 12 ]
Example: month=7

Select data for a specific month

day
number [ 1 .. 31 ]
Example: day=14

Select data for a specific day - optional

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get dock groups Deprecated

Returns a list of static dock group data

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get dock groups

Returns all dock group data

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get dock group statuses Deprecated

Returns a list of dock group statuses

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get dock group status Deprecated

Returns a single dock group status

Authorizations:
bearer
path Parameters
dockGroupId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 8787,
  • "online": true,
  • "state": "active"
}

Get dock group Deprecated

Returns a single dock group

Authorizations:
bearer
path Parameters
dockGroupId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 8787,
  • "name": "Station1",
  • "title": "Station 1",
  • "location": {
    },
  • "elevation": 0,
  • "state": "active",
  • "physicalDockCount": 20,
  • "virtualDockCount": 5,
  • "reportedVirtualDockCount": 10,
  • "maxVirtualDockCount": 15,
  • "tags": [
    ],
  • "availabilityInfo": { },
  • "controller": { }
}

Get dock group

Returns a single dock group

Authorizations:
bearer
path Parameters
dockGroupId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 8787,
  • "name": "Station1",
  • "title": "Station 1",
  • "location": {
    },
  • "elevation": 0,
  • "state": "active",
  • "physicalDockCount": 20,
  • "virtualDockCount": 5,
  • "reportedVirtualDockCount": 10,
  • "maxVirtualDockCount": 15,
  • "tags": [
    ],
  • "availabilityInfo": { },
  • "controller": { }
}

Get Vehicle by QR code

Returns vehicle data based on its QR code.

Authorizations:
bearer
path Parameters
qrCode
required
string
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 4554,
  • "assetModelId": 4112,
  • "name": "Vehicle 1",
  • "number": "42",
  • "category": "ebike",
  • "qrCode": "424242",
  • "externalId": "2469394",
  • "broken": true,
  • "state": "on_trip",
  • "location": {
    },
  • "charge": 95,
  • "lowBattery": false,
  • "tags": [
    ],
  • "damageIds": [
    ],
  • "lastSeen": "2020-01-01T00:00:00Z",
  • "isAvailable": true,
  • "blockedAt": "2020-01-01T00:00:00Z",
  • "lockMechanismState": "locked",
  • "iotCharge": 85
}

Get Vehicle by GBFS ID

Returns vehicle data based on the its GBFS ID.

Authorizations:
bearer
path Parameters
gbfsId
required
string
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 4554,
  • "assetModelId": 4112,
  • "name": "Vehicle 1",
  • "number": "42",
  • "category": "ebike",
  • "qrCode": "424242",
  • "externalId": "2469394",
  • "broken": true,
  • "state": "on_trip",
  • "location": {
    },
  • "charge": 95,
  • "lowBattery": false,
  • "tags": [
    ],
  • "damageIds": [
    ],
  • "lastSeen": "2020-01-01T00:00:00Z",
  • "isAvailable": true,
  • "blockedAt": "2020-01-01T00:00:00Z",
  • "lockMechanismState": "locked",
  • "iotCharge": 85
}

Get operation locations

Returns a list of operation locations

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Get operation location

Returns a single operation location

Authorizations:
bearer
path Parameters
operationLocationId
required
number
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "id": 8787,
  • "name": "Station1",
  • "type": "storage",
  • "location": {
    }
}

Get asset types

Returns the asset types

Authorizations:
bearer
header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Operations Webhooks

Alert event

Reports system alerts

header Parameters
Api-Client-ID
required
string

The ID of the API client associated with this webhook.

uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
string

The ID of the asset type associated with the event

entityType
required
string
Enum: "controller_id" "vehicle_id" "dock_group_id" "dock_id" "unknown"

The Asset type associated with the event

generated
required
string <date-time>

The timestamp of the event

status
required
string
Enum: "started" "finished"

The status of the alert

code
string

The alert code

description
required
string

The description of the alert

Responses

Request samples

Content type
application/json
{
  • "id": "123",
  • "entityType": "controller_id",
  • "generated": "2019-08-24T14:15:22Z",
  • "status": "started",
  • "code": "42",
  • "description": "Something wonderful has happened!"
}

Fault event

Reports fault events

header Parameters
Api-Client-ID
required
string

The ID of the API client associated with this webhook.

uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
string

The ID of the asset type associated with the event

entityType
required
string
Enum: "controller_id" "vehicle_id" "dock_group_id" "dock_id" "unknown"

The Asset type associated with the event

generated
required
string <date-time>

The timestamp of the event

status
required
string
Enum: "started" "finished"

The status of the fault

code
string

The fault code

description
required
string

The description of the fault

Responses

Request samples

Content type
application/json
{
  • "id": "123",
  • "entityType": "controller_id",
  • "generated": "2019-08-24T14:15:22Z",
  • "status": "started",
  • "code": "123",
  • "description": "Something terrible has happened!"
}

Lost event

Reports system lost events

header Parameters
Api-Client-ID
required
string

The ID of the API client associated with this webhook.

uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
string

The ID of the asset type associated with the event

entityType
required
string
Enum: "controller_id" "vehicle_id" "dock_group_id" "dock_id" "unknown"

The Asset type associated with the event

generated
required
string <date-time>

The timestamp of the event

status
required
string
Enum: "started" "finished"

Whether or not the lost event has started or finished

Responses

Request samples

Content type
application/json
{
  • "id": "123",
  • "entityType": "controller_id",
  • "generated": "2019-08-24T14:15:22Z",
  • "status": "started"
}

Connectivity event

Reports connectivity events

header Parameters
Api-Client-ID
required
string

The ID of the API client associated with this webhook.

uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
string

The ID of the asset type associated with the event

entityType
required
string
Enum: "controller_id" "vehicle_id" "dock_group_id" "dock_id" "unknown"

The Asset type associated with the event

generated
required
string <date-time>

The timestamp of the event

online
required
boolean

Whether or not the event caused the asset to go online or offline

Responses

Request samples

Content type
application/json
{
  • "id": "123",
  • "entityType": "controller_id",
  • "generated": "2019-08-24T14:15:22Z",
  • "online": true
}

Damage event

Reports damage events

header Parameters
Api-Client-ID
required
string

The ID of the API client associated with this webhook.

uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
string

The ID of the asset type associated with the event

entityType
required
string
Enum: "controller_id" "vehicle_id" "dock_group_id" "dock_id" "unknown"

The Asset type associated with the event

generated
required
string <date-time>

The timestamp of the event

status
required
string
Enum: "ok" "damaged" "broken"

The status of the damage

damage
Array of strings

The damage details

Responses

Request samples

Content type
application/json
{
  • "id": "123",
  • "entityType": "controller_id",
  • "generated": "2019-08-24T14:15:22Z",
  • "status": "broken",
  • "damage": [
    ]
}