docs: comprehensive update of all documentation - Paris, wind analysis, VPS deploy, supported cities table
This commit is contained in:
AmandaloveYang
@@ -1,6 +1,6 @@
|
||||
# 🌡️ PolyWeather: Real-time Weather Query & Analysis Bot
|
||||
|
||||
An intelligent weather information bot designed to provide ultra-fast, live meteorological data, high-fidelity forecasts, and smart trend analysis. Built for speed and accuracy, it bypasses network caching to deliver the most up-to-date reports from global weather stations.
|
||||
An intelligent weather bot for prediction markets and professional weather betting. Fetches ultra-fresh data directly from global weather stations, bypassing CDN caches, and provides automated trend analysis in plain language.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
@@ -8,19 +8,53 @@ An intelligent weather information bot designed to provide ultra-fast, live mete
|
||||
|
||||
- **Python 3.11+**
|
||||
- Dependencies: `pip install -r requirements.txt`
|
||||
- **Environment**: Configure `METEOBLUE_API_KEY` in `.env` to enable high-precision London forecasts.
|
||||
- **Environment Variables**: Set `TELEGRAM_BOT_TOKEN` in `.env` (required). Optionally set `METEOBLUE_API_KEY` for London high-precision forecasts.
|
||||
|
||||
### Running Locally (Windows/Linux)
|
||||
### VPS Deployment (Recommended)
|
||||
|
||||
**First-time setup:**
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
py -3.11 run.py
|
||||
|
||||
# Linux/VPS
|
||||
python3 run.py
|
||||
git clone https://github.com/yangyuan-zhen/PolyWeather.git
|
||||
cd PolyWeather
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env # Edit .env with your Token and API Keys
|
||||
```
|
||||
|
||||
_Note: The system is currently in **Weather Query Mode**. Legacy active market monitoring and automated trading modules are suspended._
|
||||
**Create one-click update script (run once):**
|
||||
|
||||
```bash
|
||||
cat > ~/update.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
cd ~/PolyWeather
|
||||
git fetch origin
|
||||
git reset --hard origin/main
|
||||
pkill -f run.py
|
||||
pkill -f bot_listener.py
|
||||
sleep 1
|
||||
nohup python3 run.py > bot.log 2>&1 &
|
||||
echo "✅ Updated and restarted!"
|
||||
EOF
|
||||
chmod +x ~/update.sh
|
||||
```
|
||||
|
||||
**Daily updates (after each code push):**
|
||||
|
||||
```bash
|
||||
~/update.sh
|
||||
```
|
||||
|
||||
> One command: pull latest code → kill old process → start new process. No branch conflict handling needed.
|
||||
|
||||
### Local Development (Windows)
|
||||
|
||||
```bash
|
||||
py -3.11 run.py
|
||||
```
|
||||
|
||||
> Local machine is for editing code and Git push only. IDE import errors are expected (dependencies not installed locally) and do not affect VPS operation.
|
||||
|
||||
_Note: The system is currently in **Weather Query Mode**. Legacy market monitoring and automated trading modules are suspended._
|
||||
|
||||
---
|
||||
|
||||
@@ -32,50 +66,75 @@ _Note: The system is currently in **Weather Query Mode**. Legacy active market m
|
||||
| `/id` | **Get Chat ID** | Retrieve your current Telegram Chat ID |
|
||||
| `/help` | **Help** | Display all available commands |
|
||||
|
||||
### Supported Cities
|
||||
|
||||
| City | Aliases | METAR Station | Extra Sources |
|
||||
|:---|:---|:---|:---|
|
||||
| London | `lon`, `伦敦` | EGLC (City Airport) | Meteoblue |
|
||||
| Paris | `par`, `巴黎` | LFPG (Charles de Gaulle) | — |
|
||||
| Ankara | `ank`, `安卡拉` | LTAC (Esenboğa) | MGM |
|
||||
| New York | `nyc`, `ny`, `纽约` | KLGA (LaGuardia) | NWS |
|
||||
| Chicago | `chi`, `芝加哥` | KORD (O'Hare) | NWS |
|
||||
| Dallas | `dal`, `达拉斯` | KDAL (Love Field) | NWS |
|
||||
| Miami | `mia`, `迈阿密` | KMIA (International) | NWS |
|
||||
| Atlanta | `atl`, `亚特兰大` | KATL (Hartsfield-Jackson) | NWS |
|
||||
| Seattle | `sea`, `西雅图` | KSEA (Sea-Tac) | NWS |
|
||||
| Toronto | `tor`, `多伦多` | CYYZ (Pearson) | — |
|
||||
| Seoul | `sel`, `首尔` | RKSI (Incheon) | — |
|
||||
| Buenos Aires | `ba`, `布宜诺斯艾利斯` | SAEZ (Ezeiza) | — |
|
||||
| Wellington | `wel`, `惠灵顿` | NZWN (Wellington) | — |
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
/city 巴黎
|
||||
/city london
|
||||
/city par
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
### 1. 🏛️ Multi-Source Data Fusion (High-Fidelity)
|
||||
|
||||
The bot aggregates data from multiple authoritative sources, layered by reliability:
|
||||
### 1. 🏛️ Multi-Source Data Fusion
|
||||
|
||||
| Source | Role | Coverage | Strength |
|
||||
| :----------------- | :---------------------- | :-------------- | :--------------------------------------------------------------------------------- |
|
||||
| **Open-Meteo** | Base Forecast | Global | Provides detailed 72-hour temperature curves for all cities. |
|
||||
| **Meteoblue (MB)** | **Precision Consensus** | London Only | **Traders' choice**. Aggregates multiple models; excellent for microclimates. |
|
||||
| **METAR** | **Settlement Standard** | Global Airports | The absolute truth for Polymarket settlement; real-time station data. |
|
||||
| **NWS** | Official (US) | US Only | High-fidelity forecasts for US cities, critical for extreme weather events. |
|
||||
| **MGM** | Official (Turkey) | Ankara | Direct access to Turkish State Meteorological Service for local official accuracy. |
|
||||
| **Open-Meteo** | Base Forecast | Global | 72-hour hourly temperature curves, sunrise/sunset times |
|
||||
| **Meteoblue (MB)** | **Precision Consensus** | London Only | Multi-model aggregation; excellent for microclimates |
|
||||
| **METAR** | **Settlement Standard** | Global Airports | Polymarket settlement source; real-time airport observations |
|
||||
| **NWS** | Official (US) | US Only | US National Weather Service high-fidelity forecasts |
|
||||
| **MGM** | Official (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall |
|
||||
|
||||
### 2. ⚡ Ultra-Fresh Data (Cache-Busting)
|
||||
### 2. ⚡ Ultra-Fresh Data (Zero-Cache)
|
||||
|
||||
To counter second-by-second variations in weather betting, we implemented **Zero-Cache Technology**:
|
||||
- **Dynamic Timestamps**: Every API request includes a unique token to force servers to bypass CDN caches.
|
||||
- **MGM Real-time Sync**: Specialized header camouflaging and timezone correction for Turkish API.
|
||||
|
||||
- **Micro-timestamp Tokens**: Every request includes a dynamic token to force servers to bypass CDN caches.
|
||||
- **MGM Real-time Sync**: Specialized header camouflaging to bypass local Turkish API anti-crawling for Ankara.
|
||||
### 3. 🧠 Smart Trend Analysis (Plain Language)
|
||||
|
||||
### 3. ⏱️ Automated Trend Analysis
|
||||
The bot generates human-readable insights automatically:
|
||||
|
||||
The bot doesn't just fetch data; it interprets it:
|
||||
- **🚨 Forecast Breakthrough Alerts**: Detects when METAR observed max exceeds all forecast highs.
|
||||
- **⏱️ Peak Window Prediction**: Identifies the exact hours when today's high is expected.
|
||||
- **🌬️ Wind Direction Cross-Validation**: Compares METAR and MGM wind data; alerts on conflicts (>90° difference).
|
||||
- **☁️ Cloud Impact Analysis**: Evaluates cloud cover's effect on warming potential.
|
||||
- **📉 Pressure Analysis**: Low pressure indicates warm/moist air passage.
|
||||
- **🌧️ Rain Detection**: Cross-validates METAR weather codes with actual rainfall data to avoid false positives.
|
||||
- **📊 Max Temperature Time Tracking**: Shows exactly when the daily high was recorded (e.g., `最高: 12°C @14:20`).
|
||||
|
||||
- **Peak Window Prediction**: Automatically identifies the timeframe when today's record is most likely to be hit.
|
||||
- **Risk Profiling**: Assigns risk levels based on geographic traits (e.g., Ankara high-altitude swings, London coastal microclimates).
|
||||
- **Source Attribution**: Every data point is clearly labeled ([MGM], [METAR], [MB]) to help you weigh the data.
|
||||
### 4. 📊 Risk Profiling
|
||||
|
||||
### 4. 📊 Smart Max-Temp Tracking
|
||||
Every city has a data bias risk profile based on airport-to-city-center distance:
|
||||
|
||||
Optimized for Polymarket settlement logic:
|
||||
|
||||
- **Local Day Filtering**: Uses city UTC offsets to strictly count observations after 00:00 local time.
|
||||
- **Multi-dimension Monitoring**: Includes "Feels Like" temperatures and 24h precipitation to assist in nuanced trade decisions.
|
||||
- 🔴 **High Risk**: Seoul (48.8km), Chicago (25.3km) — large bias expected
|
||||
- 🟡 **Medium Risk**: Ankara (24.5km), Paris (25.2km), Dallas, Buenos Aires — systematic bias
|
||||
- 🟢 **Low Risk**: London (12.7km), Wellington (5.1km) — reliable data
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ System Architecture
|
||||
|
||||
PolyWeather uses a **Lightweight, Plugin-based** architecture for millisecond responses.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
User[/Telegram User/] --> Bot[bot_listener.py]
|
||||
@@ -83,25 +142,30 @@ graph TD
|
||||
|
||||
subgraph "Data Engine"
|
||||
Collector --> OM[Open-Meteo API]
|
||||
Collector --> MB[Meteoblue Weather API]
|
||||
Collector --> NOAA[METAR Data Center]
|
||||
Collector --> MB[Meteoblue API]
|
||||
Collector --> NOAA[METAR / NOAA]
|
||||
Collector --> MGM[Turkish MGM API]
|
||||
Collector --> NWS[US NWS API]
|
||||
end
|
||||
|
||||
Collector --> Processing[Smart Analysis & Formatting]
|
||||
Processing --> Bot
|
||||
Bot --> Reponse[/Compact Betting Snapshot/]
|
||||
Bot --> Response[/Compact Betting Snapshot/]
|
||||
```
|
||||
|
||||
- **Logic Decoupling**: `weather_sources.py` handles parsing; `bot_listener.py` handles rendering.
|
||||
- **Legacy Modules**: `main.py` contains the old automated trading engine. Focus has shifted to "assisted manual decision-making."
|
||||
- **Logic Decoupling**: `weather_sources.py` handles data fetching & parsing; `bot_listener.py` handles analysis & rendering.
|
||||
- **City Config**: `city_risk_profiles.py` contains all METAR station mappings and risk assessments.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Betting Strategy Tips
|
||||
|
||||
1. **Check Consensus**: Compare Open-Meteo and Meteoblue (MB). Consensus usually implies higher probability.
|
||||
2. **Watch the Peak**: Use `/city` frequently during predicted peak windows to catch momentum.
|
||||
3. **Weighting Hierarchy**: Settlement is **METAR**; high-accuracy trend is **MB** (London); Official (NWS/MGM) is the "anchor."
|
||||
4. **Geographic Risk**: Pay close attention to cities where "Bias will significantly amplify."
|
||||
1. **Check Consensus**: Compare Open-Meteo, Meteoblue (MB), and NWS/MGM forecasts.
|
||||
2. **Watch the Peak Window**: Use `/city` frequently during predicted peak hours.
|
||||
3. **Settlement Priority**: Settlement is always based on **METAR** data.
|
||||
4. **Geographic Risk**: Pay attention to bias warnings, especially for high-risk cities.
|
||||
5. **Wind Conflicts**: When METAR and MGM show opposite wind directions, expect temperature volatility.
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-02-18_
|
||||
|
||||
Reference in New Issue
Block a user