https://github.com/nolanbconaway/underground
Utilities for NYC's realtime MTA data feeds.
https://github.com/nolanbconaway/underground
command-line mta nyc python transit
Last synced: about 1 month ago
JSON representation
Utilities for NYC's realtime MTA data feeds.
- Host: GitHub
- URL: https://github.com/nolanbconaway/underground
- Owner: nolanbconaway
- Created: 2019-07-31T02:38:37.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-11-10T16:45:26.000Z (11 months ago)
- Last Synced: 2024-12-15T03:24:05.596Z (10 months ago)
- Topics: command-line, mta, nyc, python, transit
- Language: Python
- Homepage:
- Size: 3.5 MB
- Stars: 18
- Watchers: 2
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# Python MTA Utilities
[](https://github.com/nolanbconaway/underground/actions)
[](https://pypi.org/project/underground/)
[](https://pypi.org/project/underground/)
This is a set of Python utilities that I use to deal with [real-time NYC subway data](https://datamine.mta.info/).
I usually want to know when trains are going to depart a specific stop along a specific train line, so right now the tools are mostly for that. But I tried to write them to support arbitrary functionality.
## Install
``` sh
pip install underground
```
Or if you'd like to live dangerously:
``` sh
pip install git+https://github.com/nolanbconaway/underground.git#egg=underground
```
## Python API
Use the Python API like:
``` python
import os
from underground import metadata, SubwayFeed
ROUTE = 'Q'
feed = SubwayFeed.get(ROUTE)
# under the hood, the Q route is mapped to a URL. This call is equivalent:
URL = 'https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw'
feed = SubwayFeed.get(URL)
# or
URL = metadata.resolve_url(ROUTE)
feed = SubwayFeed.get(URL)
```
### List train stops on each line
`feed.extract_stop_dict` will return a dictionary of dictionaries, like:
```python
>>> feed.extract_stop_dict()
{
"route_1": {
"stop_1": [datetime.datetime(...), datetime.datetime(...)],
"stop_2": [datetime.datetime(...), datetime.datetime(...)],
...
},
"route_2": {
"stop_1": [datetime.datetime(...), datetime.datetime(...)],
"stop_2": [datetime.datetime(...), datetime.datetime(...)],
...
}
}
```
## CLI
The `underground` command line tool is also installed with the package.
### `feed`
```
$ underground feed --help
Usage: underground feed [OPTIONS] ROUTE_OR_URL
Request an MTA feed via a route or URL.
ROUTE_OR_URL may be either a feed URL or a route (which will be used to
look up the feed url).
Examples (both access the same feed):
underground feed Q --json > feed_nrqw.json
URL='https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw' &&
underground feed $URL --json > feed_nrqw.json
Options:
--json Option to output the feed data as JSON. Otherwise
output will be bytes.
-r, --retries INTEGER Retry attempts in case of API connection failure.
Default 100.
--help Show this message and exit.
```
### `stops`
```
$ underground stops --help
Usage: underground stops [OPTIONS] [H|M|D|1|Z|A|N|GS|SI|J|G|Q|L|B|R|F|E|2|7|W|
6|4|C|5|FS]
Print out train departure times for all stops on a subway line.
Options:
-f, --format TEXT strftime format for stop times. Use `epoch` for a
unix timestamp.
-r, --retries INTEGER Retry attempts in case of API connection failure.
Default 100.
-t, --timezone TEXT Output timezone. Ignored if --epoch. Default to NYC
time.
-s, --stalled-timeout INTEGER Number of seconds between the last movement
of a train and the API update before
considering a train stalled. Default is 90 as
recommended by the MTA. Numbers less than 1
disable this check.
--help Show this message and exit.
```
Stops are printed to stdout in the format `stop_id t1 t2 ... tn` .
``` sh
$ underground stops Q | tail -2
Q05S 19:01 19:09 19:16 19:25 19:34 19:44 19:51 19:58
Q04S 19:03 19:11 19:18 19:27 19:36 19:46 19:53 20:00
```
If you know your stop id (stop IDs can be found in [stops.txt](http://web.mta.info/developers/data/nyct/subway/google_transit.zip)), you can grep the results:
``` sh
$ underground stops Q | grep Q05S
Q05S 19:09 19:16 19:25 19:34 19:44 19:51 19:58
```
If you don't know your stop, see below for a handy tool!
### `findstops`
```
$ underground findstops --help
Usage: underground findstops [OPTIONS] QUERY...
Find your stop ID.
Query a location and look for your stop ID, like:
$ underground findstops parkside av
Options:
--json Option to output the data as JSON. Otherwise will be human readable
table.
--help Show this message and exit.
```
Enter the name of your stop and a table of stops with matching names will be returned.
```
$ underground findstops parkside
ID: D27N Direction: NORTH Lat/Lon: 40.655292, -73.961495 Name: PARKSIDE AV
ID: D27S Direction: SOUTH Lat/Lon: 40.655292, -73.961495 Name: PARKSIDE AV
```
Some names are ambiguous (try "fulton st"), for these you'll have to dig into the [metadata](http://web.mta.info/developers/data/nyct/subway/google_transit.zip) more carefully.