warsaw-public-transport 1.0.0

FastAPI-based API for Warsaw public transport real-time data

🚌 Warsaw Public Transport API

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

pip install warsaw-public-transport

Get API Key

1. Register at Warsaw Open Data Portal
2. Get your free API key

Run the Server

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

# Run the server
warsaw-transport

Or using Python module:

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

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

# 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

// 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

# 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:

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

🐍 Programmatic Usage

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

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

{
  "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

{
  "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

pip install warsaw-public-transport[dev]

Run Tests

pytest

Code Formatting

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 file for details.

🔗 Links

• Warsaw Open Data API
• FastAPI Documentation
• GitHub Repository

📞 Support

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

---

Made with ❤️ for Warsaw 🇵🇱