Skip to main content

Pythonic access to the OpenSenseMap API

Project description

SenseMAPI - Pythonic access to the OpenSenseMap API

pipeline status coverage report documentation PyPI Downloads

sensemapi is a Python package to access the OpenSenseMap API.

Disclaimer

This software was developed within the context of a CO2 monitoring project of the University of Tübingen, Germany. The developer is not in any way affiliated with the senseBox project.

What can sensemapi do?

With sensemapi, you can do the most important things that you can also do via the OpenSenseMap user interface.

See some examples:

Access an OpenSenseMap account

account = sensemapi.account.SenseMapAccount(
    email = "SENSEMAP_EMAIL",
    password = os.environ.get("SENSEMAP_PASSWORD")
    )

Create new senseBoxes

# set up a senseBox (offline)
box = sensemapi.senseBox.senseBox(
    exposure = "outdoor",
    name="My senseBox",
    current_lat=50.5,
    current_lon=10.1)
# add a temperature sensor to the box (offline)
box.new_sensor(
    title="temperature",
    unit="°C",
    type="SHT31",
    icon="osem-temperature-celsius")
# create the senseBox (online)
account.new_box(box)

Modify senseBoxes and sensors

# retreive the account's boxes
account.get_own_boxes()
# choose the first box
box = account.boxes[0]
# change the box
box.name = "My supercool senseBox"
# ... do anything with the box object ...
# upload the changes
box.upload_metadata()

Upload measurements

# select the box's first sensor
sensor = box.sensors[0]
# reset the time to use the current time
sensor.last_time = None
# specify measurement value
sensor.last_value = 25.2
# upload the measurement
sensor.upload_measurement()

Delete a senseBox

# delete the account's first senseBox
account.delete_box(account.boxes[0].id, really=True)

Retreive any senseBox by its ID

# with an account
account.get_box(id = "57000b8745fd40c8196ad04c")
# without an account
sensemapi.client.SenseMapClient().get_box(id = "57000b8745fd40c8196ad04c")

Retreive measurements of a senseBox sensor

# get a box
box = sensemapi.client.SenseMapClient().get_box(id="57000b8745fd40c8196ad04c")
# the box' first sensor
sensor = box.sensors[0]
# get the sensor's latest measurements as pandas.Series
series = sensor.get_measurements().series
# Or download CSV data from the command-line:
sensemapi download --sensebox 5d35d315953683001a2b877a --from 2022-02 --to 2022-03 -o data.csv

Installation

The sensemapi package is best installed via pip3. Run from anywhere:

pip3 install --user sensemapi
pip3 install --user pandas # if you want pandas support

This downloads and installs the package from the Python Package Index.

You may also install sensemapi via pip3 from the repository root:

pip3 install --user .

Documentation

Documentation of the sensemapi package can be found here on GitLab.

Development

The following might only be interesting for developers

Tests

For running the full test suite, a registered and activated account at the Testing Stage of the OpenSenseMap is required. Details of this account must then be passed as environment variables, for example:

export SENSEMAP_EMAIL="user@email.com"   # specify either the email...
export SENSEMAP_USER="username"          # or the username
export SENSEMAP_PASSWORD="5uP3rP45sW0Rd"

You may also specifiy this sensitive data in a file which can then be sourced.

For running the tests, SENSEMAP_EMAIL and SENSEMAP_PASSWORD are required, else some tests might be skipped.

To run the test suite, run from the repository root

./setup.py test

To get a test coverage, run

make coverage

Versioning

This project uses bumpversion to increase version numbers.

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

sensemapi-0.5.0.tar.gz (59.2 kB view hashes)

Uploaded Source

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