API docs by Redocly

Urban Sharing - Analytics API (1.8.0)

Download OpenAPI specification:

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

The Analytics API enables provides access to realtime and historical analytics data.

  • Realtime - close to realtime data. This is the same data you see in Urban Fleet.
  • Historical - data snapshots stored in a Google BigQuery dataset.

Release History
DateVersionNotes
Thu Nov 14 20241.8.0Add direct link between trip and subscription via anonymised id
Thu Oct 03 20241.7.0Add voucher code endpoint
Mon Jan 22 20241.9.0Add attached partner ids to users
Mon Jan 22 20241.6.0Add users endpoint
Add sales/itemized endpoint
Add get BigQuery keyset endpoint
Wed Nov 15 20231.5.0Add product duration method and minutes to "subscriptions"
Add vehicle name, dock group title, dock number to endpoints with only ids
Add reported and max virtual dock count to dock groups
Include non-active stations in "dockgroups"
Some calculated fields returned as strings instead of numbers
Thu Oct 19 20231.4.1Fix sales and subscription endpoint query parameters
Fri Sep 22 20231.4.0Add "sales" endpoint
Add "subscriptions" endpoint
Mon Sep 11 20231.3.0Add "operation-locations" endpoint
Add "operationLocationId" to "realtime/vehicle" endpoint
Add "batteryVoltage" to "realtime/vehicle" endpoint
Add "positionAccurracy" to "realtime/vehicle" endpoint
Add "cellTechnology" to "realtime/vehicle" endpoint
Add "cellQuality" to "realtime/vehicle" endpoint
Add "cellStrength" to "realtime/vehicle" endpoint
Add "cellGeneratedAt" to "realtime/vehicle" endpoint
Thu Aug 31 20231.2.0Add "damage-types" endpoint
Wed Aug 30 20231.1.0Add realtime/maintenance endpoint
Add anonymised "userId" to "realtime/trips" endpoint
Mon Aug 28 20231.0.1Add "isAvailableToCustomers" to "realtime/vehicle" endpoint
Add "isOperational" to "realtime/vehicle" endpoint
Remove deprecated "with_administrator" from "externalState" enum
Tue Aug 15 20231.0.0Initial release

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


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.


Set up BigQuery service account

Prerequisites

  1. An active Google Cloud Platform (GCP) account.
  2. Google Cloud billing is enabled and current.
  3. Adequate permissions to establish service accounts and assign roles within Google Cloud's IAM & Admin console.
  4. Urban Sharing API credentials - Client ID and Secret.

Create a Google service account

If you already have a Google service account that you want to use you can skip this step and jump straight to “Grant rights to Urban Sharing BigQuery dataset”.

Step 1: Select Your Google Cloud Project

  1. Log in to your Google account.
  2. Navigate to the Google Cloud Console.
  3. If prompted, either choose an existing project from the project dropdown in the top navigation bar or create a new one. This project will serve as the foundation for your BigQuery setup.

Step 2: Activate the BigQuery API

If the GCP project is old, BigQuery API might not be enabled. Newer projects have it enabled by default. To enable:

  1. Confirm that the correct project is chosen from the project options in the top navigation bar.
  2. To enable the BigQuery API, click here.

Step 3: Create a Service Account and assign roles

  1. Go to "IAM & admin" in the navigation menu and select "Service Accounts."
  2. Initiate the creation of a new Service Account by clicking the "Create Service Account" button.
  3. Provide a distinct name for your Service Account (e.g., "UrbanSharingBQClient"). Click Create and Continue
  4. Add the role "BigQuery - BigQuery Job User".
  5. Add the role "Project - Browser". Click Continue.
  6. Click the service account you created to open the editor
  7. Click the "Keys" tab then click "Add key - Create new key".
  8. Select "JSON" and click "Create" Your new key will be downloaded.

Step 4: Verify Google Cloud Billing

  1. Access "Billing" in the Google Cloud Console using the menu (☰) in the top-left corner and selecting "Billing."
  2. Confirm that billing is active and properly configured for your project. If not, follow the prompts to enable billing.

Grant rights to Urban Sharing BigQuery dataset

The following steps use curl to make requests to the Urban Sharing APIs. You can use any method you like.

  1. Use your Urban Sharing API Client ID and Secret to obtain a JWT token. See the Authentication section above for more information. 
    curl -X POST https://auth.api.urbansharing.com/auth/token \
  -H 'Content-Type: application/json' \
  -d '{ "grantType": "client_credentials", "clientId": "your_client_id", "clientSecret": "your_client_secret" }'
  2. Use the “accessToken” from the response in step 1 to grant the dataset rights to your service account.
     
    curl -X POST https://analytics.api.${domain}/bigquery/service-account \
  -H 'Authorization: Bearer [your_jwt_token>]' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "your_service_account_email" }'
  3. The response from step 2 will contain a “dataset” property. This is the link to your BigQuery dataset.

BigQuery Access

Get BigQuery Keyset

Returns the keyset required to decrypt Personally Identifiable Information (PII). This endpoint is only available if PII access is enabled for your API credentials.

PII data is encrypted with a periodically rotating key, which is valid for up to 2 months. Keys are rotated every 2 weeks, with the last 3 keys being present in the keyset. The 'primary' key is used to encrypt and decrypt new data, while the other keys are used to decrypt previous data. A newly rotated key does not become 'primary' for 2 weeks, but will be added to the keyset. This means that as long as you periodically refresh the keyset - by calling this endpoint - you will always have the latest keys in the keyset, and when a new key becomes 'primary' and starts encrypting new data you will already be able to decrypt it with your keyset. We recommend refreshing the keyset once per week.

When a key expires - after 2 months - data encrypted by that key will no longer be able to be decrypted. This means PII data older than 2 months is effectively deleted.

Refer to BigQuery documentation for how to use the keyset. A column can be decrypted with the following SQL: select aead.decrypt_string(from_base64(@keyset), from_base64(column_name), '') as column_name from table_name;

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
{
  • "keyset": "p929850wut9238507"
}

Create Service Account

Before creating a service account you must have a service account email address. See here for details on how to create a Google service account.

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.

Request Body schema: application/json
required
email
required
string

The service account email address

Responses

Request samples

Content type
application/json
{
  • "email": "account-id@project-id.iam.gserviceaccount.com"
}

Response samples

Content type
application/json
{
  • "id": "bqsa_1ZzYjrlBlX9d57xDoax7ok2r",
  • "dataset": "urbansharing-clients.your_system_name"
}

Delete account

Delete a BigQuery service account. This is irreversible. If you require access to the data again, you will need to create a new service account.

Authorizations:
bearer
path Parameters
id
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
{
  • "status": "OK"
}

Find account

Return a single BigQuery service account that has been created for your system

Authorizations:
bearer
path Parameters
id
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": "bqsa_1ZzYjrlBlX9d57xDoax7ok2r",
  • "apiAuthId": "api_1fj653G9Rv7z6zJaoUKOqrKM",
  • "email": "account-id@project-id.iam.gserviceaccount.com",
  • "accountType": "service_account",
  • "enabled": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Find accounts

Return all the BigQuery service accounts that have been created for your system

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
[
  • {
    }
]

Realtime Data

Get Vehicles

Returns a list of vehicles

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Dock Groups Deprecated

Returns a list of dock groups

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Dock Groups

Returns a list of dock groups

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Trips

Returns all trips that are currently in progress. Use historical data for trips that have ended.

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Damage and Maintenance

Returns all damage and maintenance that is currently in progress. Use historical data for damage and maintenance that has ended.

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Damage Types

Returns damage types.

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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
{
  • "info": {
    },
  • "rows": [
    ]
}

Get Operation Locations

Returns operation locations

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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": 1,
  • "systemId": "mysystem",
  • "name": "workshop01",
  • "type": "storage",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get Sales Itemized

Returns itemised sales by year and either month or week. Each sale is broken into one row for each line item, in addition to one for each charge attempt.

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

week
number [ 1 .. 53 ]
Example: week=14

Select data for a specific week

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 Sales

Returns sales by year, month and optional day

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 Subscriptions

Returns subscriptions by year, month and optional day

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 Users

Returns active users by year, month and day

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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 voucher codes

Returns voucher codes

Authorizations:
bearer
query Parameters
limit
number
Default: 50

The maximum number of rows to return

offset
number
Default: 0

The number of pages or rows to skip

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": [
    ]
}