/bicycles/
This endpoint allows you to explore the status of your fleet in real-time. This resource is not suitable for keeping the status of your fleet in sync, as requesting thousands of bicycles at once is not effective in terms of capacity and user experience. In contrast, this endpoint is a great way to get specific features of your fleet, for example getting bicycles with the lowest state of charge.
State Machine
| State | What it means |
|---|---|
| available | The bicycle is ready and available to be used |
| in_maintenance | Bicycle requires or is undergoing maintenance so is unavailable to riders |
| rented | Bicycle has been rented using the Rider app (visible only to current Rider) |
| lost | Bicycle location is currently unknown |
| unrecoverable | The Bicycle location is known but unrecoverable |
| retired | The Bicycle is decommissioned |
| Transition | What it means |
|---|---|
| declare_available | Make bicycle visible to renters |
| rent | Renter is starting a rental session |
| return | Renter is finishing a rental session |
| declare_lost | Declare the bicycle lost |
| declare_unrecoverable | Declare the bicycle unrecoverable |
| take_over | Crew agent recovered a bicycle outside service area |
| force_put_in_maintenance | Allow fleet operators to end an active rental session |
| retire | Marks the end of the bicycle's life |
| reserve | Allow a renter to reserve a Bicycle |
| expire_rental_session | Automatic transition that expires a rental session after a configured duration |
| expire_reservation | Automatic transition that expires a reservation after a configured duration |
| cancel_reservation | Allow a renter to cancel its reservation |
Bicycle Model
The bicycle model contains the following properties:
| Property | Description |
|---|---|
| uuid | Unique identifier for the bicycle. |
| created | Date of creation of the bicycle. |
| latitude | Latitude of the current location of the bicycle. |
| longitude | Longitude of the current location of the bicycle. |
| latest_gps_accuracy | Last recorded gps accuracy in meters. |
| latest_gps_timestamp | Timestamp of the last recorded location message. |
| state_of_charge | State of charge of the battery in the device. |
| name | Given name of the asset. |
| description | Attached description to the bicycle. |
| model | Link to asset model corresponding to this entity. |
| bleid | Bluetooth identifier for the attached device. |
| device_type | Type of device attached to asset. Tracker or lock. |
| lock | Link to lock entity attached to the asset. |
| image_url | Link to image file corresponding to the asset described in this entity. |
| serial_number | Serial number of the asset. |
GET Fetch Bicycles
HTTP
This a sample request to retrieve the first page of a list of bicycles within a certain bounding box, sorted by date modified in descending order:
GET /bicycles/?ordering=-modified&bbox=<bounding-box-coords>
Authorization: JWT <token>
Accept: application/json;version=1.0
The list of allowed parameters is as follows:
| Parameter | Description |
|---|---|
| organization | UUID of the organization the bicycles belong to. |
| page | Number of the pages to fetch. |
| bbox | Geographic bounding box. Response is limited to bicycles located in this bbox. The expected format is <north-east-longitude>,<north-east-latitude>,<south-west-longitude>,<south-west-latitude> |
| zone | UUID of a geographic zone. Zone must be owned by the same organisation the bicycles belong to. Response is limited to bicycles located in this zone. |
| ordering | The field used to sort the response. Prepend a minus sign (-) to return in descending order. |
The response contains a list of bicycles:
[{
"latitude": 37.421769,
"longitude": -122.083266,
"latest_gps_accuracy": 7.45,
"latest_gps_timestamp": "2017-04-12T22:23:46Z",
"state_of_charge": 41.59375,
"name": "1645068",
"description": "Specialized MTB for public use.",
"model": "`https://api.lock8.me/api/bicycle_models/c840a800-6b6d-4aad-b0e8-3c3634248ba6/",
"bleid": "142651",
"device_type": "tracker",
"lock": "https://api.lock8.me/api/locks/4f1d6a0e-8414-432e-b4f8-b60d4d81b284/",
"image_url": "https://lock8.s3.amazonaws.com:443/photos/5f6d4bcb-491.jpg",
"serial_number": "A601160293"
},]
POST Create a Bicycle
This bicycle creation method expects the following information:
| Property | Description |
|---|---|
| name required | Visible name that gets assigned to the bicycle |
| organization required | Reference to the organization that will own the bicycle. |
| model | Reference to the bicycle's model. |
| lock | Reference to a lock that is already attached to this new bicycle. |
| serial_number | Frame serial number of the bicycle. |
Sample request:
POST /api/bicycles/
Authorization: JWT <token>
Accept: application/json;version=1.0
{
"name": "New Bicycle",
"organization": "https://<api-base-url>/organizations/<organization-uuid>/",
"lock": "https://<api-base-url>/locks/<lock-uuid>/",
"model": "https://<api-base-url>/locks/<model-uuid>/",
"serial_number": "AFTW1245124",
"description": "This is one of the most versatile and robust bicycles in the market. It's weight, size and resistance make it a great city bike, suitable for all types of trips."
}
POST Perform a transition on the state machine
You are allowed to interact with the state machine of the Bicycle, for instance to start or stop a rental session.
POST /api/bicycles/{uuid}/actions/
Authorization: JWT <token>
Accept: application/json;version=1.0
{
"type": "rent"
}
PUT Edit a Bicycle
TBA
SSE
To subscribe to updates on bicycles using Server-Sent Events, subscribe to the following topic:
Topic: /%{organization_uuid}/admin/bicycles/*
GET /subscribe/%2F%{organization_uuid}%2Fadmin%2Fbicycles%2F%2A/
Authorization: JWT <token>
Accept: application/json;version=1.0
Once successfully connected, events will start coming in on the consumer side. An example message is shown below. See the SSE section in Consuming this API for more details.
topic: /%{organization_uuid}/admin/bicycles/*
sender: bicycle
message: <updated-bicycle-model-object>