PyTransportNSWv2 1.0.3__tar.gz → 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- PyTransportNSWv2-2.0.0/PKG-INFO +308 -0
- PyTransportNSWv2-2.0.0/PyTransportNSWv2.egg-info/PKG-INFO +308 -0
- PyTransportNSWv2-2.0.0/README.md +292 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/TransportNSWv2/TransportNSWv2.py +22 -18
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/setup.py +1 -1
- PyTransportNSWv2-1.0.3/PKG-INFO +0 -221
- PyTransportNSWv2-1.0.3/PyTransportNSWv2.egg-info/PKG-INFO +0 -221
- PyTransportNSWv2-1.0.3/README.md +0 -205
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/LICENSE +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/PyTransportNSWv2.egg-info/SOURCES.txt +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/PyTransportNSWv2.egg-info/TransportNSWv2.py +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/PyTransportNSWv2.egg-info/dependency_links.txt +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/PyTransportNSWv2.egg-info/requires.txt +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/PyTransportNSWv2.egg-info/top_level.txt +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/TransportNSWv2/__init__.py +0 -0
- {PyTransportNSWv2-1.0.3 → PyTransportNSWv2-2.0.0}/setup.cfg +0 -0
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: PyTransportNSWv2
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Get detailed per-trip transport information from TransportNSW
|
|
5
|
+
Home-page: https://github.com/andystewart999/TransportNSW
|
|
6
|
+
Author: andystewart999
|
|
7
|
+
Author-email: andy.stewart@live.com
|
|
8
|
+
License: UNKNOWN
|
|
9
|
+
Description:
|
|
10
|
+
# TransportNSWv2
|
|
11
|
+
Python lib to access Transport NSW stop and journey information.
|
|
12
|
+
|
|
13
|
+
## How to Use
|
|
14
|
+
|
|
15
|
+
### Get an API Key
|
|
16
|
+
An OpenData account and API key is required to request the data. More information on how to create the free account can be found [here](https://opendata.transport.nsw.gov.au/user-guide). You need to register an application that needs both the Trip Planner and Realtime Vehicle Positions APIs.
|
|
17
|
+
|
|
18
|
+
### Get the stop IDs
|
|
19
|
+
The only mandatory parameters are the API key and the origin/destination stop IDs - the easiest way to get the stop ID is via https://transportnsw.info/stops#/ - that page provides the option to search for either a location or a specific platform, bus stop or ferry wharf. Regardless of if you specify a general location for the origin or destination, the return information shows the stop ID for the actual arrival and destination platform, bus stop or ferry wharf.
|
|
20
|
+
|
|
21
|
+
If it's available, the general occupancy level as wel as the latitude and longitude of the selected journey's vehicle(s) (train, bus, etc) will be returned, unless you specifically set `include_realtime_location` to `False`.
|
|
22
|
+
|
|
23
|
+
### API Documentation
|
|
24
|
+
The source Transport NSW API details can be found [here](https://opendata.transport.nsw.gov.au/sites/default/files/2023-08/Trip%20Planner%20API%20manual-opendataproduction%20v3.2.pdf).
|
|
25
|
+
|
|
26
|
+
### Exposed functions
|
|
27
|
+
Two functions are available:
|
|
28
|
+
`get_trip()` returns trip information between two stop IDs
|
|
29
|
+
`check_stops()` lets you confirm that the two stop IDs are valid, plus it returns all the stop ID metadata. Note that ```get_trip()``` calls this function internally (unless you tell it not to, see below) and fails with a `StopError` Exception if either of the stop IDs are invalid, so there's no specific need to call `check_stops()` unless you want the stop ID metadata, or know you'll be calling the same journey multiple times and want to reduce your daily API calls by pre-checking once.
|
|
30
|
+
|
|
31
|
+
### check_stops() parameters
|
|
32
|
+
All parameters are mandatory. Note that `stop_list` can be a single string or a list of strings:
|
|
33
|
+
```python
|
|
34
|
+
.check_stops(api_key, ['200070', '200060'])
|
|
35
|
+
```
|
|
36
|
+
The return is a JSON-compatible Python object as per the example here:
|
|
37
|
+
```
|
|
38
|
+
{
|
|
39
|
+
"all_stops_valid": true,
|
|
40
|
+
"stop_list": [
|
|
41
|
+
{
|
|
42
|
+
"stop_id": "200060",
|
|
43
|
+
"valid": true,
|
|
44
|
+
"error_code": 0,
|
|
45
|
+
"stop_detail": {
|
|
46
|
+
"id": "200060",
|
|
47
|
+
"name": "Central Station, Sydney",
|
|
48
|
+
"disassembledName": "Central Station",
|
|
49
|
+
<etc, as per the Transport NSW API>
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"stop_id": "229310",
|
|
55
|
+
"valid": true,
|
|
56
|
+
"error_code": 0,
|
|
57
|
+
"stop_detail": {
|
|
58
|
+
"id": "229310",
|
|
59
|
+
"name": "Newcastle Interchange, Wickham",
|
|
60
|
+
"disassembledName": "Newcastle Interchange",
|
|
61
|
+
<etc, as per the Transport NSW API>
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
Most of the top-level properties are pretty self-explanatory. If all you want to do is get a general yes/no then `all_stops_valid` is the quickest check, although with the latest version raising a StopError exception if a stop ID check fails that's become a little bit academic.
|
|
68
|
+
If the API call was successful then `stop_detail` will contain everything that the API sent back for the closest match it found.
|
|
69
|
+
|
|
70
|
+
### Sample Code - catching an invalid stop
|
|
71
|
+
|
|
72
|
+
The following example checks two stops to see if they're valid, and it turns out that one of them isn't.
|
|
73
|
+
|
|
74
|
+
**Code:**
|
|
75
|
+
```python
|
|
76
|
+
from TransportNSWv2 import TransportNSWv2, StopError
|
|
77
|
+
|
|
78
|
+
tnsw = TransportNSWv2()
|
|
79
|
+
try:
|
|
80
|
+
_data = tnsw.check_stops(<your API key>, ['20006012345', '229310'])
|
|
81
|
+
print (_data['all_stops_valid'])
|
|
82
|
+
|
|
83
|
+
except StopError as ex:
|
|
84
|
+
print (f"Stop error - {ex}")
|
|
85
|
+
|
|
86
|
+
except Exception as ex:
|
|
87
|
+
print (f"Misc error - {ex}")
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Result:**
|
|
91
|
+
```python
|
|
92
|
+
Stop error - Error 'stop invalid' calling stop finder API for stop ID 20006012345
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### get_trip() parameters
|
|
96
|
+
Only the first three parameters are mandatory, the rest are optional. All parameters and their defaults are as follows:
|
|
97
|
+
```python
|
|
98
|
+
.get_trip(name_origin = <origin stop ID>, name_destination = <destination stop ID>, api_key = <your API key>, journey_wait_time = 0, origin_transport_type = [0], destination_transport_type = [0], strict_transport_type = False, journeys_to_return = 1, route_filter = '', include_realtime_location = True, include_alerts = 'none', alert_type = ['all'], raw_output = False, check_stop_ids = True)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`journey_wait_time` is how many minutes from now the departure should be.
|
|
102
|
+
|
|
103
|
+
`origin_transport_type` and `destination_transport_type` are integer lists of vehicle transport types - only journeys whose first/last **non-walking** leg fits the criteria will be included, unless `strict_transport_type` is `True` in which case literally the first and last leg **must** be one of the requested types - it's effectively a 'no walking' filter. A ```transport_type``` of [0] means that **all** transport types are permitted.
|
|
104
|
+
|
|
105
|
+
If `route_filter` has a value then only journeys with that value in either the `origin_line_name` or `origin_line_name_short` fields are included - it's a caseless wildcard search so for example `north` would include 'T1 North Shore & Western Line' journeys.
|
|
106
|
+
|
|
107
|
+
Specifying an alert priority in `include_alerts` means that any alerts of that priority or higher will be included in the output as raw JSON, basically a collation of the alerts that the Trip API sent back. By default **all** alert types will be included - you can limit the output to specific alert types by setting `alert_type` to something like `['lineInfo', 'stopInfo', 'bannerInfo']`.
|
|
108
|
+
|
|
109
|
+
`raw_output` means that function returns whatever came back from the API call as-is, ignoring all of the above optional parameters with the exception of `journey_wait_time`.
|
|
110
|
+
|
|
111
|
+
Setting `check_stop_ids` to `False` does just that - `get_trip()` won't initially check that the provided stop IDs are valid, saving on your daily API quota.
|
|
112
|
+
|
|
113
|
+
Transport types:
|
|
114
|
+
```
|
|
115
|
+
1: Train
|
|
116
|
+
2: Metro
|
|
117
|
+
4: Light rail
|
|
118
|
+
5: Bus
|
|
119
|
+
7: Coach
|
|
120
|
+
9: Ferry
|
|
121
|
+
11: School bus
|
|
122
|
+
99: Walk
|
|
123
|
+
100: Walk
|
|
124
|
+
107: Cycle
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Alert priorities:
|
|
128
|
+
```
|
|
129
|
+
veryLow
|
|
130
|
+
low
|
|
131
|
+
normal
|
|
132
|
+
high
|
|
133
|
+
veryHigh
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Alert types:
|
|
137
|
+
```
|
|
138
|
+
routeInfo: Alerts relating to a specific route
|
|
139
|
+
lineInfo: Alerts relating to a specific journey
|
|
140
|
+
stopInfo: Alerts relating to specific stops
|
|
141
|
+
stopBlocking: Alerts relating to stop closures
|
|
142
|
+
bannerInfo: Alerts potentially relating to network-wide impacts
|
|
143
|
+
all: All alerts
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
TransportNSW's trip planner can work better if you use the general stop IDs (e.g. `220010` for Bankstown Station) rather than a specific stop ID (e.g. `2200501` for Bankstown Station, Platform 1) for the destination, depending on the transport type, as forcing a specific destination stop ID sometimes results in much more complicated trips. Also note that the API expects (and returns) the stop IDs as strings, although so far they all appear to be numeric.
|
|
147
|
+
|
|
148
|
+
### Sample Code - train journey, line and stop-related alerts of normal higher priority included
|
|
149
|
+
The following example returns the next train-only journey that starts from Redfern (`201510`) to Milsons Point (`206110`) ten minutes from now. Two journeys have been requested, we want realtime locations if possible, and we also want lineInfo and stopInfo alerts of priority normal or higher:
|
|
150
|
+
|
|
151
|
+
**Code:**
|
|
152
|
+
```python
|
|
153
|
+
from TransportNSWv2 import TransportNSWv2
|
|
154
|
+
tnsw = TransportNSWv2()
|
|
155
|
+
journey = tnsw.get_trip('201510', '20610', '<your API key>', journey_wait_time = 10 ,origin_transport_type = [1, 2, 4], destination_transport_type = [1, 2, 4], journeys_to_return = 2, include_alerts = 'normal', alert_type = ['lineInfo', 'stopInfo'])
|
|
156
|
+
|
|
157
|
+
print(journey)
|
|
158
|
+
```
|
|
159
|
+
**Result:**
|
|
160
|
+
```python
|
|
161
|
+
{
|
|
162
|
+
"journeys_to_return": 2,
|
|
163
|
+
"journeys_with_data": 2,
|
|
164
|
+
"journeys": [
|
|
165
|
+
{
|
|
166
|
+
"due": 10,
|
|
167
|
+
"delay": 1,
|
|
168
|
+
"origin_stop_id": "2015133",
|
|
169
|
+
"origin_name": "Redfern Station, Platform 3, Eveleigh",
|
|
170
|
+
"departure_time": "2025-08-27T22:13:48Z",
|
|
171
|
+
"destination_stop_id": "206142",
|
|
172
|
+
"destination_name": "Milsons Point Station, Platform 2, Milsons Point",
|
|
173
|
+
"arrival_time": "2025-08-27T22:24:36Z",
|
|
174
|
+
"origin_transport_type": "Train",
|
|
175
|
+
"origin_transport_name": "Sydney Trains Network",
|
|
176
|
+
"origin_line_name": "T1 North Shore & Western Line",
|
|
177
|
+
"origin_line_name_short": "T1",
|
|
178
|
+
"destination_transport_type": "Train",
|
|
179
|
+
"destination_transport_name": "Sydney Trains Network",
|
|
180
|
+
"destination_line_name": "T1 North Shore & Western Line",
|
|
181
|
+
"destination_line_name_short": "T1",
|
|
182
|
+
"changes": 0,
|
|
183
|
+
"origin_occupancy": "n/a",
|
|
184
|
+
"destination_occupancy": "n/a",
|
|
185
|
+
"origin_real_time_trip_id": "159C.938.149.32.A.8.86302165",
|
|
186
|
+
"destination_real_time_trip_id": "159C.938.149.32.A.8.86302165",
|
|
187
|
+
"origin_latitude": -33.875030517578125,
|
|
188
|
+
"origin_longitude": 151.0980682373047,
|
|
189
|
+
"destination_latitude": -33.875030517578125,
|
|
190
|
+
"destination_longitude": 151.0980682373047,
|
|
191
|
+
"alerts": []
|
|
192
|
+
},
|
|
193
|
+
{
|
|
194
|
+
"due": 12,
|
|
195
|
+
"delay": 0,
|
|
196
|
+
"origin_stop_id": "2015133",
|
|
197
|
+
"origin_name": "Redfern Station, Platform 3, Eveleigh",
|
|
198
|
+
"departure_time": "2025-08-27T22:16:00Z",
|
|
199
|
+
"destination_stop_id": "206142",
|
|
200
|
+
"destination_name": "Milsons Point Station, Platform 2, Milsons Point",
|
|
201
|
+
"arrival_time": "2025-08-27T22:27:30Z",
|
|
202
|
+
"origin_transport_type": "Train",
|
|
203
|
+
"origin_transport_name": "Sydney Trains Network",
|
|
204
|
+
"origin_line_name": "T9 Northern Line",
|
|
205
|
+
"origin_line_name_short": "T9",
|
|
206
|
+
"destination_transport_type": "Train",
|
|
207
|
+
"destination_transport_name": "Sydney Trains Network",
|
|
208
|
+
"destination_line_name": "T9 Northern Line",
|
|
209
|
+
"destination_line_name_short": "T9",
|
|
210
|
+
"changes": 0,
|
|
211
|
+
"origin_occupancy": "n/a",
|
|
212
|
+
"destination_occupancy": "n/a",
|
|
213
|
+
"origin_real_time_trip_id": "140C.938.149.48.A.8.86304102",
|
|
214
|
+
"destination_real_time_trip_id": "140C.938.149.48.A.8.86304102",
|
|
215
|
+
"origin_latitude": -33.871639251708984,
|
|
216
|
+
"origin_longitude": 151.0941925048828,
|
|
217
|
+
"destination_latitude": -33.871639251708984,
|
|
218
|
+
"destination_longitude": 151.0941925048828,
|
|
219
|
+
"alerts": []
|
|
220
|
+
}
|
|
221
|
+
]
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
In this example you can see that no actual alerts of that type were provided by the API. Below is an example of the alerts output:
|
|
225
|
+
```
|
|
226
|
+
"alerts": [
|
|
227
|
+
{
|
|
228
|
+
"priority": "normal",
|
|
229
|
+
"id": "ems-53698",
|
|
230
|
+
"version": 17859,
|
|
231
|
+
"type": "lineInfo",
|
|
232
|
+
"properties": {
|
|
233
|
+
"publisher": "ems.comm.addinfo",
|
|
234
|
+
"infoType": "lineInfo",
|
|
235
|
+
"smsText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
236
|
+
"speechText": "From Sunday 29 June, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.\n \nSee the news story for more information at transportnsw.info."
|
|
237
|
+
},
|
|
238
|
+
"infoLinks": [
|
|
239
|
+
{
|
|
240
|
+
"urlText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
241
|
+
"url": "https://transportnsw.info/alerts/details#/ems-53698",
|
|
242
|
+
"content": "<div>From<strong> Sunday 29 June</strong>, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.</div>\n<div> </div>\n<div>See the <a href=\"https://transportnsw.info/news/2025/train-timetable-changes-in-june\">news story</a> for more information.</div>",
|
|
243
|
+
"subtitle": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
244
|
+
"smsText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
245
|
+
"speechText": "From Sunday 29 June, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.\n \nSee the news story for more information at transportnsw.info."
|
|
246
|
+
}
|
|
247
|
+
],
|
|
248
|
+
"urlText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
249
|
+
"url": "https://transportnsw.info/alerts/details#/ems-53698",
|
|
250
|
+
"content": "<div>From<strong> Sunday 29 June</strong>, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.</div>\n<div> </div>\n<div>See the <a href=\"https://transportnsw.info/news/2025/train-timetable-changes-in-june\">news story</a> for more information.</div>",
|
|
251
|
+
"subtitle": "Minor timetable adjustments to some train services from Sunday 29 June"
|
|
252
|
+
}
|
|
253
|
+
]
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
### Output explanations
|
|
257
|
+
|
|
258
|
+
* `due`: the time (in minutes) before the journey starts
|
|
259
|
+
* `delay`: how delayed (in minutes) the next service is. Note that ```due``` already factors in delays
|
|
260
|
+
* `origin_stop_id`: the specific departure stop id of the journey
|
|
261
|
+
* `origin_name`:` the name of the departure location
|
|
262
|
+
* `departure_time`: the departure time, in UTC
|
|
263
|
+
* `destination_stop_id`: the specific destination stop id of the journey
|
|
264
|
+
* `destination_name`: the name of the destination location
|
|
265
|
+
* `arrival_time`: the planned arrival time at the origin, in UTC
|
|
266
|
+
* `origin_transport_type`: the type of transport, eg train, bus, ferry etc of the first leg of the journey
|
|
267
|
+
* `origin_transport_name`: the full name of the first-leg transport provider
|
|
268
|
+
* `origin_line_name` & `origin_line_name_short`: the full and short names of the first-leg line or service
|
|
269
|
+
* `destination_transport_type`: the type of transport, eg train, bus, ferry etc of the final leg of the journey
|
|
270
|
+
* `destination_transport_name`: the full name of the last-leg transport provider
|
|
271
|
+
* `destination_line_name` and `destination_line_name_short`: the full and short names of the last-leg line or service
|
|
272
|
+
* `changes`: how many transport changes are needed on the journey, excluding walking
|
|
273
|
+
* `origin_occupancy`: how full the first-leg vehicle is, if available
|
|
274
|
+
* `destination_occupancy`: how full the last-leg vehicle is, if available
|
|
275
|
+
* `origin_real_time_trip_id`: the unique TransportNSW id for the first-leg vehicle, if available
|
|
276
|
+
* `destination_real_time_trip_id`: the unique TransportNSW id for the last-leg vehicle, if available
|
|
277
|
+
* `origin_latitude/longitude` and `destination_latitude/longitude`: The current location of the first-leg and last-leg vehicles, if available
|
|
278
|
+
* `alerts`: An array of alerts pertinent to that journey
|
|
279
|
+
|
|
280
|
+
For single-leg journeys the `origin_*` and `destination_*` outputs will be identical.
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
### Notes ###
|
|
284
|
+
Requesting multiple journeys to be returned doesn't always return that exact number of journeys. The API call only ever returns five or six and if you have any filters applied then that might further reduce the number of 'valid' journeys.
|
|
285
|
+
|
|
286
|
+
Note that the origin and destination details are just that - information about the first and last stops on the journey at the time the request was made. The output doesn't include any intermediate steps, transport change types etc. other than the total number of changes - the assumption is that you'll know the details of your specified trip, you just want to know when the next departure is. If you need much more detailed information then I recommend that you use the full [Transport NSW trip planner](https://transportnsw.info/trip#/trip) or app, or parse the raw output by adding `raw_output = True` to your call.
|
|
287
|
+
|
|
288
|
+
## Exceptions ##
|
|
289
|
+
The latest release of TransportNSWv2 now uses custom Exceptions when things go wrong, instead of returning None - it's more 'Pythonic'. The Exceptions that can be imported are as follows:
|
|
290
|
+
* InvalidAPIKey - API key-related issues
|
|
291
|
+
* APIRateLimitExceeded - API rate-limit issues
|
|
292
|
+
* StopError - stop ID issues, usually when checking that a stop ID is valid
|
|
293
|
+
* TripError - trip-related issues, including no journeys being returned when calling ```.get_trip()```
|
|
294
|
+
|
|
295
|
+
## Rate limits ##
|
|
296
|
+
By default the TransportNSW API allows each API key to make 60,000 calls in a day and up to 5 calls per second. When requesting real-time location information some services required me to brute-force up to 12 (!) URIs until I found the right one which sometimes resulted in an API rate-limit breach. From version 0.8.7 I found a TransportNSW-maintained CSV that contains mappings of bus agency IDs to URIs so I'm using that, plus adding in a 0.75 second delay between API calls. Plus, if you're confident that the origin and destination IDs are correct you can reduce your totail daily API calls by adding `check_trip_ids = False` in the parameters.
|
|
297
|
+
|
|
298
|
+
## Thank you
|
|
299
|
+
Thank you [Dav0815](https://github.com/Dav0815/TransportNSW) for your TransportNSW library that the vast majority of this fork is based on. I couldn't have done it without you!
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
Platform: UNKNOWN
|
|
303
|
+
Classifier: Programming Language :: Python :: 3
|
|
304
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
305
|
+
Classifier: Operating System :: OS Independent
|
|
306
|
+
Classifier: Intended Audience :: Developers
|
|
307
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
308
|
+
Description-Content-Type: text/markdown
|
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: PyTransportNSWv2
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Get detailed per-trip transport information from TransportNSW
|
|
5
|
+
Home-page: https://github.com/andystewart999/TransportNSW
|
|
6
|
+
Author: andystewart999
|
|
7
|
+
Author-email: andy.stewart@live.com
|
|
8
|
+
License: UNKNOWN
|
|
9
|
+
Description:
|
|
10
|
+
# TransportNSWv2
|
|
11
|
+
Python lib to access Transport NSW stop and journey information.
|
|
12
|
+
|
|
13
|
+
## How to Use
|
|
14
|
+
|
|
15
|
+
### Get an API Key
|
|
16
|
+
An OpenData account and API key is required to request the data. More information on how to create the free account can be found [here](https://opendata.transport.nsw.gov.au/user-guide). You need to register an application that needs both the Trip Planner and Realtime Vehicle Positions APIs.
|
|
17
|
+
|
|
18
|
+
### Get the stop IDs
|
|
19
|
+
The only mandatory parameters are the API key and the origin/destination stop IDs - the easiest way to get the stop ID is via https://transportnsw.info/stops#/ - that page provides the option to search for either a location or a specific platform, bus stop or ferry wharf. Regardless of if you specify a general location for the origin or destination, the return information shows the stop ID for the actual arrival and destination platform, bus stop or ferry wharf.
|
|
20
|
+
|
|
21
|
+
If it's available, the general occupancy level as wel as the latitude and longitude of the selected journey's vehicle(s) (train, bus, etc) will be returned, unless you specifically set `include_realtime_location` to `False`.
|
|
22
|
+
|
|
23
|
+
### API Documentation
|
|
24
|
+
The source Transport NSW API details can be found [here](https://opendata.transport.nsw.gov.au/sites/default/files/2023-08/Trip%20Planner%20API%20manual-opendataproduction%20v3.2.pdf).
|
|
25
|
+
|
|
26
|
+
### Exposed functions
|
|
27
|
+
Two functions are available:
|
|
28
|
+
`get_trip()` returns trip information between two stop IDs
|
|
29
|
+
`check_stops()` lets you confirm that the two stop IDs are valid, plus it returns all the stop ID metadata. Note that ```get_trip()``` calls this function internally (unless you tell it not to, see below) and fails with a `StopError` Exception if either of the stop IDs are invalid, so there's no specific need to call `check_stops()` unless you want the stop ID metadata, or know you'll be calling the same journey multiple times and want to reduce your daily API calls by pre-checking once.
|
|
30
|
+
|
|
31
|
+
### check_stops() parameters
|
|
32
|
+
All parameters are mandatory. Note that `stop_list` can be a single string or a list of strings:
|
|
33
|
+
```python
|
|
34
|
+
.check_stops(api_key, ['200070', '200060'])
|
|
35
|
+
```
|
|
36
|
+
The return is a JSON-compatible Python object as per the example here:
|
|
37
|
+
```
|
|
38
|
+
{
|
|
39
|
+
"all_stops_valid": true,
|
|
40
|
+
"stop_list": [
|
|
41
|
+
{
|
|
42
|
+
"stop_id": "200060",
|
|
43
|
+
"valid": true,
|
|
44
|
+
"error_code": 0,
|
|
45
|
+
"stop_detail": {
|
|
46
|
+
"id": "200060",
|
|
47
|
+
"name": "Central Station, Sydney",
|
|
48
|
+
"disassembledName": "Central Station",
|
|
49
|
+
<etc, as per the Transport NSW API>
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"stop_id": "229310",
|
|
55
|
+
"valid": true,
|
|
56
|
+
"error_code": 0,
|
|
57
|
+
"stop_detail": {
|
|
58
|
+
"id": "229310",
|
|
59
|
+
"name": "Newcastle Interchange, Wickham",
|
|
60
|
+
"disassembledName": "Newcastle Interchange",
|
|
61
|
+
<etc, as per the Transport NSW API>
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
Most of the top-level properties are pretty self-explanatory. If all you want to do is get a general yes/no then `all_stops_valid` is the quickest check, although with the latest version raising a StopError exception if a stop ID check fails that's become a little bit academic.
|
|
68
|
+
If the API call was successful then `stop_detail` will contain everything that the API sent back for the closest match it found.
|
|
69
|
+
|
|
70
|
+
### Sample Code - catching an invalid stop
|
|
71
|
+
|
|
72
|
+
The following example checks two stops to see if they're valid, and it turns out that one of them isn't.
|
|
73
|
+
|
|
74
|
+
**Code:**
|
|
75
|
+
```python
|
|
76
|
+
from TransportNSWv2 import TransportNSWv2, StopError
|
|
77
|
+
|
|
78
|
+
tnsw = TransportNSWv2()
|
|
79
|
+
try:
|
|
80
|
+
_data = tnsw.check_stops(<your API key>, ['20006012345', '229310'])
|
|
81
|
+
print (_data['all_stops_valid'])
|
|
82
|
+
|
|
83
|
+
except StopError as ex:
|
|
84
|
+
print (f"Stop error - {ex}")
|
|
85
|
+
|
|
86
|
+
except Exception as ex:
|
|
87
|
+
print (f"Misc error - {ex}")
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Result:**
|
|
91
|
+
```python
|
|
92
|
+
Stop error - Error 'stop invalid' calling stop finder API for stop ID 20006012345
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### get_trip() parameters
|
|
96
|
+
Only the first three parameters are mandatory, the rest are optional. All parameters and their defaults are as follows:
|
|
97
|
+
```python
|
|
98
|
+
.get_trip(name_origin = <origin stop ID>, name_destination = <destination stop ID>, api_key = <your API key>, journey_wait_time = 0, origin_transport_type = [0], destination_transport_type = [0], strict_transport_type = False, journeys_to_return = 1, route_filter = '', include_realtime_location = True, include_alerts = 'none', alert_type = ['all'], raw_output = False, check_stop_ids = True)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`journey_wait_time` is how many minutes from now the departure should be.
|
|
102
|
+
|
|
103
|
+
`origin_transport_type` and `destination_transport_type` are integer lists of vehicle transport types - only journeys whose first/last **non-walking** leg fits the criteria will be included, unless `strict_transport_type` is `True` in which case literally the first and last leg **must** be one of the requested types - it's effectively a 'no walking' filter. A ```transport_type``` of [0] means that **all** transport types are permitted.
|
|
104
|
+
|
|
105
|
+
If `route_filter` has a value then only journeys with that value in either the `origin_line_name` or `origin_line_name_short` fields are included - it's a caseless wildcard search so for example `north` would include 'T1 North Shore & Western Line' journeys.
|
|
106
|
+
|
|
107
|
+
Specifying an alert priority in `include_alerts` means that any alerts of that priority or higher will be included in the output as raw JSON, basically a collation of the alerts that the Trip API sent back. By default **all** alert types will be included - you can limit the output to specific alert types by setting `alert_type` to something like `['lineInfo', 'stopInfo', 'bannerInfo']`.
|
|
108
|
+
|
|
109
|
+
`raw_output` means that function returns whatever came back from the API call as-is, ignoring all of the above optional parameters with the exception of `journey_wait_time`.
|
|
110
|
+
|
|
111
|
+
Setting `check_stop_ids` to `False` does just that - `get_trip()` won't initially check that the provided stop IDs are valid, saving on your daily API quota.
|
|
112
|
+
|
|
113
|
+
Transport types:
|
|
114
|
+
```
|
|
115
|
+
1: Train
|
|
116
|
+
2: Metro
|
|
117
|
+
4: Light rail
|
|
118
|
+
5: Bus
|
|
119
|
+
7: Coach
|
|
120
|
+
9: Ferry
|
|
121
|
+
11: School bus
|
|
122
|
+
99: Walk
|
|
123
|
+
100: Walk
|
|
124
|
+
107: Cycle
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Alert priorities:
|
|
128
|
+
```
|
|
129
|
+
veryLow
|
|
130
|
+
low
|
|
131
|
+
normal
|
|
132
|
+
high
|
|
133
|
+
veryHigh
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Alert types:
|
|
137
|
+
```
|
|
138
|
+
routeInfo: Alerts relating to a specific route
|
|
139
|
+
lineInfo: Alerts relating to a specific journey
|
|
140
|
+
stopInfo: Alerts relating to specific stops
|
|
141
|
+
stopBlocking: Alerts relating to stop closures
|
|
142
|
+
bannerInfo: Alerts potentially relating to network-wide impacts
|
|
143
|
+
all: All alerts
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
TransportNSW's trip planner can work better if you use the general stop IDs (e.g. `220010` for Bankstown Station) rather than a specific stop ID (e.g. `2200501` for Bankstown Station, Platform 1) for the destination, depending on the transport type, as forcing a specific destination stop ID sometimes results in much more complicated trips. Also note that the API expects (and returns) the stop IDs as strings, although so far they all appear to be numeric.
|
|
147
|
+
|
|
148
|
+
### Sample Code - train journey, line and stop-related alerts of normal higher priority included
|
|
149
|
+
The following example returns the next train-only journey that starts from Redfern (`201510`) to Milsons Point (`206110`) ten minutes from now. Two journeys have been requested, we want realtime locations if possible, and we also want lineInfo and stopInfo alerts of priority normal or higher:
|
|
150
|
+
|
|
151
|
+
**Code:**
|
|
152
|
+
```python
|
|
153
|
+
from TransportNSWv2 import TransportNSWv2
|
|
154
|
+
tnsw = TransportNSWv2()
|
|
155
|
+
journey = tnsw.get_trip('201510', '20610', '<your API key>', journey_wait_time = 10 ,origin_transport_type = [1, 2, 4], destination_transport_type = [1, 2, 4], journeys_to_return = 2, include_alerts = 'normal', alert_type = ['lineInfo', 'stopInfo'])
|
|
156
|
+
|
|
157
|
+
print(journey)
|
|
158
|
+
```
|
|
159
|
+
**Result:**
|
|
160
|
+
```python
|
|
161
|
+
{
|
|
162
|
+
"journeys_to_return": 2,
|
|
163
|
+
"journeys_with_data": 2,
|
|
164
|
+
"journeys": [
|
|
165
|
+
{
|
|
166
|
+
"due": 10,
|
|
167
|
+
"delay": 1,
|
|
168
|
+
"origin_stop_id": "2015133",
|
|
169
|
+
"origin_name": "Redfern Station, Platform 3, Eveleigh",
|
|
170
|
+
"departure_time": "2025-08-27T22:13:48Z",
|
|
171
|
+
"destination_stop_id": "206142",
|
|
172
|
+
"destination_name": "Milsons Point Station, Platform 2, Milsons Point",
|
|
173
|
+
"arrival_time": "2025-08-27T22:24:36Z",
|
|
174
|
+
"origin_transport_type": "Train",
|
|
175
|
+
"origin_transport_name": "Sydney Trains Network",
|
|
176
|
+
"origin_line_name": "T1 North Shore & Western Line",
|
|
177
|
+
"origin_line_name_short": "T1",
|
|
178
|
+
"destination_transport_type": "Train",
|
|
179
|
+
"destination_transport_name": "Sydney Trains Network",
|
|
180
|
+
"destination_line_name": "T1 North Shore & Western Line",
|
|
181
|
+
"destination_line_name_short": "T1",
|
|
182
|
+
"changes": 0,
|
|
183
|
+
"origin_occupancy": "n/a",
|
|
184
|
+
"destination_occupancy": "n/a",
|
|
185
|
+
"origin_real_time_trip_id": "159C.938.149.32.A.8.86302165",
|
|
186
|
+
"destination_real_time_trip_id": "159C.938.149.32.A.8.86302165",
|
|
187
|
+
"origin_latitude": -33.875030517578125,
|
|
188
|
+
"origin_longitude": 151.0980682373047,
|
|
189
|
+
"destination_latitude": -33.875030517578125,
|
|
190
|
+
"destination_longitude": 151.0980682373047,
|
|
191
|
+
"alerts": []
|
|
192
|
+
},
|
|
193
|
+
{
|
|
194
|
+
"due": 12,
|
|
195
|
+
"delay": 0,
|
|
196
|
+
"origin_stop_id": "2015133",
|
|
197
|
+
"origin_name": "Redfern Station, Platform 3, Eveleigh",
|
|
198
|
+
"departure_time": "2025-08-27T22:16:00Z",
|
|
199
|
+
"destination_stop_id": "206142",
|
|
200
|
+
"destination_name": "Milsons Point Station, Platform 2, Milsons Point",
|
|
201
|
+
"arrival_time": "2025-08-27T22:27:30Z",
|
|
202
|
+
"origin_transport_type": "Train",
|
|
203
|
+
"origin_transport_name": "Sydney Trains Network",
|
|
204
|
+
"origin_line_name": "T9 Northern Line",
|
|
205
|
+
"origin_line_name_short": "T9",
|
|
206
|
+
"destination_transport_type": "Train",
|
|
207
|
+
"destination_transport_name": "Sydney Trains Network",
|
|
208
|
+
"destination_line_name": "T9 Northern Line",
|
|
209
|
+
"destination_line_name_short": "T9",
|
|
210
|
+
"changes": 0,
|
|
211
|
+
"origin_occupancy": "n/a",
|
|
212
|
+
"destination_occupancy": "n/a",
|
|
213
|
+
"origin_real_time_trip_id": "140C.938.149.48.A.8.86304102",
|
|
214
|
+
"destination_real_time_trip_id": "140C.938.149.48.A.8.86304102",
|
|
215
|
+
"origin_latitude": -33.871639251708984,
|
|
216
|
+
"origin_longitude": 151.0941925048828,
|
|
217
|
+
"destination_latitude": -33.871639251708984,
|
|
218
|
+
"destination_longitude": 151.0941925048828,
|
|
219
|
+
"alerts": []
|
|
220
|
+
}
|
|
221
|
+
]
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
In this example you can see that no actual alerts of that type were provided by the API. Below is an example of the alerts output:
|
|
225
|
+
```
|
|
226
|
+
"alerts": [
|
|
227
|
+
{
|
|
228
|
+
"priority": "normal",
|
|
229
|
+
"id": "ems-53698",
|
|
230
|
+
"version": 17859,
|
|
231
|
+
"type": "lineInfo",
|
|
232
|
+
"properties": {
|
|
233
|
+
"publisher": "ems.comm.addinfo",
|
|
234
|
+
"infoType": "lineInfo",
|
|
235
|
+
"smsText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
236
|
+
"speechText": "From Sunday 29 June, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.\n \nSee the news story for more information at transportnsw.info."
|
|
237
|
+
},
|
|
238
|
+
"infoLinks": [
|
|
239
|
+
{
|
|
240
|
+
"urlText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
241
|
+
"url": "https://transportnsw.info/alerts/details#/ems-53698",
|
|
242
|
+
"content": "<div>From<strong> Sunday 29 June</strong>, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.</div>\n<div> </div>\n<div>See the <a href=\"https://transportnsw.info/news/2025/train-timetable-changes-in-june\">news story</a> for more information.</div>",
|
|
243
|
+
"subtitle": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
244
|
+
"smsText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
245
|
+
"speechText": "From Sunday 29 June, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.\n \nSee the news story for more information at transportnsw.info."
|
|
246
|
+
}
|
|
247
|
+
],
|
|
248
|
+
"urlText": "Minor timetable adjustments to some train services from Sunday 29 June",
|
|
249
|
+
"url": "https://transportnsw.info/alerts/details#/ems-53698",
|
|
250
|
+
"content": "<div>From<strong> Sunday 29 June</strong>, minor timetable adjustments will be made to some train services. These adjustments are being introduced as part of a regular review of train services to improve reliability for passengers.</div>\n<div> </div>\n<div>See the <a href=\"https://transportnsw.info/news/2025/train-timetable-changes-in-june\">news story</a> for more information.</div>",
|
|
251
|
+
"subtitle": "Minor timetable adjustments to some train services from Sunday 29 June"
|
|
252
|
+
}
|
|
253
|
+
]
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
### Output explanations
|
|
257
|
+
|
|
258
|
+
* `due`: the time (in minutes) before the journey starts
|
|
259
|
+
* `delay`: how delayed (in minutes) the next service is. Note that ```due``` already factors in delays
|
|
260
|
+
* `origin_stop_id`: the specific departure stop id of the journey
|
|
261
|
+
* `origin_name`:` the name of the departure location
|
|
262
|
+
* `departure_time`: the departure time, in UTC
|
|
263
|
+
* `destination_stop_id`: the specific destination stop id of the journey
|
|
264
|
+
* `destination_name`: the name of the destination location
|
|
265
|
+
* `arrival_time`: the planned arrival time at the origin, in UTC
|
|
266
|
+
* `origin_transport_type`: the type of transport, eg train, bus, ferry etc of the first leg of the journey
|
|
267
|
+
* `origin_transport_name`: the full name of the first-leg transport provider
|
|
268
|
+
* `origin_line_name` & `origin_line_name_short`: the full and short names of the first-leg line or service
|
|
269
|
+
* `destination_transport_type`: the type of transport, eg train, bus, ferry etc of the final leg of the journey
|
|
270
|
+
* `destination_transport_name`: the full name of the last-leg transport provider
|
|
271
|
+
* `destination_line_name` and `destination_line_name_short`: the full and short names of the last-leg line or service
|
|
272
|
+
* `changes`: how many transport changes are needed on the journey, excluding walking
|
|
273
|
+
* `origin_occupancy`: how full the first-leg vehicle is, if available
|
|
274
|
+
* `destination_occupancy`: how full the last-leg vehicle is, if available
|
|
275
|
+
* `origin_real_time_trip_id`: the unique TransportNSW id for the first-leg vehicle, if available
|
|
276
|
+
* `destination_real_time_trip_id`: the unique TransportNSW id for the last-leg vehicle, if available
|
|
277
|
+
* `origin_latitude/longitude` and `destination_latitude/longitude`: The current location of the first-leg and last-leg vehicles, if available
|
|
278
|
+
* `alerts`: An array of alerts pertinent to that journey
|
|
279
|
+
|
|
280
|
+
For single-leg journeys the `origin_*` and `destination_*` outputs will be identical.
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
### Notes ###
|
|
284
|
+
Requesting multiple journeys to be returned doesn't always return that exact number of journeys. The API call only ever returns five or six and if you have any filters applied then that might further reduce the number of 'valid' journeys.
|
|
285
|
+
|
|
286
|
+
Note that the origin and destination details are just that - information about the first and last stops on the journey at the time the request was made. The output doesn't include any intermediate steps, transport change types etc. other than the total number of changes - the assumption is that you'll know the details of your specified trip, you just want to know when the next departure is. If you need much more detailed information then I recommend that you use the full [Transport NSW trip planner](https://transportnsw.info/trip#/trip) or app, or parse the raw output by adding `raw_output = True` to your call.
|
|
287
|
+
|
|
288
|
+
## Exceptions ##
|
|
289
|
+
The latest release of TransportNSWv2 now uses custom Exceptions when things go wrong, instead of returning None - it's more 'Pythonic'. The Exceptions that can be imported are as follows:
|
|
290
|
+
* InvalidAPIKey - API key-related issues
|
|
291
|
+
* APIRateLimitExceeded - API rate-limit issues
|
|
292
|
+
* StopError - stop ID issues, usually when checking that a stop ID is valid
|
|
293
|
+
* TripError - trip-related issues, including no journeys being returned when calling ```.get_trip()```
|
|
294
|
+
|
|
295
|
+
## Rate limits ##
|
|
296
|
+
By default the TransportNSW API allows each API key to make 60,000 calls in a day and up to 5 calls per second. When requesting real-time location information some services required me to brute-force up to 12 (!) URIs until I found the right one which sometimes resulted in an API rate-limit breach. From version 0.8.7 I found a TransportNSW-maintained CSV that contains mappings of bus agency IDs to URIs so I'm using that, plus adding in a 0.75 second delay between API calls. Plus, if you're confident that the origin and destination IDs are correct you can reduce your totail daily API calls by adding `check_trip_ids = False` in the parameters.
|
|
297
|
+
|
|
298
|
+
## Thank you
|
|
299
|
+
Thank you [Dav0815](https://github.com/Dav0815/TransportNSW) for your TransportNSW library that the vast majority of this fork is based on. I couldn't have done it without you!
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
Platform: UNKNOWN
|
|
303
|
+
Classifier: Programming Language :: Python :: 3
|
|
304
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
305
|
+
Classifier: Operating System :: OS Independent
|
|
306
|
+
Classifier: Intended Audience :: Developers
|
|
307
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
308
|
+
Description-Content-Type: text/markdown
|