{"id":26418614,"url":"https://github.com/pizza1016/ptv-timetable","last_synced_at":"2025-10-09T02:23:32.007Z","repository":{"id":282530351,"uuid":"948869582","full_name":"pizza1016/ptv-timetable","owner":"pizza1016","description":"Python API wrappers for interacting with public transport information in Victoria, Australia","archived":false,"fork":false,"pushed_at":"2025-03-16T20:06:15.000Z","size":205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-08-09T22:22:48.429Z","etag":null,"topics":["api-wrapper","library","melbourne","public-transport","public-transport-victoria","python","python-library","python3","tramtracker","transportation","vline","yarra-trams"],"latest_commit_sha":null,"homepage":"https://gitlab.com/pizza1016/ptv-timetable","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pizza1016.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-15T06:17:03.000Z","updated_at":"2025-03-16T20:06:18.000Z","dependencies_parsed_at":"2025-03-15T08:25:13.765Z","dependency_job_id":"516bed3d-c8e1-4b9a-822f-ec0b2026f79e","html_url":"https://github.com/pizza1016/ptv-timetable","commit_stats":null,"previous_names":["pizza1016/ptv-timetable"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/pizza1016/ptv-timetable","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pizza1016%2Fptv-timetable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pizza1016%2Fptv-timetable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pizza1016%2Fptv-timetable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pizza1016%2Fptv-timetable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pizza1016","download_url":"https://codeload.github.com/pizza1016/ptv-timetable/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pizza1016%2Fptv-timetable/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000781,"owners_count":26082906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","library","melbourne","public-transport","public-transport-victoria","python","python-library","python3","tramtracker","transportation","vline","yarra-trams"],"created_at":"2025-03-18T01:48:48.866Z","updated_at":"2025-10-09T02:23:31.970Z","avatar_url":"https://github.com/pizza1016.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Victorian public transport information API wrappers for Python (pre-release)\n\nPython utilities for interacting with real-time information for public transport in Victoria, Australia, via the [Public Transport Victoria](https://ptv.vic.gov.au) (PTV) [Timetable API](https://timetableapi.ptv.vic.gov.au/swagger/ui/index), [Yarra Trams](https://yarratrams.com.au/)' [TramTracker data service](https://tramtracker.com.au/pid.html) and the [V/Line website](https://www.vline.com.au).\n\nPackage version: 0.4.1\u003cbr /\u003e\nLast updated: 17 March 2025\u003cbr /\u003e\nTested on Python version: ≥ 3.12\n\nThis repository is hosted on GitLab and mirrored on GitHub. **If you are viewing on GitHub, please send any issues, comments and feedback [there](https://gitlab.com/pizza1016/ptv-timetable).**\n\n---\n\n## Documentation\n\nThe full public API documentation can be found at: https://pizza1016.gitlab.io/ptv-timetable \n\n## Overview\n\nThis package of modules aims to simplify the process of retrieving and manipulating real-time data for public transport in Victoria, Australia and document each operation and response supported by the APIs.\n\nThe package implements interfaces for three data sources:\n- PTV [Timetable API](https://timetableapi.ptv.vic.gov.au/swagger/ui/index) - the main service for real-time and scheduled public transport information across Victoria;\n- Yarra Trams [TramTracker](https://tramtracker.com.au/pid.html) - live passenger information for the Melbourne tram network, including planned diversions which the Timetable API lacks; and\n- [V/Line website](https://www.vline.com.au) - since November 2024, real-time V/Line departures and arrivals information at Southern Cross station for the next 30 minutes, including platform information and estimated time of departure/arrival.\n\nThe package minimises the use of third-party modules to improve portability, especially on systems with restrictions.\n\n### What's different from accessing the Timetable API directly?\n\n- **Simplifying output \"types\"**: instead of having a different response schema for each API operation, any object that represents the same concept are consolidated into the same response type (e.g. all responses that represent a public transport stop are instances of the same class: `Stop`, instead of the ten or so different representations in the API). Any attribute/field for which the API does not provide a response for will have a sentinel value.\n- **Best-effort documentation**: all operations and fields have, as far as practicable, been documented in type hints and docstrings (although some of these are guesses).\n- **Date and time representation**: date inputs and outputs are converted from and to `datetime` objects with the local time zone of Victoria, so that you do not have to deal with the different string representations of dates and speaking to the API in the UTC time zone as implemented by the Timetable API.\n- **Other quality of life modifications**: such as consistent attribute names, fixing typos and removing trailing whitespaces.\n\n## Pre-release package\n\nThis package is in pre-release. Breaking changes may be made without notice during development.\n\n## Direct dependencies\nNote that these dependencies may have their own dependencies.\n\n| Package name | Tested on version | Notes |\n|---------------------------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------|\n| [aiohttp](https://pypi.org/project/aiohttp) | ≥ 3.11.11 |\n| [aiolimiter](https://pypi.org/project/aiolimiter) | ≥ 1.2.1 |\n| [ratelimit](https://pypi.org/project/ratelimit/) | ≥ 2.2.1 | |\n| [requests](https://pypi.org/project/requests/) | ≥ 2.32.3 | |\n| [tzdata](https://pypi.org/project/tzdata/) | ≥ 2024.1 | Only required on OSes without a native [tz database](https://en.wikipedia.org/wiki/tz_database), including Windows. |\n\n## Installation\n\nThe recommended method to install this package is via the [Python Package Index](https://pypi.org/project/ptv-timetable/) (PyPI):\n```bash\npython -m pip install ptv-timetable\n```\nYou can also install from the [GitLab Package Registry](https://gitlab.com/pizza1016/ptv-timetable/-/packages/) (authentication not required):\n```bash\npython -m pip install --index-url https://gitlab.com/api/v4/projects/54559866/packages/pypi/simple ptv-timetable\n```\nThese commands will also install any required dependencies from PyPI.\n\n## Usage\n\nThis package adds three modules into the root namespace of your interpreter (so they can be directly imported into your code with `import \u003cmodule_name\u003e`):\n- `ptv_timetable` for interacting with the PTV Timetable API;\n - `ptv_timetable.types` defines dataclasses used to represent returned API objects;\n- `tramtracker` for interacting with the TramTracker data service; and\n- `vline` for retrieving V/Line Southern Cross departure and arrival information.\n\nEach module defines data types that encapsulate the responses from the APIs to allow access by attribute reference (`.`) to take advantage of autocompletion systems in IDEs where available. This format also allows each field to be documented, which is not a feature that is available in the raw `dict`s returned by the APIs.\n\n### PTV Timetable API\n\nTo use the Timetable API service, you will first need to obtain credentials from PTV:\n- Send an email to [APIKeyRequest@ptv.vic.gov.au](mailto:APIKeyRequest@ptv.vic.gov.au) with the subject line `PTV Timetable API - request for key`.\n- You will receive a user ID and a UUID-format signing key in response. This may take several days depending on volume of requests; you will *not* receive confirmation that your request was received, so hang tight!\u003cbr /\u003e\n (Details: http://ptv.vic.gov.au/ptv-timetable-api/)\n\nImport the `ptv_timetable` module:\n```python\nfrom ptv_timetable import *\n```\n\nThis adds the `TimetableAPI` class and a number of constants for use in method arguments.\n\nCreate a new instance of `TimetableAPI` and provide your user ID and signing key:\n```python\ntimetable = TimetableAPI(dev_id, key)\n```\n\nYou can now communicate with the API using the instance methods.\n\nThere is also an `asyncio` version, which you can set up as follows:\n```python\nimport asyncio\n\nfrom aiohttp.client import ClientSession\nfrom ptv_timetable.asyncapi import *\n\nasync def main() -\u003e None:\n async with ClientSession() as session:\n timetable = AsyncTimetableAPI(dev_id, key, session)\n # Your code here\n # e.g. routes = await timetable.list_routes(METROPOLITAN_TRAIN)\n return\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### TramTracker data service\nImport the `tramtracker` module and instantiate `TramTrackerAPI`:\n```python\nfrom tramtracker import *\n\ntracker = TramTrackerAPI()\n\n# Your code here\n```\n\nOr, for asynchronous use:\n```python\nimport asyncio\n\nfrom aiohttp.client import ClientSession\nfrom tramtracker.asyncapi import *\n\nasync def main() -\u003e None:\n async with ClientSession() as session:\n tracker = AsyncTramTrackerAPI(session)\n # Your code here\n return\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Southern Cross station V/Line departures and arrivals\nImport the `vline` module and call `next_services()`:\n```python\nimport vline\n\ndepartures, arrivals, as_at = vline.next_services()\n```\n\n### Logging\n\nSome actions are logged under the logger names `ptv-timetable.ptv_timetable`, `ptv-timetable.tramtracker` and `ptv-timetable.vline`. Use `logging.getLogger()` to obtain the loggers and you can register your own handlers to retrieve their contents.\n\n## Issues and error reporting\n\nTo report problems with the package or otherwise give feedback, [go to the Issues tab of the repository](https://gitlab.com/pizza1016/ptv-timetable/-/issues).\n\n[//]: # ()\n[//]: # (## Contributing)\n\n[//]: # ()\n[//]: # (All constructive contributions are welcome! By contributing, you agree to license your contributions under the Apache Licence 2.0.)\n\n## Copyright and licensing\n\nThis project's source code is licensed under the Apache Licence 2.0; however, data obtained from the APIs themselves via these modules are licensed separately: PTV Timetable API data are under a Creative Commons Attribution 4.0 International licence and TramTracker data is proprietary. See [LICENCE.md](https://gitlab.com/pizza1016/ptv-timetable/-/blob/trunk/LICENCE.md) for further information.\n\n## Summary of module contents\n\n### ptv_timetable/\\_\\_init__.py\n\n| Constant/function/method | Description |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **METROPOLITAN_TRAIN\u003cbr/\u003eMETRO_TRAIN\u003cbr/\u003eMET_TRAIN\u003cbr/\u003eMETRO** | Use in `route_type` parameters to specify the metropolitan train network. |\n| **TRAM** | Use in `route_type` parameters to specify the metropolitan tram network. |\n| **BUS** | Use in `route_type` parameters to specify the metropolitan or regional bus network. |\n| **REGIONAL_TRAIN\u003cbr/\u003eREG_TRAIN\u003cbr/\u003eCOACH\u003cbr/\u003eVLINE** | Use in `route_type` parameters to specify the regional train or coach network. |\n| **EXPAND_**\u003c_property_\u003e | Use in `expand` parameters to tell the API to return the specified properties in full. |\n| _class_ **TimetableAPI(**_dev_id, key, *, calls=1, period=10, ratelimit_handler=ratelimit.decorators.sleep_and_retry, session=None_**)** | Constructs a new instance of the `TimetableAPI` class with the supplied credentials.\u003cbr/\u003e\u003cbr/\u003eTo obtain your own set of credentials, follow the instructions on [this page](http://ptv.vic.gov.au/ptv-timetable-api/). |\n| TimetableAPI.**list_route_directions(**_route_id_**)** | List directions for a specified route.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/directions/route/{route_id}` |\n| TimetableAPI.**get_direction(**_direction_id, route_type=None_**)** | List directions with a specified identifier.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/directions/{direction_id}/route_type/{route_type}` |\n| TimetableAPI.**get_pattern(**_run_ref, route_type, stop_id=None, date=None, include_skipped_stops=None, expand=None, include_geopath=None_**)** | Retrieve the stopping pattern and times of arrival at each stop for a particular run.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/pattern/run/{run_ref}/route_type/{route_type}` |\n| TimetableAPI.**get_route(**_route_id, include_geopath=None, geopath_date=None_**)** | Return the route with the specified identifier.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/routes/{route_id}` |\n| TimetableAPI.**list_routes(**_route_types=None, route_name=None_**)** | List all routes.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/routes/` |\n| TimetableAPI.**list_route_types()** | List all route types (modes of travel) and their identifiers.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/route_types/` |\n| TimetableAPI.**get_run(**_run_ref, route_type=None, expand=None, date=None, include_geopath=None_**)** | Return the run with the specified identifier.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/runs/{run_ref}/route_type/{route_type}` |\n| TimetableAPI.**list_runs(**_route_id, route_type=None, expand=None, date=None_**)** | List runs for a specified route.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/runs/route/{route_id}/route_type/{route_type}` |\n| TimetableAPI.**get_stop(**_stop_id, route_type, stop_location=None, stop_amenities=None, stop_accessibility=None, stop_contact=None, stop_ticket=None, gtfs=None, stop_staffing=None, stop_disruptions=None_**)** | Return the stop with the specified identifier and route type.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/stops/{stop_id}/route_type/{route_type}` |\n| TimetableAPI.**list_stops(**_route_id, route_type, direction_id=None, stop_disruptions=None_**)** | List all stops on a specified route.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/stops/route/{route_id}/route_type/{route_type}` |\n| TimetableAPI.**list_stops_near_location(**_latitude, longitude, route_types=None, max_results=None, max_distance=None, stop_distuptions=None_**)** | List all stops near a specified location.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/stops/location/{latitude},{longitude}` |\n| TimetableAPI.**list_departures(**_route_type, stop_id, route_id=None, platform_numbers=None, direction_id=None, gtfs=None, include_advertised_interchange=None, date=None, max_results=None, include_cancelled=None, expand=None, include_geopath=None_**)** | List the departures from a specified stop.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/departures/route_type/{route_type}/stop/{stop_id}/route/{route_id}` |\n| TimetableAPI.**list_disruptions(**_route_id=None, stop_id=None, route_types=None, disruption_modes=None, disruption_status=None_**)** | List disruptions on the network.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/disruptions/route/{route_id}/stop/{stop_id}` |\n| TimetableAPI.**list_disruption_modes()** | List all disruption modes.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/disruptions/modes` |\n| TimetableAPI.**fare_estimate(**_zone_a, zone_b, touch_on=None, touch_off=None, is_free_fare_zone=None, route_types=None_**)** | Return the fare for a specified journey.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/fare_estimate/min_zone/{minZone}/max_zone/{maxZone}` |\n| TimetableAPI.**list_outlets(**_latitude=None, longitude=None, max_distance=None, max_results=None_**)** | List ticket outlets near a specified location.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/outlets/location/{latitude},{longitude}` |\n| TimetableAPI.**search(**_search_term, route_types=None, latitude=None, longitude=None, max_distance=None, include_outlets=None, match_stop_by_locality=None, match_route_by_locality=None, match_stop_by_gtfs_stop_id=None_**)** | Search for a stop, route or ticket outlet by name.\u003cbr/\u003e\u003cbr/\u003eAPI operation: `/v3/search/{search_term}` |\n\n### ptv_timetable/asyncapi.py\n\n| Constant/function/method | Description |\n|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| \u003c_constant_\u003e | All constants in `ptv_timetable\\__init__.py` are also available here. |\n| _class_ **AsyncTimetableAPI(**_dev_id, key, session, *, calls=1, period=10_**)** | Constructs a new instance of the `AsyncTimetableAPI` class with the supplied credentials and `aiohttp.client.ClientSession` session. |\n| _classmethod_ AsyncTimetableAPI.**create(**_dev_id, key, session=None, *, calls=1, period=10_**)** | Constructs a new instance of the `AsyncTimetableAPI` class with the supplied credentials. This alternative constructor does not require a `ClientSession` to be provided, with the instance itself managing the opening and closing of the session. |\n| _async_ AsyncTimetableAPI.**_\\\u003cmethod\\\u003e_(**_\\\u003cargs\\\u003e_**)** | All methods described in `ptv_timetable.TimetableAPI` have the same functionality here but supports `asyncio`. |\n\n\n### tramtracker/\\_\\_init__.py\n\n| Constant/function/method | Description |\n|-------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|\n| _class_ **TramTrackerAPI(**_*, calls=1, period=10, ratelimit_handler=ratelimit.decorators.sleep_and_retry, session=None_**)** | Constructs a new instance of the `TramTrackerAPI` class. |\n| TramTrackerAPI.**list_destinations()** | List all destinations on the tram network. |\n| TramTrackerAPI.**list_stops(**_route_id, up_direction_**)** | List stops for a specified route and direction of travel. |\n| TramTrackerAPI.**get_stop(**_stop_id_**)** | Return details about a specified stop. |\n| TramTrackerAPI.**list_routes_for_stop(**_stop_id_**)** | List the routes serving a specified stop. |\n| TramTrackerAPI.**next_trams(**_stop_id, route_id=None, low_floor_tram=False, as_of=datetime.now(tz=ZoneInfo(\"Australia/Melbourne\"))_**)** | List the next tram departures from a specified stop. |\n| TramTrackerAPI.**get_route_colour(**_route_id, as_of=datetime.now(tz=ZoneInfo(\"Australia/Melbourne\"))_**)** | Return the route's colour on public information paraphernalia. |\n| TramTrackerAPI.**get_route_text_colour(**_route_id, as_of=datetime.now(tz=ZoneInfo(\"Australia/Melbourne\"))_**)** | Return the route's text colour on public information paraphernalia. |\n\n\n### tramtracker/asyncapi.py\n\n| Constant/function/method | Description |\n|-----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| _class_ **AsyncTramTrackerAPI(**_session, *, calls=1, period=10_**)** | Constructs a new instance of the `AsyncTramTrackerAPI` class with the supplied credentials and `aiohttp.client.ClientSession` session. |\n| _classmethod_ AsyncTramTrackerAPI.**create(**_session=None, *, calls=1, period=10_**)** | Constructs a new instance of the `AsyncTramTrackerAPI` class with the supplied credentials and `aiohttp.client.ClientSession` session. This alternative constructor does not require a `ClientSession` to be provided, with the instance itself managing the opening and closing of the session. |\n| _async_ AsyncTramTrackerAPI.**\\\u003c_method_\\\u003e(**_\\\u003cargs\\\u003e_**)** | All methods described in `tramtracker.TramTrackerAPI` have the same functionality here but supports `asyncio`. |\n\n### vline/\\_\\_init__.py\n\n| Constant/function/method | Description |\n|--------------------------|----------------------------------------------------------------------------------------------------|\n| **next_services()** | Gets the details of the next 30 minutes of services departing and arriving Southern Cross station. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpizza1016%2Fptv-timetable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpizza1016%2Fptv-timetable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpizza1016%2Fptv-timetable/lists"}