| Name | ptv-timetable JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | API wrappers for interacting with real-time public transport data in Victoria, Australia |
| upload_time | 2025-01-14 11:39:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | # Copyright and licensing ### Source code licence The source code in this project is licensed under the Apache Licence, version 2.0, which allows anyone to use, copy, modify and distribute the source code in this project, provided that the licence and any copyright notices, and, where you or someone else has modified one or more files before distribution, a notice stating that that person has changed those files, are distributed with the source code. For convenience, a copy of the licence is provided below these notices. For the purposes of clause 4(a) of the licence for this project, the contributors deem it sufficient for a URL or hyperlink to this licence page or the main licence page at https://www.apache.org/licenses/LICENSE-2.0 to be provided in lieu of the full text of the licence. **Note that the Apache Licence only applies to the source code and not the data obtained from the APIs.** ### Data licences Data from the PTV Timetable API is open government data that is separately licensed under the Creative Commons Attribution 4.0 International licence (CC BY 4.0) by the Department of Transport and Planning of Victoria, Australia, which can be found at https://creativecommons.org/licenses/by/4.0/legalcode.en. Data from the Yarra Trams TramTracker service is proprietary data by Yarra Journey Makers Pty Ltd and their terms of use can be found at https://yarratrams.com.au/terms-conditions. Data from the V/Line website is proprietary data by V/Line Corporation, a statutory authority of the state government of Victoria and their terms of use can be found at https://www.vline.com.au/Terms-of-use. **If you need to avoid using data that is not freely licensed, do *not* use the `tramtracker` and `vline` modules.** --- ## Apache Licence Version 2.0, January 2004<br /> http://www.apache.org/licenses/<br /> This copy of the licence has been edited for style; the original licence terms as linked above prevails in the event of any inconsistency. ### Terms and conditions for use, reproduction and distribution #### 1. Definitions In these terms: - ***licence*** shall mean the terms and conditions for use, reproduction, and distribution as defined by sections 1 through 9 of this document. - ***licensor*** shall mean the copyright owner or entity authorized by the copyright owner that is granting the licence. - ***legal entity*** shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means: - (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or - (ii) ownership of fifty percent (50%) or more of the outstanding shares, or - (iii) beneficial ownership of such entity. - ***you*** (or ***your***) shall mean an individual or legal entity exercising permissions granted by this licence. - ***source*** form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. - ***object*** form shall mean any form resulting from mechanical transformation or translation of a source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. - ***work*** shall mean the work of authorship, whether in source or object form, made available under the licence, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix at https://www.apache.org/licenses/LICENSE-2.0). - ***derivative works*** shall mean any work, whether in source or object form, that is based on (or derived from) the work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this licence, derivative works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the work and derivative works thereof. - ***contribution*** shall mean any work of authorship, including the original version of the work and any modifications or additions to that work or derivative works thereof, that is intentionally submitted to licensor for inclusion in the work by the copyright owner or by an individual or legal entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a contribution." - ***contributor*** shall mean licensor and any individual or legal entity on behalf of whom a contribution has been received by licensor and subsequently incorporated within the work. #### 2. Grant of copyright licence Subject to the terms and conditions of this licence, each contributor hereby grants to you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright licence to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the work and such derivative works in source or object form. #### 3. Grant of patent licence Subject to the terms and conditions of this licence, each contributor hereby grants to you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent licence to make, have made, use, offer to sell, sell, import, and otherwise transfer the work, where such licence applies only to those patent claims licensable by such contributor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the work to which such contribution(s) was submitted. If you institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the work or a contribution incorporated within the work constitutes direct or contributory patent infringement, then any patent licences granted to you under this licence for that work shall terminate as of the date such litigation is filed. #### 4. Redistribution You may reproduce and distribute copies of the work or derivative works thereof in any medium, with or without modifications, and in source or object form, provided that you meet the following conditions: - (a) You must give any other recipients of the work or derivative works a copy of this licence; and - (b) You must cause any modified files to carry prominent notices stating that you changed the files; and - (c) You must retain, in the source form of any derivative works that you distribute, all copyright, patent, trademark, and attribution notices from the source form of the work, excluding those notices that do not pertain to any part of the derivative works; and - (d) If the work includes a "NOTICE" text file as part of its distribution, then any derivative works that you distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the derivative works, in at least one of the following places: within a NOTICE text file distributed as part of the derivative works; within the source form or documentation, if provided along with the derivative works; or, within a display generated by the derivative works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the licence. You may add your own attribution notices within derivative works that you distribute, alongside or as an addendum to the NOTICE text from the work, provided that such additional attribution notices cannot be construed as modifying the licence. You may add your own copyright statement to your modifications and may provide additional or different licence terms and conditions for use, reproduction, or distribution of your modifications, or for any such derivative works as a whole, provided your use, reproduction, and distribution of the work otherwise complies with the conditions stated in this licence. #### 5. Submission of contributions Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you to the licensor shall be under the terms and conditions of this licence, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate licence agreement you may have executed with licensor regarding such contributions. #### 6. Trademarks This licence does not grant permission to use the trade names, trademarks, service marks, or product names of the licensor, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. #### 7. Disclaimer of warranty Unless required by applicable law or agreed to in writing, the licensor provides the work (and each contributor provides its contributions) on an **"as is" basis, without warranties or conditions of any kind**, either express or implied, including, without limitation, any warranties or conditions of **title, non-infringement, merchantability, or fitness for a particular purpose**. You are solely responsible for determining the appropriateness of using or redistributing the work and assume any risks associated with your exercise of permissions under this licence. #### 8. Limitation of liability In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any contributor be liable to you for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this licence or out of the use or inability to use the work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such contributor has been advised of the possibility of such damages. #### 9. Accepting warranty or additional liability While redistributing the work or derivative works thereof, you may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this licence. However, in accepting such obligations, you may act only on your own behalf and on your sole responsibility, not on behalf of any other contributor, and only if You agree to indemnify, defend, and hold each contributor harmless for any liability incurred by, or claims asserted against, such contributor by reason of your accepting any such warranty or additional liability. |
| keywords |
public transport
transportation
melbourne
victoria
australia
ptv
public transport victoria
yarra trams
library
api wrapper
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Victorian public transport information API wrappers for Python (pre-release)
Python 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).
Package version: 0.3.1<br />
Last updated: 14 January 2025<br />
Tested on Python version: ≥ 3.12
---
## Overview
This 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.
The package implements interfaces for three data sources:
- 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;
- 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
- [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.
The package minimises the use of third-party modules to improve portability, especially on systems with restrictions.
### What's different from accessing the Timetable API directly?
- **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.
- **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).
- **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.
- **Other quality of life modifications**: such as consistent attribute names, fixing typos and removing trailing whitespaces.
## Pre-release package
This package is in pre-release. Breaking changes may be made without notice during development.
## Direct dependencies
| Package name | Tested on version | Notes |
|--------------------------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------|
| [ratelimit](https://pypi.org/project/ratelimit/) | ≥ 2.2.1 | |
| [requests](https://pypi.org/project/requests/) | ≥ 2.32.3 | |
| [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. |
## Usage
The recommended method to install this package is via the [Python Package Index](https://pypi.org/project/ptv-timetable/):
```bash
python -m pip install ptv-timetable
```
You can also install from the [GitLab Package Registry](https://gitlab.com/pizza1016/ptv-timetable/-/packages/) (authentication not required):
```bash
python -m pip install --index-url https://gitlab.com/api/v4/projects/54559866/packages/pypi/simple ptv-timetable
```
These commands will also install any required dependencies.
This package adds three modules into the root namespace of your interpreter (so they can be directly imported into your code with `import <module_name>`):
- `ptv_timetable` for interacting with the PTV Timetable API;
- `ptv_timetable.types` defines dataclasses used to represent returned API objects;
- `tramtracker` for interacting with the TramTracker data service; and
- `vline` for retrieving V/Line Southern Cross departure and arrival information.
Each 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.
To use the Timetable API service, you will first need to obtain credentials from PTV:
- 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`.
- 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!<br />
(Details: http://ptv.vic.gov.au/ptv-timetable-api/)
- Specify the credentials when instantiating the `ptv_timetable.TimetableAPI` class: `TimetableAPI(dev_id, key)`
Credentials are not required for the `tramtracker` and `vline` modules.
### Logging
Some 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.
## Issues and error reporting
To report problems with the package or otherwise give feedback, [go to the Issues tab of the repository](https://gitlab.com/pizza1016/ptv-timetable/-/issues).
## Contributing
All constructive contributions are welcome! By contributing, you agree to license your contributions under the Apache Licence 2.0.
## Copyright and licensing
This 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.
## Summary of module contents
### ptv_timetable/\_\_init__.py
| Constant/function/method | Description |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **METROPOLITAN_TRAIN<br/>METRO_TRAIN<br/>MET_TRAIN<br/>METRO** | Use in `route_type` parameters to specify the metropolitan train network. |
| **TRAM** | Use in `route_type` parameters to specify the metropolitan tram network. |
| **BUS** | Use in `route_type` parameters to specify the metropolitan or regional bus network. |
| **REGIONAL_TRAIN<br/>REG_TRAIN<br/>COACH<br/>VLINE** | Use in `route_type` parameters to specify the regional train or coach network. |
| **EXPAND_**<_property_> | Use in `expand` parameters to tell the API to return the specified properties in full. |
| _class_ **TimetableAPI(**_dev_id, key, *, calls=1, period=10, ratelimit_handler=ratelimit.decorators.sleep_and_retry_**)** | Constructs a new instance of the `TimetableAPI` class with the supplied credentials.<br/><br/>To obtain your own set of credentials, follow the instructions on [this page](http://ptv.vic.gov.au/ptv-timetable-api/). |
| TimetableAPI.**list_route_directions(**_route_id_**)** | List directions for a specified route.<br/><br/>API operation: `/v3/directions/route/{route_id}` |
| TimetableAPI.**get_direction(**_direction_id, route_type=None_**)** | List directions with a specified identifier.<br/><br/>API operation: `/v3/directions/{direction_id}/route_type/{route_type}` |
| 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.<br/><br/>API operation: `/v3/pattern/run/{run_ref}/route_type/{route_type}` |
| TimetableAPI.**get_route(**_route_id, include_geopath=None, geopath_date=None_**)** | Return the route with the specified identifier.<br/><br/>API operation: `/v3/routes/{route_id}` |
| TimetableAPI.**list_routes(**_route_types=None, route_name=None_**)** | List all routes.<br/><br/>API operation: `/v3/routes/` |
| TimetableAPI.**list_route_types()** | List all route types (modes of travel) and their identifiers.<br/><br/>API operation: `/v3/route_types/` |
| TimetableAPI.**get_run(**_run_ref, route_type=None, expand=None, date=None, include_geopath=None_**)** | Return the run with the specified identifier.<br/><br/>API operation: `/v3/runs/{run_ref}/route_type/{route_type}` |
| TimetableAPI.**list_runs(**_route_id, route_type=None, expand=None, date=None_**)** | List runs for a specified route.<br/><br/>API operation: `/v3/runs/route/{route_id}/route_type/{route_type}` |
| 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.<br/><br/>API operation: `/v3/stops/{stop_id}/route_type/{route_type}` |
| TimetableAPI.**list_stops(**_route_id, route_type, direction_id=None, stop_disruptions=None_**)** | List all stops on a specified route.<br/><br/>API operation: `/v3/stops/route/{route_id}/route_type/{route_type}` |
| 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.<br/><br/>API operation: `/v3/stops/location/{latitude},{longitude}` |
| 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.<br/><br/>API operation: `/v3/departures/route_type/{route_type}/stop/{stop_id}/route/{route_id}` |
| TimetableAPI.**list_disruptions(**_route_id=None, stop_id=None, route_types=None, disruption_modes=None, disruption_status=None_**)** | List disruptions on the network.<br/><br/>API operation: `/v3/disruptions/route/{route_id}/stop/{stop_id}` |
| TimetableAPI.**list_disruption_modes()** | List all disruption modes.<br/><br/>API operation: `/v3/disruptions/modes` |
| 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.<br/><br/>API operation: `/v3/fare_estimate/min_zone/{minZone}/max_zone/{maxZone}` |
| TimetableAPI.**list_outlets(**_latitude=None, longitude=None, max_distance=None, max_results=None_**)** | List ticket outlets near a specified location.<br/><br/>API operation: `/v3/outlets/location/{latitude},{longitude}` |
| 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.<br/><br/>API operation: `/v3/search/{search_term}` |
### tramtracker/\_\_init__.py
| Constant/function/method | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| _class_ **TramTrackerService(**_*, calls=1, period=10, ratelimit_handler=ratelimit.decorators.sleep_and_retry_**)** | Constructs a new instance of the `TramTrackerService` class. |
| TramTrackerService.**list_destinations()** | List all destinations on the tram network. |
| TramTrackerService.**list_stops(**_route_id, up_direction_**)** | List stops for a specified route and direction of travel. |
| TramTrackerService.**get_stop(**_stop_id_**)** | Return details about a specified stop. |
| TramTrackerService.**list_routes_for_stop(**_stop_id_**)** | List the routes serving a specified stop. |
| TramTrackerService.**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. |
| TramTrackerService.**get_route_colour(**_route_id, as_of=datetime.now(tz=ZoneInfo("Australia/Melbourne"))_**)** | Return the route's colour on public information paraphernalia. |
| TramTrackerService.**get_route_text_colour(**_route_id, as_of=datetime.now(tz=ZoneInfo("Australia/Melbourne"))_**)** | Return the route's text colour on public information paraphernalia. |
### vline/\_\_init__.py
| Constant/function/method | Description |
|--------------------------|----------------------------------------------------------------------------------------------------|
| **next_services()** | Gets the details of the next 30 minutes of services departing and arriving Southern Cross station. |
Raw data
{
"_id": null,
"home_page": null,
"name": "ptv-timetable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "pizza1016 <10370007-pizza1016@users.noreply.gitlab.com>",
"keywords": "public transport, transportation, melbourne, victoria, australia, ptv, public transport victoria, yarra trams, library, api wrapper",
"author": null,
"author_email": "pizza1016 <10370007-pizza1016@users.noreply.gitlab.com>",
"download_url": "https://files.pythonhosted.org/packages/a6/52/f8df09505cace99e09bbf1ef97d67804802d1c75f8aa6494d5c4bdf6efc5/ptv_timetable-0.3.1.tar.gz",
"platform": null,
"description": "# 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.3.1<br />\nLast updated: 14 January 2025<br />\nTested on Python version: \u2265 3.12\n\n---\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\n\n| Package name | Tested on version | Notes |\n|--------------------------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------|\n| [ratelimit](https://pypi.org/project/ratelimit/) | \u2265 2.2.1 | |\n| [requests](https://pypi.org/project/requests/) | \u2265 2.32.3 | |\n| [tzdata](https://pypi.org/project/tzdata/) | \u2265 2024.1 | Only required on OSes without a native [tz database](https://en.wikipedia.org/wiki/tz_database), including Windows. |\n\n## Usage\n\nThe recommended method to install this package is via the [Python Package Index](https://pypi.org/project/ptv-timetable/):\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.\n\nThis package adds three modules into the root namespace of your interpreter (so they can be directly imported into your code with `import <module_name>`):\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\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!<br />\n (Details: http://ptv.vic.gov.au/ptv-timetable-api/)\n- Specify the credentials when instantiating the `ptv_timetable.TimetableAPI` class: `TimetableAPI(dev_id, key)`\n\nCredentials are not required for the `tramtracker` and `vline` modules.\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## Contributing\n\nAll 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<br/>METRO_TRAIN<br/>MET_TRAIN<br/>METRO** | 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<br/>REG_TRAIN<br/>COACH<br/>VLINE** | Use in `route_type` parameters to specify the regional train or coach network. |\n| **EXPAND_**<_property_> | 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_**)** | Constructs a new instance of the `TimetableAPI` class with the supplied credentials.<br/><br/>To 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.<br/><br/>API operation: `/v3/directions/route/{route_id}` |\n| TimetableAPI.**get_direction(**_direction_id, route_type=None_**)** | List directions with a specified identifier.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API operation: `/v3/routes/{route_id}` |\n| TimetableAPI.**list_routes(**_route_types=None, route_name=None_**)** | List all routes.<br/><br/>API operation: `/v3/routes/` |\n| TimetableAPI.**list_route_types()** | List all route types (modes of travel) and their identifiers.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API operation: `/v3/disruptions/route/{route_id}/stop/{stop_id}` |\n| TimetableAPI.**list_disruption_modes()** | List all disruption modes.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API 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.<br/><br/>API operation: `/v3/search/{search_term}` |\n\n### tramtracker/\\_\\_init__.py\n\n| Constant/function/method | Description |\n|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|\n| _class_ **TramTrackerService(**_*, calls=1, period=10, ratelimit_handler=ratelimit.decorators.sleep_and_retry_**)** | Constructs a new instance of the `TramTrackerService` class. |\n| TramTrackerService.**list_destinations()** | List all destinations on the tram network. |\n| TramTrackerService.**list_stops(**_route_id, up_direction_**)** | List stops for a specified route and direction of travel. |\n| TramTrackerService.**get_stop(**_stop_id_**)** | Return details about a specified stop. |\n| TramTrackerService.**list_routes_for_stop(**_stop_id_**)** | List the routes serving a specified stop. |\n| TramTrackerService.**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| TramTrackerService.**get_route_colour(**_route_id, as_of=datetime.now(tz=ZoneInfo(\"Australia/Melbourne\"))_**)** | Return the route's colour on public information paraphernalia. |\n| TramTrackerService.**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### 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",
"bugtrack_url": null,
"license": "# Copyright and licensing ### Source code licence The source code in this project is licensed under the Apache Licence, version 2.0, which allows anyone to use, copy, modify and distribute the source code in this project, provided that the licence and any copyright notices, and, where you or someone else has modified one or more files before distribution, a notice stating that that person has changed those files, are distributed with the source code. For convenience, a copy of the licence is provided below these notices. For the purposes of clause 4(a) of the licence for this project, the contributors deem it sufficient for a URL or hyperlink to this licence page or the main licence page at https://www.apache.org/licenses/LICENSE-2.0 to be provided in lieu of the full text of the licence. **Note that the Apache Licence only applies to the source code and not the data obtained from the APIs.** ### Data licences Data from the PTV Timetable API is open government data that is separately licensed under the Creative Commons Attribution 4.0 International licence (CC BY 4.0) by the Department of Transport and Planning of Victoria, Australia, which can be found at https://creativecommons.org/licenses/by/4.0/legalcode.en. Data from the Yarra Trams TramTracker service is proprietary data by Yarra Journey Makers Pty Ltd and their terms of use can be found at https://yarratrams.com.au/terms-conditions. Data from the V/Line website is proprietary data by V/Line Corporation, a statutory authority of the state government of Victoria and their terms of use can be found at https://www.vline.com.au/Terms-of-use. **If you need to avoid using data that is not freely licensed, do *not* use the `tramtracker` and `vline` modules.** --- ## Apache Licence Version 2.0, January 2004<br /> http://www.apache.org/licenses/<br /> This copy of the licence has been edited for style; the original licence terms as linked above prevails in the event of any inconsistency. ### Terms and conditions for use, reproduction and distribution #### 1. Definitions In these terms: - ***licence*** shall mean the terms and conditions for use, reproduction, and distribution as defined by sections 1 through 9 of this document. - ***licensor*** shall mean the copyright owner or entity authorized by the copyright owner that is granting the licence. - ***legal entity*** shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, \"control\" means: - (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or - (ii) ownership of fifty percent (50%) or more of the outstanding shares, or - (iii) beneficial ownership of such entity. - ***you*** (or ***your***) shall mean an individual or legal entity exercising permissions granted by this licence. - ***source*** form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. - ***object*** form shall mean any form resulting from mechanical transformation or translation of a source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. - ***work*** shall mean the work of authorship, whether in source or object form, made available under the licence, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix at https://www.apache.org/licenses/LICENSE-2.0). - ***derivative works*** shall mean any work, whether in source or object form, that is based on (or derived from) the work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this licence, derivative works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the work and derivative works thereof. - ***contribution*** shall mean any work of authorship, including the original version of the work and any modifications or additions to that work or derivative works thereof, that is intentionally submitted to licensor for inclusion in the work by the copyright owner or by an individual or legal entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, \"submitted\" means any form of electronic, verbal, or written communication sent to the licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as \"Not a contribution.\" - ***contributor*** shall mean licensor and any individual or legal entity on behalf of whom a contribution has been received by licensor and subsequently incorporated within the work. #### 2. Grant of copyright licence Subject to the terms and conditions of this licence, each contributor hereby grants to you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright licence to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the work and such derivative works in source or object form. #### 3. Grant of patent licence Subject to the terms and conditions of this licence, each contributor hereby grants to you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent licence to make, have made, use, offer to sell, sell, import, and otherwise transfer the work, where such licence applies only to those patent claims licensable by such contributor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the work to which such contribution(s) was submitted. If you institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the work or a contribution incorporated within the work constitutes direct or contributory patent infringement, then any patent licences granted to you under this licence for that work shall terminate as of the date such litigation is filed. #### 4. Redistribution You may reproduce and distribute copies of the work or derivative works thereof in any medium, with or without modifications, and in source or object form, provided that you meet the following conditions: - (a) You must give any other recipients of the work or derivative works a copy of this licence; and - (b) You must cause any modified files to carry prominent notices stating that you changed the files; and - (c) You must retain, in the source form of any derivative works that you distribute, all copyright, patent, trademark, and attribution notices from the source form of the work, excluding those notices that do not pertain to any part of the derivative works; and - (d) If the work includes a \"NOTICE\" text file as part of its distribution, then any derivative works that you distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the derivative works, in at least one of the following places: within a NOTICE text file distributed as part of the derivative works; within the source form or documentation, if provided along with the derivative works; or, within a display generated by the derivative works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the licence. You may add your own attribution notices within derivative works that you distribute, alongside or as an addendum to the NOTICE text from the work, provided that such additional attribution notices cannot be construed as modifying the licence. You may add your own copyright statement to your modifications and may provide additional or different licence terms and conditions for use, reproduction, or distribution of your modifications, or for any such derivative works as a whole, provided your use, reproduction, and distribution of the work otherwise complies with the conditions stated in this licence. #### 5. Submission of contributions Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you to the licensor shall be under the terms and conditions of this licence, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate licence agreement you may have executed with licensor regarding such contributions. #### 6. Trademarks This licence does not grant permission to use the trade names, trademarks, service marks, or product names of the licensor, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. #### 7. Disclaimer of warranty Unless required by applicable law or agreed to in writing, the licensor provides the work (and each contributor provides its contributions) on an **\"as is\" basis, without warranties or conditions of any kind**, either express or implied, including, without limitation, any warranties or conditions of **title, non-infringement, merchantability, or fitness for a particular purpose**. You are solely responsible for determining the appropriateness of using or redistributing the work and assume any risks associated with your exercise of permissions under this licence. #### 8. Limitation of liability In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any contributor be liable to you for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this licence or out of the use or inability to use the work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such contributor has been advised of the possibility of such damages. #### 9. Accepting warranty or additional liability While redistributing the work or derivative works thereof, you may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this licence. However, in accepting such obligations, you may act only on your own behalf and on your sole responsibility, not on behalf of any other contributor, and only if You agree to indemnify, defend, and hold each contributor harmless for any liability incurred by, or claims asserted against, such contributor by reason of your accepting any such warranty or additional liability. ",
"summary": "API wrappers for interacting with real-time public transport data in Victoria, Australia",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://gitlab.com/pizza1016/ptv-timetable/-/blob/trunk/README.md",
"Issues": "https://gitlab.com/pizza1016/ptv-timetable/-/issues",
"Repository": "https://gitlab.com/pizza1016/ptv-timetable"
},
"split_keywords": [
"public transport",
" transportation",
" melbourne",
" victoria",
" australia",
" ptv",
" public transport victoria",
" yarra trams",
" library",
" api wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a53a58f52e59473b4b05c81e2c2fa95e19139a4fb03fa541c659e8cbf010b770",
"md5": "5fa11624847afafed196b95851e56a40",
"sha256": "ab0782bd91c26d6a60c0384407cb9fd55ff8c81720cec136a7ed6c5af40a62e6"
},
"downloads": -1,
"filename": "ptv_timetable-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fa11624847afafed196b95851e56a40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 37417,
"upload_time": "2025-01-14T11:39:51",
"upload_time_iso_8601": "2025-01-14T11:39:51.913608Z",
"url": "https://files.pythonhosted.org/packages/a5/3a/58f52e59473b4b05c81e2c2fa95e19139a4fb03fa541c659e8cbf010b770/ptv_timetable-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a652f8df09505cace99e09bbf1ef97d67804802d1c75f8aa6494d5c4bdf6efc5",
"md5": "72e1cf55410c6d85b39b6c71b7f00016",
"sha256": "12eb5cef11723a1d8261bbda8dd6bba095b4791e6f929caba18ee5606bc2a36d"
},
"downloads": -1,
"filename": "ptv_timetable-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "72e1cf55410c6d85b39b6c71b7f00016",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 41598,
"upload_time": "2025-01-14T11:39:54",
"upload_time_iso_8601": "2025-01-14T11:39:54.065418Z",
"url": "https://files.pythonhosted.org/packages/a6/52/f8df09505cace99e09bbf1ef97d67804802d1c75f8aa6494d5c4bdf6efc5/ptv_timetable-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-14 11:39:54",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "pizza1016",
"gitlab_project": "ptv-timetable",
"lcname": "ptv-timetable"
}
