| Name | gridstatusio JSON |
| Version |
0.13.0
JSON |
| download |
| home_page | None |
| Summary | Python Client for GridStatus.io API |
| upload_time | 2025-07-11 21:59:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.10 |
| license | Copyright 2022 James Max Kanter
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
energy
independent system operator
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img width=75% src="/gridstatus-header.png" alt="gridstatus logo" />
</p>
<p align="center">
<a href="https://github.com/gridstatus/gridstatusio/actions/workflows/tests.yaml" target="_blank">
<img src="https://github.com/gridstatus/gridstatusio/actions/workflows/tests.yaml/badge.svg" alt="Tests" />
</a>
<a href="https://badge.fury.io/py/gridstatusio" target="_blank">
<img src="https://badge.fury.io/py/gridstatusio.svg?maxAge=2592000" alt="PyPI version">
</a>
</p>
# GridStatus.io Hosted API
Python client for accessing the [GridStatus.io Hosted API](https://www.gridstatus.io/api).
Browse all available datasets in our [Data Catalog](https://www.gridstatus.io/datasets).
## Installation
`gridstatusio` supports Python 3.10+. Install with pip:
```bash
pip install gridstatusio
```
Upgrade using the following command:
```bash
pip install --upgrade gridstatusio
```
## Getting Started
* Sign up for a Grid Status account and get your API key from the [Settings page](https://www.gridstatus.io/settings/api)
* Set your API key as an environment variable: `export GRIDSTATUS_API_KEY=your_api_key`
* **NOTE**: the Grid Status API has a 1 million rows per month limit on the free plan. This limit is _very_ easy to exceed when querying data, especially real time prices.
* Make sure to add `limit` to all of your `get_dataset` calls to avoid quickly exceeding the limit.
* The Grid Status API has rate limits that restrict the number of requests that are allowed each second, minute and hour. If rate limits are hit the client will automatically retry the request after a delay. You can configure the maximum number of retries using the `max_retries` parameter when initializing the client. If you find yourself hitting rate limits, you may need to add a delay between your requests. The [Grid Status Pricing Page](https://www.gridstatus.io/pricing) contains more details on specific rate limits.
Check out this example notebook: [Getting Started](/Examples/Getting%20Started.ipynb)
Other Examples:
- [ERCOT Pricing Data](/Examples/ERCOT%20Pricing%20Data.ipynb)
- [Finding Hubs and Zones in Pricing Data](/Examples/ISO%20Hubs.ipynb)
- [Stacked Net Load Visualization](/Examples/Stacked%20Net%20Load%20Visualization.ipynb)
- [CAISO April Net Load Analysis](/Examples/CAISO%20April%20Net%20Load.ipynb)
- [Resample Data to Different Frequencies](/Examples/Resample%20Data.ipynb)
## Retry Configuration
The client retries failed requests due to rate limits (429), server errors (5xx), and network issues using exponential backoff. You can customize retry behavior:
```python
client = GridStatusClient(
max_retries=3, # Maximum retries (default: 5)
base_delay=1.0, # Base delay in seconds (default: 2.0)
exponential_base=1.5, # Exponential backoff multiplier (default: 2.0)
)
```
The retry delay follows the formula `delay = base_delay * (exponential_base ** retry_count)`.
Retries are useful when:
* You're making pagination-heavy requests and risk hitting short-term rate limits
* A request fails due to a temporary server error
* A network issue or timeout interrupts the request
To disable retries entirely, set `max_retries=0`.
## Open Source
If you prefer to use an open source library that fetches data directly from the source, you can check out this [github repo](https://github.com/gridstatus/gridstatus).
## Get Help
We'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io
Raw data
{
"_id": null,
"home_page": null,
"name": "gridstatusio",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": "Max Kanter <kmax12@gmail.com>",
"keywords": "energy, independent system operator",
"author": null,
"author_email": "Max Kanter <kmax12@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/6f/11ff2f9e89915416e5b91eefaa26cd2bc10dc5218fc0a95e53590ecdf365/gridstatusio-0.13.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<img width=75% src=\"/gridstatus-header.png\" alt=\"gridstatus logo\" />\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/gridstatus/gridstatusio/actions/workflows/tests.yaml\" target=\"_blank\">\n <img src=\"https://github.com/gridstatus/gridstatusio/actions/workflows/tests.yaml/badge.svg\" alt=\"Tests\" />\n </a>\n <a href=\"https://badge.fury.io/py/gridstatusio\" target=\"_blank\">\n <img src=\"https://badge.fury.io/py/gridstatusio.svg?maxAge=2592000\" alt=\"PyPI version\">\n </a>\n</p>\n\n# GridStatus.io Hosted API\n\nPython client for accessing the [GridStatus.io Hosted API](https://www.gridstatus.io/api). \n\nBrowse all available datasets in our [Data Catalog](https://www.gridstatus.io/datasets).\n\n\n## Installation\n\n`gridstatusio` supports Python 3.10+. Install with pip:\n\n```bash\npip install gridstatusio\n```\n\nUpgrade using the following command:\n\n```bash\npip install --upgrade gridstatusio\n```\n\n## Getting Started\n\n* Sign up for a Grid Status account and get your API key from the [Settings page](https://www.gridstatus.io/settings/api)\n* Set your API key as an environment variable: `export GRIDSTATUS_API_KEY=your_api_key`\n* **NOTE**: the Grid Status API has a 1 million rows per month limit on the free plan. This limit is _very_ easy to exceed when querying data, especially real time prices.\n * Make sure to add `limit` to all of your `get_dataset` calls to avoid quickly exceeding the limit.\n* The Grid Status API has rate limits that restrict the number of requests that are allowed each second, minute and hour. If rate limits are hit the client will automatically retry the request after a delay. You can configure the maximum number of retries using the `max_retries` parameter when initializing the client. If you find yourself hitting rate limits, you may need to add a delay between your requests. The [Grid Status Pricing Page](https://www.gridstatus.io/pricing) contains more details on specific rate limits.\n\nCheck out this example notebook: [Getting Started](/Examples/Getting%20Started.ipynb)\n\nOther Examples:\n\n- [ERCOT Pricing Data](/Examples/ERCOT%20Pricing%20Data.ipynb)\n- [Finding Hubs and Zones in Pricing Data](/Examples/ISO%20Hubs.ipynb)\n- [Stacked Net Load Visualization](/Examples/Stacked%20Net%20Load%20Visualization.ipynb)\n- [CAISO April Net Load Analysis](/Examples/CAISO%20April%20Net%20Load.ipynb)\n- [Resample Data to Different Frequencies](/Examples/Resample%20Data.ipynb)\n\n## Retry Configuration\n\nThe client retries failed requests due to rate limits (429), server errors (5xx), and network issues using exponential backoff. You can customize retry behavior:\n\n```python\nclient = GridStatusClient(\n max_retries=3, # Maximum retries (default: 5)\n base_delay=1.0, # Base delay in seconds (default: 2.0)\n exponential_base=1.5, # Exponential backoff multiplier (default: 2.0)\n)\n```\n\nThe retry delay follows the formula `delay = base_delay * (exponential_base ** retry_count)`.\n\nRetries are useful when:\n\n* You're making pagination-heavy requests and risk hitting short-term rate limits\n* A request fails due to a temporary server error\n* A network issue or timeout interrupts the request\n\nTo disable retries entirely, set `max_retries=0`.\n\n## Open Source\n\nIf you prefer to use an open source library that fetches data directly from the source, you can check out this [github repo](https://github.com/gridstatus/gridstatus). \n\n## Get Help\n\nWe'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io\n",
"bugtrack_url": null,
"license": "Copyright 2022 James Max Kanter\n \n Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n \n 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n \n 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n \n 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.\n \n THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "Python Client for GridStatus.io API",
"version": "0.13.0",
"project_urls": {
"Issue Tracker": "https://github.com/kmax12/gridstatusio/issues",
"Source Code": "https://github.com/kmax12/gridstatusio/"
},
"split_keywords": [
"energy",
" independent system operator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c28830dddaba49c58a47629d642353e0fde080a9eb3d479d66c9657833d21f3a",
"md5": "56af146514bb15b7f4f5ca3341c035de",
"sha256": "7961e9d262320252e025f3bd6c0d28bad6127afa8c97aa1422d6972e63a33dad"
},
"downloads": -1,
"filename": "gridstatusio-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56af146514bb15b7f4f5ca3341c035de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 20175,
"upload_time": "2025-07-11T21:59:28",
"upload_time_iso_8601": "2025-07-11T21:59:28.631997Z",
"url": "https://files.pythonhosted.org/packages/c2/88/30dddaba49c58a47629d642353e0fde080a9eb3d479d66c9657833d21f3a/gridstatusio-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a06f11ff2f9e89915416e5b91eefaa26cd2bc10dc5218fc0a95e53590ecdf365",
"md5": "d6bda05376515fb4388409c3ed8ec431",
"sha256": "9736c978ac90f2c6bda055279cb2b04d540ee514a1529120cb826c6d7e9f0929"
},
"downloads": -1,
"filename": "gridstatusio-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "d6bda05376515fb4388409c3ed8ec431",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 919821,
"upload_time": "2025-07-11T21:59:30",
"upload_time_iso_8601": "2025-07-11T21:59:30.240861Z",
"url": "https://files.pythonhosted.org/packages/a0/6f/11ff2f9e89915416e5b91eefaa26cd2bc10dc5218fc0a95e53590ecdf365/gridstatusio-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 21:59:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kmax12",
"github_project": "gridstatusio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gridstatusio"
}
