{"id":22115303,"url":"https://github.com/nolanbconaway/underground","last_synced_at":"2025-08-25T00:31:49.492Z","repository":{"id":46866709,"uuid":"199764143","full_name":"nolanbconaway/underground","owner":"nolanbconaway","description":"Utilities for NYC's realtime MTA data feeds.","archived":false,"fork":false,"pushed_at":"2024-11-10T16:45:26.000Z","size":3667,"stargazers_count":18,"open_issues_count":1,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-15T03:24:05.596Z","etag":null,"topics":["command-line","mta","nyc","python","transit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nolanbconaway.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-31T02:38:37.000Z","updated_at":"2024-11-10T16:37:37.000Z","dependencies_parsed_at":"2023-11-29T00:25:02.843Z","dependency_job_id":"4623bd81-6269-4cb4-8bde-55574ffab2fd","html_url":"https://github.com/nolanbconaway/underground","commit_stats":{"total_commits":149,"total_committers":2,"mean_commits":74.5,"dds":0.04026845637583898,"last_synced_commit":"a2ddec274d2fd77db76f78a8dead315259ca9f1c"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanbconaway%2Funderground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanbconaway%2Funderground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanbconaway%2Funderground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolanbconaway%2Funderground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nolanbconaway","download_url":"https://codeload.github.com/nolanbconaway/underground/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230852591,"owners_count":18290081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","mta","nyc","python","transit"],"created_at":"2024-12-01T12:15:20.837Z","updated_at":"2024-12-22T15:48:53.501Z","avatar_url":"https://github.com/nolanbconaway.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python MTA Utilities\n\n[![badge](https://github.com/nolanbconaway/underground/workflows/Push/badge.svg)](https://github.com/nolanbconaway/underground/actions)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/underground)](https://pypi.org/project/underground/)\n[![PyPI](https://img.shields.io/pypi/v/underground)](https://pypi.org/project/underground/)\n\nThis is a set of Python utilities that I use to deal with [real-time NYC subway data](https://datamine.mta.info/).\n\nI 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.\n\n## Install\n\n``` sh\npip install underground\n```\n\nOr if you'd like to live dangerously:\n\n``` sh\npip install git+https://github.com/nolanbconaway/underground.git#egg=underground\n```\n\n## Python API\n\nUse the Python API like:\n\n``` python\nimport os\n\nfrom underground import metadata, SubwayFeed\n\nROUTE = 'Q'\nfeed = SubwayFeed.get(ROUTE)\n\n# under the hood, the Q route is mapped to a URL. This call is equivalent:\nURL = 'https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw'\nfeed = SubwayFeed.get(URL)\n\n# or\nURL = metadata.resolve_url(ROUTE)\nfeed = SubwayFeed.get(URL)\n```\n\n### List train stops on each line\n\n`feed.extract_stop_dict` will return a dictionary of dictionaries, like:\n\n```python\n\u003e\u003e\u003e feed.extract_stop_dict()\n\n{\n\n  \"route_1\": {\n    \"stop_1\": [datetime.datetime(...), datetime.datetime(...)], \n    \"stop_2\": [datetime.datetime(...), datetime.datetime(...)], \n    ...\n  }, \n  \"route_2\": {\n    \"stop_1\": [datetime.datetime(...), datetime.datetime(...)], \n    \"stop_2\": [datetime.datetime(...), datetime.datetime(...)], \n    ...\n  }\n\n}\n```\n\n## CLI\n\nThe `underground` command line tool is also installed with the package.\n\n### `feed` \n```\n$ underground feed --help\nUsage: underground feed [OPTIONS] ROUTE_OR_URL\n\n  Request an MTA feed via a route or URL.\n\n  ROUTE_OR_URL may be either a feed URL or a route (which will be used to\n  look up the feed url).\n\n  Examples (both access the same feed):\n\n      underground feed Q --json \u003e feed_nrqw.json\n\n      URL='https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw' \u0026\u0026\n      underground feed $URL --json \u003e feed_nrqw.json\n\nOptions:\n  --json                 Option to output the feed data as JSON. Otherwise\n                         output will be bytes.\n\n  -r, --retries INTEGER  Retry attempts in case of API connection failure.\n                         Default 100.\n\n  --help                 Show this message and exit.\n```\n\n### `stops` \n\n```\n$ underground stops --help\nUsage: underground stops [OPTIONS] [H|M|D|1|Z|A|N|GS|SI|J|G|Q|L|B|R|F|E|2|7|W|\n                          6|4|C|5|FS]\n    \n  Print out train departure times for all stops on a subway line.\n\nOptions:\n\n  -f, --format TEXT      strftime format for stop times. Use `epoch` for a\n                          unix timestamp.\n  -r, --retries INTEGER  Retry attempts in case of API connection failure.\n                          Default 100.\n  -t, --timezone TEXT    Output timezone. Ignored if --epoch. Default to NYC\n                          time.\n  -s, --stalled-timeout INTEGER  Number of seconds between the last movement\n                                 of a train and the API update before\n                                 considering a train stalled. Default is 90 as\n                                 recommended by the MTA. Numbers less than 1\n                                 disable this check.\n  --help                 Show this message and exit.\n```\n\nStops are printed to stdout in the format `stop_id t1 t2 ... tn` .\n\n``` sh\n$ underground stops Q | tail -2\nQ05S 19:01 19:09 19:16 19:25 19:34 19:44 19:51 19:58\nQ04S 19:03 19:11 19:18 19:27 19:36 19:46 19:53 20:00\n```\n\nIf 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:\n\n``` sh\n$ underground stops Q | grep Q05S\nQ05S 19:09 19:16 19:25 19:34 19:44 19:51 19:58\n```\n\nIf you don't know your stop, see below for a handy tool!\n\n### `findstops` \n\n```\n$ underground findstops --help\nUsage: underground findstops [OPTIONS] QUERY...\n\n  Find your stop ID.\n\n  Query a location and look for your stop ID, like:\n\n  $ underground findstops parkside av\n\nOptions:\n\n  --json  Option to output the data as JSON. Otherwise will be human readable\n          table.\n\n  --help  Show this message and exit.\n```\n\nEnter the name of your stop and a table of stops with matching names will be returned.\n\n```\n$ underground findstops parkside\nID: D27N    Direction: NORTH    Lat/Lon: 40.655292, -73.961495    Name: PARKSIDE AV\nID: D27S    Direction: SOUTH    Lat/Lon: 40.655292, -73.961495    Name: PARKSIDE AV\n```\n\nSome 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanbconaway%2Funderground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnolanbconaway%2Funderground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanbconaway%2Funderground/lists"}