Skip to main content

A Python client and object-mapper for the Oslo Bysykkel API

Project description


sgs-pycycle is a pure Python 3 client and object-mapper for Oslo Bysykkel.

It requires no additional libraries.


The main reason for writing this library was a simple academic task.

Since the name pycycle was already taken, I decided to namespace it.

I hope that somebody will find it useful.


  • Python >=3.6 with corresponding setuptools


If one wants to install the package in a convenient way as an unprivileged user the easiest way is to use virtualenv that is part of Python 3.

python -m venv venvSGSPycycle
source venvSGSPycycle/bin/activate

or if using MS Windows


That will install and load the virtual environment Now one can choose one of the methods described bellow.

pip (pypi)

The easiest way is to install the package directly from

pip install sgs-pycycle


git clone

One can simply install in a virtual-environment or as a privileged user by:

cd sgs-pycycle
python install

or one can add a symlink or copy sgs-pycycle/sgs_pycycle into any directory that is included in the PYTHONPATH environmental variable or create own directory.

mkdir mypythonpathdir
export PYTHONPATH=/full/path/to/mypythonpathdir
cp -R sgs-pycycle/sgs_pycycle /full/path/to/mypythonpathdir/

This latest method also eliminates the need for setuptools, but will not add the dedicated executable sgs_pycycle. Still the CLI interface can be accessed as shown bellow.

Check if everything works by typing:

python -m sgs_pycycle -h

Overview and technical design

The main goals when considering the technical design were:


Although there are several Python libraries that simplify the HTTP request as well as handling the responses like requests and pydantic for object mapping, I decided to use only the standard Python modules to make installation and usage as simple as possible.


There are many possible improvements (some of them listed bellow), but I made a conscious decision to only stick with the provided task.

Object-oriented design and extensibility

Making HTTP requests and processing data is a relatively simple task. I wanted to provide a small set of objects (Station and StationCollection) in order to make the use of this client library easier to extend. Instead of using the provided CLI interface, it is now quite easy to use the client library in f.i. web application or GUI application. In addition using a simple object mapper is more elegant and intuitive than simply manipulating JSON structures.



The CLI interface can be accessed in two ways.

python -m sgs_pycycle -h

or if sgs-pycycle was installed using setuptools, there will also be a binary called sgs_pycycle. Hence

sgs_pycycle -h

will yield the same result and display a summery of all available CLI options.

python -m sgs_pycycle -l
sgs_pycycle -l

will display all stations with id, name, number of docks available, number of bikes available.

python -m sgs_pycycle -l -k name
sgs_pycycle -l -k name

will produce the same content, only order the stations by name.

All station attributes can be used for sorting, given that string attributes will be sorted as strings (f.i. '98' > '1654').

python -m sgs_pycycle -l -c user-testapp
sgs_pycycle -l -c user-testapp

will call the API using 'user-testapp' as Client-Identifier.

Using the library directly

Using the library directly provides more possibilities and makes it possible to embed the client into a web-application or even a GUI application.

import sgs_pycycle

# Auto discovery URL and identity
A_D_URL = ''
CLIENT_IDENTITY = 'user-testapp'

# create a Client object
client = sgs_pycycle.Client(A_D_URL, CLIENT_IDENTITY)

# fetch the entire collection
    collection = client.get_station_collection()
except sgs_pycycle.ClientConnectionError as e:
    # ... unable to connect routines and messages
len(collection)  # amount of stations

# print the last_reported value for each station
for station in collection:
    print(f'{} - {station.last_reported}')

# sort the stations by name
for station in collection:
    # prints id, name, number of docks available, number of bikes available


Incomplete list of possible future improvements:

  • unit tests

  • caching by using the last_updated and last_reported attributes for better performance

  • extended StationCollection API, fetching a single Station, advanced sorting..

  • translation / locale support

  • API documentation with Sphinx

  • Better error reporting and sanity checking

  • Formatting output for CLI (header, even spacing, etc...)

  • More CLI parameters (socket timeout, SSL context, etc...)


Simeon Simeonov - sgs @ Freenode


Copyright (c) 2020, Simeon Simeonov All rights reserved.

Licensed under the BSD 2-clause. SPDX-License-Identifier: BSD-2-Clause-FreeBSD

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sgs-pycycle-1.0.0.tar.gz (11.4 kB view hashes)

Uploaded Source

Built Distribution

sgs_pycycle-1.0.0-py3-none-any.whl (13.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page