| Name | clarityio JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Retrieve air quality data from the Clarity.io API |
| upload_time | 2024-08-26 20:17:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# clarityio
This package wraps the API for Clarity air quality sensors. It makes calls to [v2 of the API](https://api-guide.clarity.io/), which as of August 2024 is the newest version of the API.
## Development status
This package is in beta status. Some functionality is still missing, but it is being used in production at the City of Ann Arbor.
### Implemented endpoints
- Recent measurements: `POST {baseUrl}/v2/recent-datasource-measurements-query `
- Per-Org Datasources summary: `GET {baseURl}/v2/datasources`
- Per-Datasource details: `GET {baseURl}/v2/datasources/:datasourceId `
### Not yet implemented
- Continuations
- Historical measurements
- All other endpoints.
## Installation
Install from PyPI:
```
pip install clarityio
```
## Usage
### Initialize API connection
Find your API key and org in your Clarity.io user profile. Log in at https://dashboard.clarity.io, then click the person icon on the top-right corner.
Use these values to initialize a connection:
```python
import clarityio
import pandas as pd
api_connection = clarityio.ClarityAPIConnection(api_key='YOUR_API_KEY', org='YOUR_ORG')
```
Both of these values are required to make calls to the Clarity API and are appended as needed by this package.
### Retrieve recent measurements
See API docs for valid arguments to pass, e.g., retrieve daily data instead of hourly.
The default value of `format` is `json-long`, which returns the data in long format (one row per combination of metric and time). Here is such a call:
```python
request_body = {
'allDatasources': True,
'outputFrequency': 'hour',
'format': 'json-long',
'startTime': '2024-07-22T00:00:00Z'
}
response = api_connection.get_recent_measurements(data=request_body)
df = pd.DataFrame(response['data'])
```
To get the data in wide format, with one row per timestamp and each metric in its own column, use the `csv-wide` format option and convert to a pandas dataframe:
```python
request_body = {
'allDatasources': True,
'outputFrequency': 'hour',
'format': 'csv-wide',
'metricSelect': 'only pm2_5ConcMass24HourRollingMean' # Refer to API documentation for metric selection
}
response_wide = api_connection.get_recent_measurements(data=request_body)
from io import StringIO
df_wide = pd.read_csv(StringIO(response_wide), sep=",")
```
### List data sources
```python
datasources_response = api_connection.get_datasources()
datasources = pd.json_normalize(datasources_response['datasources'])
```
### Get details for a specific data source
Obtain the IDs from the prior block of code.
```python
source_details_response = api_connection.get_datasource_details('A_DATA_SOURCE_ID')
source_details = pd.json_normalize(source_details_response['datasource'])
```
### Convert a raw measurement to the EPA AQI scale
The Clarity API provides some of these values, but this utility function offers more flexibility for custom data processing.
```python
clarityio.scale_raw_to_aqi('pm2.5_24hr', 18.84) # 69.14676806083651
clarityio.scale_raw_to_aqi('nitrogen_dioxide_1hr', 300) # 138.64864864864865
```
Raw data
{
"_id": null,
"home_page": null,
"name": "clarityio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Sam Firke <samuel.firke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/73/d6/21d156c37fe40b5e70b3ed6203a4c6f062c8c34ba29745abcffc0163b112/clarityio-0.3.0.tar.gz",
"platform": null,
"description": "# clarityio\n\nThis package wraps the API for Clarity air quality sensors. It makes calls to [v2 of the API](https://api-guide.clarity.io/), which as of August 2024 is the newest version of the API.\n\n\n## Development status\n\nThis package is in beta status. Some functionality is still missing, but it is being used in production at the City of Ann Arbor. \n\n### Implemented endpoints\n\n- Recent measurements: `POST {baseUrl}/v2/recent-datasource-measurements-query `\n- Per-Org Datasources summary: `GET {baseURl}/v2/datasources`\n- Per-Datasource details: `GET {baseURl}/v2/datasources/:datasourceId `\n\n### Not yet implemented\n\n- Continuations\n- Historical measurements\n- All other endpoints.\n\n\n## Installation\n\nInstall from PyPI:\n```\npip install clarityio\n```\n\n## Usage\n\n### Initialize API connection\n\nFind your API key and org in your Clarity.io user profile. Log in at https://dashboard.clarity.io, then click the person icon on the top-right corner.\n\nUse these values to initialize a connection:\n\n```python\nimport clarityio\nimport pandas as pd\napi_connection = clarityio.ClarityAPIConnection(api_key='YOUR_API_KEY', org='YOUR_ORG')\n```\nBoth of these values are required to make calls to the Clarity API and are appended as needed by this package.\n\n### Retrieve recent measurements\n\nSee API docs for valid arguments to pass, e.g., retrieve daily data instead of hourly. \n\nThe default value of `format` is `json-long`, which returns the data in long format (one row per combination of metric and time). Here is such a call:\n\n```python\nrequest_body = {\n 'allDatasources': True,\n 'outputFrequency': 'hour',\n 'format': 'json-long',\n 'startTime': '2024-07-22T00:00:00Z'\n}\nresponse = api_connection.get_recent_measurements(data=request_body)\ndf = pd.DataFrame(response['data'])\n```\n\nTo get the data in wide format, with one row per timestamp and each metric in its own column, use the `csv-wide` format option and convert to a pandas dataframe:\n\n```python\nrequest_body = {\n 'allDatasources': True,\n 'outputFrequency': 'hour',\n 'format': 'csv-wide',\n 'metricSelect': 'only pm2_5ConcMass24HourRollingMean' # Refer to API documentation for metric selection\n}\nresponse_wide = api_connection.get_recent_measurements(data=request_body)\nfrom io import StringIO\ndf_wide = pd.read_csv(StringIO(response_wide), sep=\",\")\n```\n\n### List data sources\n```python\ndatasources_response = api_connection.get_datasources()\ndatasources = pd.json_normalize(datasources_response['datasources'])\n```\n\n### Get details for a specific data source\n\nObtain the IDs from the prior block of code.\n```python\nsource_details_response = api_connection.get_datasource_details('A_DATA_SOURCE_ID')\nsource_details = pd.json_normalize(source_details_response['datasource'])\n```\n\n### Convert a raw measurement to the EPA AQI scale\n\nThe Clarity API provides some of these values, but this utility function offers more flexibility for custom data processing.\n```python\nclarityio.scale_raw_to_aqi('pm2.5_24hr', 18.84) # 69.14676806083651\nclarityio.scale_raw_to_aqi('nitrogen_dioxide_1hr', 300) # 138.64864864864865\n```",
"bugtrack_url": null,
"license": null,
"summary": "Retrieve air quality data from the Clarity.io API",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/a2gov/clarityio",
"Issues": "https://github.com/a2gov/clarityio/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "74df428467c136cf8e7c3c787ce7145a87d495c6f5328c73ae2106c9451389dc",
"md5": "c102ca63b8fc6545f8748a516913dbf5",
"sha256": "6a8663ae8c23ba34a4c3d925f60f7898b0d61c9d23b3a3498e54ebc6554adbed"
},
"downloads": -1,
"filename": "clarityio-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c102ca63b8fc6545f8748a516913dbf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5661,
"upload_time": "2024-08-26T20:17:51",
"upload_time_iso_8601": "2024-08-26T20:17:51.489195Z",
"url": "https://files.pythonhosted.org/packages/74/df/428467c136cf8e7c3c787ce7145a87d495c6f5328c73ae2106c9451389dc/clarityio-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73d621d156c37fe40b5e70b3ed6203a4c6f062c8c34ba29745abcffc0163b112",
"md5": "eff6a86ecd64c7c1a0ac29c215f0fe6b",
"sha256": "6559f8e916fa5b2dde72312b9bf8bdd483ba2c1f9c4bb86bff3ca55cd752ee12"
},
"downloads": -1,
"filename": "clarityio-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "eff6a86ecd64c7c1a0ac29c215f0fe6b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7681,
"upload_time": "2024-08-26T20:17:52",
"upload_time_iso_8601": "2024-08-26T20:17:52.728159Z",
"url": "https://files.pythonhosted.org/packages/73/d6/21d156c37fe40b5e70b3ed6203a4c6f062c8c34ba29745abcffc0163b112/clarityio-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 20:17:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "a2gov",
"github_project": "clarityio",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "clarityio"
}
