warsaw-public-transport 1.0.0
FastAPI-based API for Warsaw public transport real-time data
License: MIT
Requires Python: >=3.8
Keywords: warsaw, transport, api, fastapi, real-time, buses, trams, public-transport

# 🚌 Warsaw Public Transport API

[![Python Version](https://img.shields.io/pypi/pyversions/warsaw-public-transport)](https://pypi.org/project/warsaw-public-transport/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A FastAPI-based REST API for accessing Warsaw public transport real-time data. Track buses, trams, and get schedule information for all stops in Warsaw.

## 🎯 Features

- **Real-time vehicle tracking** - Get current location of buses and trams
- **Stop schedules** - Access timetables for any stop in Warsaw
- **Route information** - Find all stops and vehicles on a route
- **Stop search** - Search stops by name
- **Next arrivals** - See upcoming vehicles with countdown timers
- **Fast & Modern** - Built with FastAPI and Pydantic v2
- **Interactive docs** - Auto-generated Swagger UI documentation

## 🚀 Quick Start

### Installation

```bash
pip install warsaw-public-transport
```

### Get API Key

1. Register at [Warsaw Open Data Portal](https://api.um.warszawa.pl/)
2. Get your free API key

### Run the Server

```bash
# Set your API key
export WARSAW_DATA_API_KEY="your-api-key-here"

# Run the server
warsaw-transport
```

Or using Python module:

```bash
python -m warsaw_public_transport
```

The API will be available at `http://localhost:8000`

📖 **Interactive documentation**: http://localhost:8000/docs

## 📚 API Endpoints

### Transport Location

- `GET /api/buses/location` - Get all buses location
- `GET /api/trams/location` - Get all trams location
- `GET /api/routes/{route}/location` - Get all vehicles on a route

### Stops Information

- `GET /api/stops` - List all stops
- `GET /api/stops/search/{name}` - Find stop by name
- `GET /api/stops/{id}/lines` - Get routes for a stop
- `GET /api/stops/{id}/schedule` - Get stop schedule
- `GET /api/stops/{id}/next-arrivals` - Get next arrivals with countdown

### Route Information

- `GET /api/routes/{route}/stops` - Get all stops on a route

## 💡 Usage Examples

### Python

```python
import requests

# Get buses on route 182
response = requests.get(
    'http://localhost:8000/api/routes/182/location',
    params={'vehicle_type': 'bus'}
)
data = response.json()
print(f"Found {data['vehicles_count']} buses")

# Search for a stop
response = requests.get('http://localhost:8000/api/stops/search/Marszałkowska')
stop = response.json()
print(f"Stop ID: {stop['stop_id']}")

# Get next arrivals
response = requests.get(
    f"http://localhost:8000/api/stops/{stop['stop_id']}/next-arrivals",
    params={'bus_stop_nr': '01', 'minutes': 30}
)
arrivals = response.json()
for arrival in arrivals['next_arrivals'][:5]:
    print(f"Line {arrival['line']}: {arrival['minutes_until']} min - {arrival['direction']}")
```

### cURL

```bash
# Health check
curl http://localhost:8000/

# Get trams on route 17
curl "http://localhost:8000/api/routes/17/location?vehicle_type=tram"

# Find a stop
curl "http://localhost:8000/api/stops/search/Centrum"

# Get schedule
curl "http://localhost:8000/api/stops/7009/schedule?line=182&bus_stop_nr=01"

# Get next arrivals with countdown
curl "http://localhost:8000/api/stops/7009/next-arrivals?bus_stop_nr=01&minutes=60"
```

### JavaScript/TypeScript

```typescript
// Fetch buses on route
const fetchBuses = async (route: string) => {
  const response = await fetch(
    `http://localhost:8000/api/routes/${route}/location?vehicle_type=bus`
  );
  const data = await response.json();
  return data;
};

// Get next arrivals
const getNextArrivals = async (stopId: string) => {
  const response = await fetch(
    `http://localhost:8000/api/stops/${stopId}/next-arrivals?bus_stop_nr=01&minutes=30`
  );
  const data = await response.json();
  return data.next_arrivals;
};
```

## 🔧 Configuration

### Environment Variables

```bash
# Required
WARSAW_DATA_API_KEY=your-api-key-here

# Optional
PORT=8000                    # Server port (default: 8000)
HOST=0.0.0.0                # Server host (default: 0.0.0.0)
```

### Using .env file

Create a `.env` file in your project directory:

```env
WARSAW_DATA_API_KEY=your-api-key-here
PORT=8000
```

## 🐍 Programmatic Usage

You can also use the library programmatically without running the server:

```python
from warsaw_public_transport import WarsawTransportAPI

# Initialize client
api = WarsawTransportAPI(api_key="your-api-key")

# Get buses location
buses = api.get_buses_location(line="182")
for bus in buses:
    print(f"Bus {bus.lines} at ({bus.location.latitude}, {bus.location.longitude})")

# Get stop schedule
schedule = api.get_stop_schedule(
    stop_id="7009",
    stop_nr="01",
    line="182"
)
for ride in schedule.rides:
    print(f"{ride.time} - {ride.direction}")

# Search for a stop
stop_id = api.get_bus_stop_id_by_name("Marszałkowska")
print(f"Stop ID: {stop_id}")

# Get all stops
stops = api.get_all_stops()
print(f"Total stops: {len(stops)}")
```

## 📦 Response Examples

### Vehicle Location

```json
{
  "route_number": "182",
  "vehicle_type": "bus",
  "vehicles_count": 5,
  "locations": [
    {
      "type": "bus",
      "line": "182",
      "lat": 52.2297,
      "lon": 21.0122,
      "time": "2025-11-20 14:30:00",
      "brigade": "1",
      "vehicle_number": "1234"
    }
  ]
}
```

### Next Arrivals

```json
{
  "current_time": "14:25:30",
  "stop_id": "7009",
  "stop_name": "Centrum",
  "bus_stop_nr": "01",
  "next_arrivals": [
    {
      "line": "182",
      "direction": "Piaseczno",
      "scheduled_time": "14:27:00",
      "minutes_until": 2,
      "urgency": "urgent",
      "brigade": "4"
    }
  ],
  "total_arrivals": 15
}
```

## 🛠️ Development

### Install Development Dependencies

```bash
pip install warsaw-public-transport[dev]
```

### Run Tests

```bash
pytest
```

### Code Formatting

```bash
black warsaw_public_transport/
isort warsaw_public_transport/
```

## 📋 Requirements

- Python 3.8+
- FastAPI
- Uvicorn
- Pydantic v2
- Requests
- Warsaw Open Data API key

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- [Warsaw Open Data API](https://api.um.warszawa.pl/)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [GitHub Repository](https://github.com/yourusername/warsaw-public-transport)

## 📞 Support

For bug reports and feature requests, please open an issue on GitHub.

---

**Made with ❤️ for Warsaw** 🇵🇱