# WeatherLink v2 API Python Library
A comprehensive Python library for accessing WeatherLink v2 API to retrieve meteorological and air quality data efficiently. Designed for developers, researchers, and weather enthusiasts who need fast, reliable access to weather station data.
## 🌟 Features
- **Professional API Integration**: Robust authentication and data retrieval
- **Flexible Operation Modes**: Choose between demo mode (testing/education) or production mode (your stations)
- **Sensor-Specific Processing**: Support for different sensor types with automatic field mapping
- **Comprehensive Data Processing**: Automatic unit conversions (Imperial ↔ Metric)
- **Advanced Visualization**: Built-in plotting functions for weather data analysis
- **Export Capabilities**: CSV export with customizable formats
- **Production Ready**: Error handling, validation, and professional-grade code structure
## 🚀 Quick Start
### Installation
```bash
pip install weatherlinkv2
```
Or install from source:
```bash
git clone https://github.com/Vendetta0462/weatherlinkv2.git
cd weatherlinkv2
pip install -e .
```
### Basic Usage
#### Demo Mode (Testing/Education)
```python
from weatherlinkv2 import WeatherLinkAPI, parse_weather_data
# Initialize API in demo mode for testing
api = WeatherLinkAPI(api_key="your_api_key", api_secret="your_api_secret", demo_mode=True)
# Get current weather data from demo station
current_data = api.get_current_data()
print(f"Current sensors: {len(current_data.get('sensors', []))}")
# Get historical data (limited to 24 hours in demo mode)
historic_data = api.get_historic_data(hours_back=24)
# Parse data for specific sensor type (e.g., AirLink sensor type 323)
df = parse_weather_data(historic_data, sensor_type=323, data_structure_type=17)
print(f"Retrieved {len(df)} air quality records")
```
#### Production Mode (Your Stations)
```python
# Initialize API for production use
api = WeatherLinkAPI(api_key="your_api_key", api_secret="your_api_secret", demo_mode=False)
# Get your stations and sensors
stations = api.get_stations()
sensors = api.get_sensors()
my_station_id = stations[0]['station_id_uuid']
# Get specific station information
station_info = api.get_station_info(my_station_id)
print(f"Station: {station_info.get('station_name')}")
# Get sensor information by sensor ID (lsid)
if sensors:
sensor_info = api.get_sensors_info(sensors[0]['lsid'])
print(f"Sensor type: {sensor_info.get('sensor_type')}")
# Get historical data with extended range for production
historic_data = api.get_historic_data(station_id=my_station_id, hours_back=168) # 7 days
# Parse data for weather station (sensor type 23)
df = parse_weather_data(historic_data, sensor_type=23)
print(f"Retrieved {len(df)} weather records")
```
## 📋 Requirements
- Python 3.7+
- WeatherLink API credentials (API Key + Secret)
- Internet connection
### Dependencies
- `requests` - HTTP requests
- `pandas` - Data manipulation
- `matplotlib` - Basic plotting
- `seaborn` - Enhanced visualizations
- `python-dotenv` - Environment variable management
## 🔧 API Credentials Setup
1. **Get API Credentials**: Visit the WeatherLink Developer Portal to obtain your API key and secret
2. **Create `.env` file**:
```env
WEATHERLINK_API_KEY=your_api_key_here
WEATHERLINK_API_SECRET=your_api_secret_here
```
3. **Load in your code**:
```python
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv('WEATHERLINK_API_KEY')
api_secret = os.getenv('WEATHERLINK_API_SECRET')
api = WeatherLinkAPI(api_key, api_secret)
```
## 📚 Examples
This library includes two example files to get you started:
### Basic Usage (`examples/basic_usage.py`)
Simple and direct example showing core functionality:
- API initialization with demo mode
- Getting stations and sensors
- Retrieving current and historical data
- Basic data parsing
### Sensor Types (`examples/sensor_types.py`)
Working with different sensor types:
- Exploring available sensor types
- Sensor-specific data parsing
- AirLink air quality sensors (type 323)
### Running Examples
In bash:
```bash
# Make sure you have your API credentials
export WEATHERLINK_API_KEY="your_api_key"
export WEATHERLINK_API_SECRET="your_api_secret"
# Run examples
python examples/basic_usage.py
python examples/sensor_types.py
```
## 🔍 API Reference
### WeatherLinkAPI Class
| Method | Description | Parameters |
|--------|-------------|------------|
| `__init__(api_key, api_secret, demo_mode)` | Initialize API client | API credentials, operation mode |
| `get_stations()` | Get available stations | None |
| `get_station_info(station_id)` | Get specific station info | Optional station ID if demo mode is enabled |
| `get_sensors()` | Get all available sensors | None |
| `get_sensors_info(sensor_id)` | Get specific sensor info | Sensor ID (lsid) |
| `get_current_data(station_id)` | Get current weather data | Station ID |
| `get_historic_data(station_id, hours_back)` | Get historical data | Station ID, hours back |
| `test_connection()` | Test API connection | None |
### Utility Functions
| Function | Description | Parameters | Returns |
|----------|-------------|------------|---------|
| `parse_weather_data(response, sensor_type, data_structure_type)` | Parse API response to DataFrame | API response, sensor type, optional structure type | pandas.DataFrame |
| `get_weather_summary(df)` | Generate statistics summary | DataFrame | dict |
| `create_weather_plots(df)` | Create visualization plots | DataFrame | matplotlib.Figure |
| `export_to_csv(df, filename)` | Export data to CSV | DataFrame, filename | str (file path) |
### Supported Sensor Types
| Sensor Type | Description | Data Structure Types |
|-------------|-------------|----------------------|
| 323 | AirLink (Air Quality) | 16 (Current), 17 (Archive) |
## ⚠️ Important Notes
### Data Units
The library provides both Imperial and Metric units depending on the sensor-structure pair. For a full list of the fields and units returned by the API, please refer to the official [WeatherLink v2 API Sensor Catalog](https://weatherlink.github.io/v2-api/interactive-sensor-catalog).
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License** - see the [LICENSE](LICENSE) file for details.
### Key License Terms:
- ✅ **Free for non-commercial use**: Research, education, personal projects
- ✅ **Open source friendly**: Use in other open source projects
- ❌ **No commercial use**: Cannot be used in proprietary or commercial software
- 🔄 **Share-alike**: Derivatives must use the same license
For commercial licensing options, please contact the maintainers.
**Powered by WeatherLink API 🌤️ | Made with Python 🐍**
Raw data
{
"_id": null,
"home_page": null,
"name": "weatherlinkv2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "weather, meteorology, weatherlink, api, climate, atmospheric, air quality, environmental monitoring",
"author": null,
"author_email": "Nicolas Mantilla-Molina <nicomantimol1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f2/0d/57a0e014a669c7f54aa13b214ac0fce369595225195d4c1d65a543bc2e07/weatherlinkv2-0.1.0.tar.gz",
"platform": null,
"description": "# WeatherLink v2 API Python Library\r\n\r\nA comprehensive Python library for accessing WeatherLink v2 API to retrieve meteorological and air quality data efficiently. Designed for developers, researchers, and weather enthusiasts who need fast, reliable access to weather station data.\r\n\r\n## \ud83c\udf1f Features\r\n\r\n- **Professional API Integration**: Robust authentication and data retrieval\r\n- **Flexible Operation Modes**: Choose between demo mode (testing/education) or production mode (your stations)\r\n- **Sensor-Specific Processing**: Support for different sensor types with automatic field mapping\r\n- **Comprehensive Data Processing**: Automatic unit conversions (Imperial \u2194 Metric)\r\n- **Advanced Visualization**: Built-in plotting functions for weather data analysis\r\n- **Export Capabilities**: CSV export with customizable formats\r\n- **Production Ready**: Error handling, validation, and professional-grade code structure\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install weatherlinkv2\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/Vendetta0462/weatherlinkv2.git\r\ncd weatherlinkv2\r\npip install -e .\r\n```\r\n\r\n### Basic Usage\r\n\r\n#### Demo Mode (Testing/Education)\r\n```python\r\nfrom weatherlinkv2 import WeatherLinkAPI, parse_weather_data\r\n\r\n# Initialize API in demo mode for testing\r\napi = WeatherLinkAPI(api_key=\"your_api_key\", api_secret=\"your_api_secret\", demo_mode=True)\r\n\r\n# Get current weather data from demo station\r\ncurrent_data = api.get_current_data()\r\nprint(f\"Current sensors: {len(current_data.get('sensors', []))}\")\r\n\r\n# Get historical data (limited to 24 hours in demo mode)\r\nhistoric_data = api.get_historic_data(hours_back=24)\r\n\r\n# Parse data for specific sensor type (e.g., AirLink sensor type 323)\r\ndf = parse_weather_data(historic_data, sensor_type=323, data_structure_type=17)\r\nprint(f\"Retrieved {len(df)} air quality records\")\r\n```\r\n\r\n#### Production Mode (Your Stations)\r\n```python\r\n# Initialize API for production use\r\napi = WeatherLinkAPI(api_key=\"your_api_key\", api_secret=\"your_api_secret\", demo_mode=False)\r\n\r\n# Get your stations and sensors\r\nstations = api.get_stations()\r\nsensors = api.get_sensors()\r\nmy_station_id = stations[0]['station_id_uuid']\r\n\r\n# Get specific station information\r\nstation_info = api.get_station_info(my_station_id)\r\nprint(f\"Station: {station_info.get('station_name')}\")\r\n\r\n# Get sensor information by sensor ID (lsid)\r\nif sensors:\r\n sensor_info = api.get_sensors_info(sensors[0]['lsid'])\r\n print(f\"Sensor type: {sensor_info.get('sensor_type')}\")\r\n\r\n# Get historical data with extended range for production\r\nhistoric_data = api.get_historic_data(station_id=my_station_id, hours_back=168) # 7 days\r\n\r\n# Parse data for weather station (sensor type 23)\r\ndf = parse_weather_data(historic_data, sensor_type=23)\r\nprint(f\"Retrieved {len(df)} weather records\")\r\n```\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.7+\r\n- WeatherLink API credentials (API Key + Secret)\r\n- Internet connection\r\n\r\n### Dependencies\r\n\r\n- `requests` - HTTP requests\r\n- `pandas` - Data manipulation\r\n- `matplotlib` - Basic plotting\r\n- `seaborn` - Enhanced visualizations\r\n- `python-dotenv` - Environment variable management\r\n\r\n## \ud83d\udd27 API Credentials Setup\r\n\r\n1. **Get API Credentials**: Visit the WeatherLink Developer Portal to obtain your API key and secret\r\n2. **Create `.env` file**:\r\n\r\n```env\r\nWEATHERLINK_API_KEY=your_api_key_here\r\nWEATHERLINK_API_SECRET=your_api_secret_here\r\n```\r\n\r\n3. **Load in your code**:\r\n\r\n```python\r\nfrom dotenv import load_dotenv\r\nimport os\r\n\r\nload_dotenv()\r\napi_key = os.getenv('WEATHERLINK_API_KEY')\r\napi_secret = os.getenv('WEATHERLINK_API_SECRET')\r\n\r\napi = WeatherLinkAPI(api_key, api_secret)\r\n```\r\n\r\n## \ud83d\udcda Examples\r\n\r\nThis library includes two example files to get you started:\r\n\r\n### Basic Usage (`examples/basic_usage.py`)\r\nSimple and direct example showing core functionality:\r\n- API initialization with demo mode\r\n- Getting stations and sensors\r\n- Retrieving current and historical data\r\n- Basic data parsing\r\n\r\n### Sensor Types (`examples/sensor_types.py`)\r\nWorking with different sensor types:\r\n- Exploring available sensor types\r\n- Sensor-specific data parsing\r\n- AirLink air quality sensors (type 323)\r\n\r\n### Running Examples\r\n\r\nIn bash:\r\n\r\n```bash\r\n# Make sure you have your API credentials\r\nexport WEATHERLINK_API_KEY=\"your_api_key\"\r\nexport WEATHERLINK_API_SECRET=\"your_api_secret\"\r\n\r\n# Run examples\r\npython examples/basic_usage.py\r\npython examples/sensor_types.py\r\n```\r\n\r\n## \ud83d\udd0d API Reference\r\n\r\n### WeatherLinkAPI Class\r\n\r\n| Method | Description | Parameters |\r\n|--------|-------------|------------|\r\n| `__init__(api_key, api_secret, demo_mode)` | Initialize API client | API credentials, operation mode |\r\n| `get_stations()` | Get available stations | None |\r\n| `get_station_info(station_id)` | Get specific station info | Optional station ID if demo mode is enabled |\r\n| `get_sensors()` | Get all available sensors | None |\r\n| `get_sensors_info(sensor_id)` | Get specific sensor info | Sensor ID (lsid) |\r\n| `get_current_data(station_id)` | Get current weather data | Station ID |\r\n| `get_historic_data(station_id, hours_back)` | Get historical data | Station ID, hours back |\r\n| `test_connection()` | Test API connection | None |\r\n\r\n### Utility Functions\r\n\r\n| Function | Description | Parameters | Returns |\r\n|----------|-------------|------------|---------|\r\n| `parse_weather_data(response, sensor_type, data_structure_type)` | Parse API response to DataFrame | API response, sensor type, optional structure type | pandas.DataFrame |\r\n| `get_weather_summary(df)` | Generate statistics summary | DataFrame | dict |\r\n| `create_weather_plots(df)` | Create visualization plots | DataFrame | matplotlib.Figure |\r\n| `export_to_csv(df, filename)` | Export data to CSV | DataFrame, filename | str (file path) |\r\n\r\n### Supported Sensor Types\r\n\r\n| Sensor Type | Description | Data Structure Types |\r\n|-------------|-------------|----------------------|\r\n| 323 | AirLink (Air Quality) | 16 (Current), 17 (Archive) |\r\n\r\n## \u26a0\ufe0f Important Notes\r\n\r\n### Data Units\r\n\r\nThe library provides both Imperial and Metric units depending on the sensor-structure pair. For a full list of the fields and units returned by the API, please refer to the official [WeatherLink v2 API Sensor Catalog](https://weatherlink.github.io/v2-api/interactive-sensor-catalog).\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License** - see the [LICENSE](LICENSE) file for details.\r\n\r\n### Key License Terms:\r\n- \u2705 **Free for non-commercial use**: Research, education, personal projects\r\n- \u2705 **Open source friendly**: Use in other open source projects\r\n- \u274c **No commercial use**: Cannot be used in proprietary or commercial software\r\n- \ud83d\udd04 **Share-alike**: Derivatives must use the same license\r\n\r\nFor commercial licensing options, please contact the maintainers.\r\n\r\n**Powered by WeatherLink API \ud83c\udf24\ufe0f | Made with Python \ud83d\udc0d**\r\n",
"bugtrack_url": null,
"license": "CC-BY-NC-SA-4.0",
"summary": "Professional Python library for WeatherLink v2 API integration",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Vendetta0462/weatherlinkv2/issues",
"Homepage": "https://github.com/Vendetta0462/weatherlinkv2",
"Repository": "https://github.com/Vendetta0462/weatherlinkv2"
},
"split_keywords": [
"weather",
" meteorology",
" weatherlink",
" api",
" climate",
" atmospheric",
" air quality",
" environmental monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "282aa1dbb7727a6ce436e924ab0ac53434f596fac72d28b63edccb614896532f",
"md5": "a10c0a4591d612e529564f4d1523d200",
"sha256": "620fd7c69340bd83490c02481c1ede9a820014caa98ef038ec138333a87440d4"
},
"downloads": -1,
"filename": "weatherlinkv2-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a10c0a4591d612e529564f4d1523d200",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13522,
"upload_time": "2025-08-14T04:17:14",
"upload_time_iso_8601": "2025-08-14T04:17:14.944748Z",
"url": "https://files.pythonhosted.org/packages/28/2a/a1dbb7727a6ce436e924ab0ac53434f596fac72d28b63edccb614896532f/weatherlinkv2-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f20d57a0e014a669c7f54aa13b214ac0fce369595225195d4c1d65a543bc2e07",
"md5": "b7918a94a6900ffc3d0ef96045db93eb",
"sha256": "491a91104c89f4a7ab1d6f7a26f182f3cd8d10cdd9219035edf3390e3d73b909"
},
"downloads": -1,
"filename": "weatherlinkv2-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b7918a94a6900ffc3d0ef96045db93eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19614,
"upload_time": "2025-08-14T04:17:16",
"upload_time_iso_8601": "2025-08-14T04:17:16.573628Z",
"url": "https://files.pythonhosted.org/packages/f2/0d/57a0e014a669c7f54aa13b214ac0fce369595225195d4c1d65a543bc2e07/weatherlinkv2-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 04:17:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Vendetta0462",
"github_project": "weatherlinkv2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.3.0"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.11.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
}
],
"lcname": "weatherlinkv2"
}
JSON
