API.md

# 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.**