ztm-buses 0.0.1

Warsaw ZTM API Fetcher and Data Analyzer

ZTM Buses Package

Current Features

The package consists of three main functionalities:

1. ZTMFetcher
2. BusStatistician
3. Visualizer

ZTMFetcher

The ZTMFetcher module allows acquiring information from the Warsaw API.

• Import the module:

  from ztm_buses import ZTMFetcher
  

• Initialize with multiple API keys (may be beneficial when handling a substantial number of requests.):

  fetcher = ZTMFetcher(['your_apikey1', 'your_apikey2'])
  

  API keys can be obtained on https://api.um.warszawa.pl/.

• Fetch Bus Location:

  location = fetcher.fetch_bus_location()
  

• Fetch Bus Location Period:

  hour_location = fetcher.fetch_bus_location_period(period, "filename_to_save_json.json")
  

• Fetch Bus Stop Coordinates and Routes:

  fetcher.fetch_busstop_coordinates("filename_to_save_json.json")
  fetcher.fetch_routes("filename_to_save_json.json")
  

  For all methods, if a filename was not given, the data will be automatically saved with the date to avoid overwriting issues.

• Fetch Lines for Bus Stop:

  list_of_lines = fetcher.fetch_lines_for_busstop(bus_stop_complex_id, bus_stop_id)
  

• Fetch Whole Timetable:

  fetcher.read_the_whole_schedule("filename_to_save_json.json")
  

  Beware that fetching the whole timetable requires sending about 28,000 requests and may take from 20 to 50 minutes depending on the server load.

BusStatistician

The BusStatistician module allows obtaining information about the speed and punctuality of buses.

• Import the module:

  from ztm_buses import BusStatistician
  

• Initialize:

  statistician = BusStatistician(bus_coordinates_file, timetable_file, routes_file, bus_stops_file)
  

• Get Speed Statistics:

  speed_data_frame = statistician.get_speed_statistics()
  

• Get Punctuality Statistics:

  punctuality_data_frame = statistician.get_punctuality_statistics()
  

  The speed_data_frame contains the columns: 'speed', 'lon', 'lat', 'vehicle_number', 'line_number'. The punctuality_data_frame contains 'Bus_num', 'Line', 'Busstop_id', 'Busstop_name', 'Lon', 'Lat', 'Arrived', 'Expected', 'Delay [min]'.

Due to the complicated structure of bus routes and imperfections of the data, the punctuality data is prone to some larger errors.

Visualizer

The Visualizer module takes the dataframes from the BusStatistician and plots them on the Warsaw map.

• Import the module:

  from ztm_buses import Visualizer
  

• Initialize:

  vis = Visualizer()
  

• Heat Map of Speeds:

  vis.heat_map_speeds(speed_data_frame, html_file_to_save)
  

• Scatter Map of Speeds:

  vis.scatter_map_speeds(speed_data_frame, html_file_to_save)
  

  For speed maps output html file is optional and if not given the result will not be saved

• Map of Punctuality:

  vis.map_punctuality(punctuality_data_frame, html_file_to_save)
  

  For punctuality map the html file is required parameter

It is worth noting that before visualizing the data, it has to be cleaned up as the API sometimes responds with nonrealistic data (time traveling, hypersonic buses).

Installation

pip install ztm_buses