# Weather Chatbot API Documentation
## =================================

**Author:** RSK World (https://rskworld.in)  
**Founded by:** Molla Samser  
**Designer & Tester:** Rima Khatun  
**Contact:** +91 93305 39277, hello@rskworld.in, support@rskworld.in  
**Location:** Nutanhat, Mongolkote, Purba Burdwan, West Bengal, India, 713147  
**Year:** 2026

---

## Base URL

```
http://localhost:5000
```

Production: `https://your-domain.com`

---

## Authentication

Currently, the API is open. For production use, implement API key authentication:

```
X-API-Key: your_api_key_here
```

---

## Endpoints

### 1. Health Check

Check if the API is running.

**Endpoint:** `GET /health`

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2026-01-15T10:30:00",
  "version": "1.0.0",
  "app": "Weather Chatbot"
}
```

**Status Codes:**
- `200 OK` - Service is healthy

---

### 2. Chat Interface

Send a natural language query and get weather information.

**Endpoint:** `POST /chat`

**Headers:**
```
Content-Type: application/x-www-form-urlencoded
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| message | string | Yes | Natural language weather query |

**Request Example:**
```bash
curl -X POST http://localhost:5000/chat \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=What is the weather in London?"
```

**Response Example (Current Weather):**
```json
{
  "city": "London",
  "country": "GB",
  "temperature": 15.5,
  "feels_like": 14.2,
  "humidity": 65,
  "pressure": 1013,
  "description": "clear sky",
  "icon": "01d",
  "wind_speed": 3.5,
  "visibility": 10,
  "timestamp": "2026-01-15 10:30:00"
}
```

**Response Example (Forecast):**
```json
{
  "city": "London",
  "country": "GB",
  "forecasts": [
    {
      "datetime": "2026-01-15 12:00:00",
      "temperature": 16,
      "feels_like": 15,
      "humidity": 60,
      "description": "clear sky",
      "icon": "01d",
      "wind_speed": 3.2,
      "rain": 0,
      "snow": 0
    }
  ]
}
```

**Response Example (Error):**
```json
{
  "error": "Failed to fetch weather data: City not found"
}
```

**Status Codes:**
- `200 OK` - Request successful
- `400 Bad Request` - Invalid request
- `500 Internal Server Error` - Server error

---

### 3. Get Current Weather

Get current weather for a specific city.

**Endpoint:** `GET /weather/<city>`

**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |

**Request Example:**
```bash
curl http://localhost:5000/weather/London
```

**Response:**
Same as Chat Interface current weather response.

**Status Codes:**
- `200 OK` - Request successful
- `404 Not Found` - City not found
- `500 Internal Server Error` - Server error

---

### 4. Get Weather Forecast

Get 5-day weather forecast for a specific city.

**Endpoint:** `GET /forecast/<city>`

**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |

**Query Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| days | integer | No | 5 | Number of forecast days (max 5) |

**Request Example:**
```bash
curl http://localhost:5000/forecast/London?days=3
```

**Response:**
Same as Chat Interface forecast response.

**Status Codes:**
- `200 OK` - Request successful
- `404 Not Found` - City not found
- `500 Internal Server Error` - Server error

---

### 5. Get Weather Alerts

Get weather alerts and warnings for a specific city.

**Endpoint:** `GET /alerts/<city>`

**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |

**Request Example:**
```bash
curl http://localhost:5000/alerts/London
```

**Response Example:**
```json
{
  "city": "London",
  "alerts": [
    {
      "event": "Heat Warning",
      "start": "2026-01-15 12:00:00",
      "end": "2026-01-15 18:00:00",
      "description": "Extreme heat expected. Stay hydrated.",
      "severity": "high"
    }
  ],
  "has_alerts": true
}
```

**Response Example (No Alerts):**
```json
{
  "city": "London",
  "alerts": [],
  "has_alerts": false
}
```

**Status Codes:**
- `200 OK` - Request successful
- `404 Not Found` - City not found
- `500 Internal Server Error` - Server error

---

## Error Responses

All endpoints may return error responses in the following format:

```json
{
  "error": "Error message description",
  "status": 400
}
```

### Common Error Codes

| Status Code | Description |
|-------------|-------------|
| 400 | Bad Request - Invalid parameters |
| 404 | Not Found - Resource not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server error |
| 503 | Service Unavailable - Service temporarily unavailable |

---

## Rate Limiting

The API implements rate limiting to prevent abuse:

- **30 requests per minute** per IP address
- **1000 requests per hour** per IP address
- **10000 requests per day** per IP address

When rate limit is exceeded, the API returns:
```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "retry_after": 60,
  "message": "Too many requests. Please try again later."
}
```

---

## Response Format

All successful responses are in JSON format with the following structure:

### Current Weather Response
```json
{
  "city": "string",
  "country": "string",
  "temperature": float,
  "feels_like": float,
  "humidity": integer,
  "pressure": float,
  "description": "string",
  "icon": "string",
  "wind_speed": float,
  "visibility": float,
  "timestamp": "string (ISO format)"
}
```

### Forecast Response
```json
{
  "city": "string",
  "country": "string",
  "forecasts": [
    {
      "datetime": "string",
      "temperature": float,
      "feels_like": float,
      "humidity": integer,
      "description": "string",
      "icon": "string",
      "wind_speed": float,
      "rain": float,
      "snow": float
    }
  ]
}
```

---

## Examples

### Python Example

```python
import requests

# Chat interface
response = requests.post(
    'http://localhost:5000/chat',
    data={'message': 'What is the weather in London?'}
)
data = response.json()
print(data)

# Get current weather
response = requests.get('http://localhost:5000/weather/London')
data = response.json()
print(f"Temperature: {data['temperature']}°C")

# Get forecast
response = requests.get('http://localhost:5000/forecast/London?days=3')
data = response.json()
print(f"Forecasts: {len(data['forecasts'])} periods")
```

### JavaScript Example

```javascript
// Chat interface
fetch('http://localhost:5000/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'message=What is the weather in London?'
})
.then(response => response.json())
.then(data => console.log(data));

// Get current weather
fetch('http://localhost:5000/weather/London')
  .then(response => response.json())
  .then(data => console.log(data));
```

### cURL Example

```bash
# Health check
curl http://localhost:5000/health

# Chat
curl -X POST http://localhost:5000/chat \
  -d "message=What is the weather in London?"

# Current weather
curl http://localhost:5000/weather/London

# Forecast
curl http://localhost:5000/forecast/London?days=3

# Alerts
curl http://localhost:5000/alerts/London
```

---

## Support

For API support and inquiries:

- **Email:** hello@rskworld.in, support@rskworld.in
- **Phone:** +91 93305 39277
- **Website:** https://rskworld.in

---

**© 2026 RSK World. All rights reserved.**