# SenseMAPI - Pythonic access to the OpenSenseMap API
[](https://gitlab.com/tue-umphy/co2mofetten/software/python3-sensemapi/commits/master)
[](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/coverage-report/)
[](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/)
[](https://badge.fury.io/py/sensemapi)
[](https://pepy.tech/project/sensemapi)
`sensemapi` is a Python package to access the [OpenSenseMap
API](https://api.opensensemap.org).
> ## Disclaimer
>
> This software was developed within the context of a
> [CO2 monitoring project](https://gitlab.com/tue-umphy/co2mofetten)
> of the University of Tübingen, Germany. The developer is not in any
> way affiliated with the [senseBox project](https://www.sensebox.de/en/).
## What can `sensemapi` do?
With `sensemapi`, you can do the most important things that you can also do via
the [OpenSenseMap user interface](https://opensensemap.org).
See some examples:
### Access an OpenSenseMap account
```python
account = sensemapi.account.SenseMapAccount(
email = "SENSEMAP_EMAIL",
password = os.environ.get("SENSEMAP_PASSWORD")
)
```
### Create new senseBoxes
```python
# 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
```python
# 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
```python
# 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
```python
# delete the account's first senseBox
account.delete_box(account.boxes[0].id, really=True)
```
### Retreive any senseBox by its ID
```python
# with an account
account.get_box(id = "57000b8745fd40c8196ad04c")
# without an account
sensemapi.client.SenseMapClient().get_box(id = "57000b8745fd40c8196ad04c")
```
### Retreive measurements of a senseBox sensor
```python
# 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
```
```bash
# 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:
```bash
pip3 install --user sensemapi
pip3 install --user pandas # if you want pandas support
```
This downloads and installs the package from the [Python Package
Index](https://pypi.org).
You may also install `sensemapi` via `pip3` from the repository root:
```bash
pip3 install --user .
```
## Documentation
Documentation of the `sensemapi` package can be found [here on
GitLab](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/).
## 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](https://testing.opensensemap.org/) is
required. Details of this account must then be passed as environment
variables, for example:
```bash
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
`source`d.
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
```bash
./setup.py test
```
To get a test coverage, run
```bash
make coverage
```
### Versioning
This project uses [bumpversion](https://pypi.org/project/bumpversion/) to
increase version numbers.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/tue-umphy/co2mofetten/software/python3-sensemapi",
"name": "sensemapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "opensensemap,sensemap,api",
"author": "Yann B\u00fcchau",
"author_email": "nobodyinperson@gmx.de",
"download_url": "https://files.pythonhosted.org/packages/73/41/33478cbd58d7b5e01f93c21e0d2605e53cf1227b95bf1b8f7d23c3a3392b/sensemapi-0.5.0.tar.gz",
"platform": null,
"description": "# SenseMAPI - Pythonic access to the OpenSenseMap API\n\n[](https://gitlab.com/tue-umphy/co2mofetten/software/python3-sensemapi/commits/master) \n[](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/coverage-report/)\n[](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/) \n[](https://badge.fury.io/py/sensemapi)\n[](https://pepy.tech/project/sensemapi)\n\n`sensemapi` is a Python package to access the [OpenSenseMap\nAPI](https://api.opensensemap.org).\n\n> ## Disclaimer\n>\n> This software was developed within the context of a\n> [CO2 monitoring project](https://gitlab.com/tue-umphy/co2mofetten)\n> of the University of T\u00fcbingen, Germany. The developer is not in any\n> way affiliated with the [senseBox project](https://www.sensebox.de/en/).\n\n## What can `sensemapi` do?\n\nWith `sensemapi`, you can do the most important things that you can also do via\nthe [OpenSenseMap user interface](https://opensensemap.org).\n\nSee some examples:\n\n### Access an OpenSenseMap account\n\n```python\naccount = sensemapi.account.SenseMapAccount(\n email = \"SENSEMAP_EMAIL\",\n password = os.environ.get(\"SENSEMAP_PASSWORD\")\n )\n```\n\n### Create new senseBoxes\n\n```python\n# set up a senseBox (offline)\nbox = sensemapi.senseBox.senseBox(\n exposure = \"outdoor\",\n name=\"My senseBox\",\n current_lat=50.5,\n current_lon=10.1)\n# add a temperature sensor to the box (offline)\nbox.new_sensor(\n title=\"temperature\",\n unit=\"\u00b0C\",\n type=\"SHT31\",\n icon=\"osem-temperature-celsius\")\n# create the senseBox (online)\naccount.new_box(box)\n```\n\n### Modify senseBoxes and sensors\n\n```python\n# retreive the account's boxes\naccount.get_own_boxes()\n# choose the first box\nbox = account.boxes[0]\n# change the box\nbox.name = \"My supercool senseBox\"\n# ... do anything with the box object ...\n# upload the changes\nbox.upload_metadata()\n```\n\n### Upload measurements\n\n```python\n# select the box's first sensor\nsensor = box.sensors[0]\n# reset the time to use the current time\nsensor.last_time = None\n# specify measurement value\nsensor.last_value = 25.2\n# upload the measurement\nsensor.upload_measurement()\n```\n\n### Delete a senseBox\n\n```python\n# delete the account's first senseBox\naccount.delete_box(account.boxes[0].id, really=True)\n```\n\n### Retreive any senseBox by its ID\n\n```python\n# with an account\naccount.get_box(id = \"57000b8745fd40c8196ad04c\")\n# without an account\nsensemapi.client.SenseMapClient().get_box(id = \"57000b8745fd40c8196ad04c\")\n```\n\n### Retreive measurements of a senseBox sensor\n\n```python\n# get a box\nbox = sensemapi.client.SenseMapClient().get_box(id=\"57000b8745fd40c8196ad04c\")\n# the box' first sensor\nsensor = box.sensors[0]\n# get the sensor's latest measurements as pandas.Series\nseries = sensor.get_measurements().series\n```\n\n```bash\n# Or download CSV data from the command-line:\nsensemapi download --sensebox 5d35d315953683001a2b877a --from 2022-02 --to 2022-03 -o data.csv\n```\n\n## Installation\n\nThe `sensemapi` package is best installed via `pip3`. Run from anywhere:\n\n```bash\npip3 install --user sensemapi\npip3 install --user pandas # if you want pandas support\n```\n\nThis downloads and installs the package from the [Python Package\nIndex](https://pypi.org).\n\nYou may also install `sensemapi` via `pip3` from the repository root:\n\n```bash\npip3 install --user .\n```\n\n## Documentation\n\nDocumentation of the `sensemapi` package can be found [here on\nGitLab](https://tue-umphy.gitlab.io/co2mofetten/software/python3-sensemapi/).\n\n## Development\n\nThe following might only be interesting for developers\n\n### Tests\n\nFor running the full test suite, a registered and activated account at the \n[Testing Stage of the OpenSenseMap](https://testing.opensensemap.org/) is \nrequired. Details of this account must then be passed as environment\n variables, for example: \n\n```bash\nexport SENSEMAP_EMAIL=\"user@email.com\" # specify either the email...\nexport SENSEMAP_USER=\"username\" # or the username\nexport SENSEMAP_PASSWORD=\"5uP3rP45sW0Rd\"\n```\n\nYou may also specifiy this sensitive data in a file which can then be\n`source`d.\n\nFor running the tests, `SENSEMAP_EMAIL` and `SENSEMAP_PASSWORD` are required, \nelse some tests might be skipped.\n\nTo run the test suite, run from the repository root\n\n```bash\n./setup.py test\n```\n\nTo get a test coverage, run\n\n```bash\nmake coverage\n```\n\n### Versioning\n\nThis project uses [bumpversion](https://pypi.org/project/bumpversion/) to\nincrease version numbers.\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Pythonic access to the OpenSenseMap API",
"version": "0.5.0",
"split_keywords": [
"opensensemap",
"sensemap",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "734133478cbd58d7b5e01f93c21e0d2605e53cf1227b95bf1b8f7d23c3a3392b",
"md5": "f8ff341de89402024d2f1f5824bf4d24",
"sha256": "a954ace2c46abdd0692f7f6d5ab28cd1a7c9b52bb62a46484fec2279fdf0169d"
},
"downloads": -1,
"filename": "sensemapi-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "f8ff341de89402024d2f1f5824bf4d24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 59174,
"upload_time": "2023-02-02T15:36:07",
"upload_time_iso_8601": "2023-02-02T15:36:07.591787Z",
"url": "https://files.pythonhosted.org/packages/73/41/33478cbd58d7b5e01f93c21e0d2605e53cf1227b95bf1b8f7d23c3a3392b/sensemapi-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-02 15:36:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "sensemapi"
}
JSON