Mobility Database Catalogs

To run this project on macOS, you need Python 3.9+, Pip, GDAL, and the RTree (Libspatialindex) library. It is highly recommended to use a Python virtual environment.

1. Install System Dependencies

Use Homebrew to install Python and the required spatial libraries:

brew install python3.9
brew install GDAL
brew install spatialindex

2. Set up a Virtual Environment

Create and activate a Python 3.9 virtual environment to isolate dependencies:

python3.9 -m venv env
source env/bin/activate

3. Install Project Requirements

With the virtual environment activated, install the necessary Python packages:

pip install -r requirements.txt

# Install system dependencies
brew install python3.9
brew install GDAL
brew install spatialindex

# Setup virtual environment
python3.9 -m venv env
source env/bin/activate

# Install requirements
pip install -r requirements.txt

You can browse open mobility data feeds or pull the latest feed URLs by downloading the project's CSV spreadsheet.

Important Considerations:

• Version: Use the current version of the spreadsheet (v2), which includes all feeds from the Mobility Database along with automatically extracted features and feed status information.
• Freshness: If you are consuming the spreadsheet in an automated way, download a new version every time you use it. The latest.url field is updated periodically to reflect changes in provider or subdivision names.
• Deprecation Warning: The legacy CSV will be deprecated and unavailable after July 30th, 2025.
• ID Mapping: To cross-reference IDs between the Mobility Database, TransitFeeds, and Transitland, use the ID map spreadsheet.

https://files.mobilitydatabase.org/feeds_v2.csv

After installation, you can interact with the catalogs via a Python interpreter. Import the operations module to access various filtering functions.

Import Operations

from tools.operations import *

Available Filtering Functions

Get all sources

Returns all available feeds:

get_sources()

Filter by Subdivision

Use an ISO 3166-2 subdivision name:

get_sources_by_subdivision_name(subdivision_name='US-CA')

Filter by Country

Use an ISO 3166-1 alpha-2 code:

get_sources_by_country_code(country_code='US')

Filter by Bounding Box

Use floats for latitude and longitude boundaries:

get_sources_by_bounding_box(
    minimum_latitude=45.0,
    maximum_latitude=46.0,
    minimum_longitude=-123.0,
    maximum_longitude=-122.0
)

Filter by Feature

Filter by specific feature strings. Supported values:

• fares-v2
• fares-v1
• flex-v1
• flex-v2
• pathways
• occupancy

get_sources_by_feature(feature='fares-v2')

Filter by Status

Filter by the status of the feed. Supported values:

• active
• deprecated
• inactive
• development

get_sources_by_status(status='active')

from tools.operations import *

# Example: Get all sources
get_sources()

# Example: Get sources by country
get_sources_by_country_code(country_code='US')

The GTFS Schedule schema defines the structure for static GTFS feeds.

Key Fields:

• mdb_source_id: Unique numerical identifier (System generated).
• data_type: Must be gtfs.
• features: Optional array of enums (e.g., fares-v2, fares-v1, flex-v1, flex-v2, pathways).
• status: Optional enum (active, deprecated, inactive, development). Defaults to active.
• is_official: Optional boolean (defaults to False).
• is_seasonal: Optional enum (True, False, null).
• location: Required object containing country_code (ISO 3166-1 alpha-2), subdivision_name (ISO 3166-2), municipality, and a system-generated bounding_box.
• urls: Required object containing direct_download, latest (System generated), and license.
• redirect: Optional object for pointing deprecated feeds to a new id and comment.

|Field Name|Type|Presence|Definition|
|-|-|-|-|
| mdb_source_id |  Unique ID | System generated | Unique numerical identifier for the feed.      |
| data_type     | Enum| Required| The data format that the feed uses: `gtfs`.|
| features      | Array of Enums | Optional | An array of features which can be any of: <ul><li>`fares-v2`</li><li>`fares-v1`</li><li>`flex-v1`</li><li>`flex-v2`</li><li>`pathways`</li></ul>|
| status        | Enum | Optional | Describes status of the feed. Should be one of: <ul><li`active`: The feed service is current.</li><li`deprecated`: Feed is explicitly deprecated and should not be used in public trip planners.</li><li`inactive`: Feed hasn't been recently updated and should be used at risk of providing outdated information.</li><li`development`: Feed is being used for development purposes and should not be used in public trip planners.</li></ul>Feed is assumed to be `active` if status is not explicitly provided.|
| is_official        | Enum | Optional | Flag indicating if the source comes from the agency itself or not.  <ul><li`True`: Feed comes from the agency as an authorized source.</li><li`False`: Feed is created by researchers or partners unaffiliated with the agency or municipality.</li></ul>Feed's is_official flag is assumed to be `False` if it is not explicitly provided.|
| is_producer_url_unstable | Enum | Optional | Indicates whether the feed's producer URL is stable and unchanging over time. <ul><li`False`: Producer URL is stable and unchanging over time.</li><li`True`: Producer URL is unstable and changes over time. This may be indicated from a timestamp in the URL, website documentation, or other information that indicates this URL changes more than twice a year.</li><li`null`: There is not enough information to describe the stability of the producer URL.</li></ul> |
| is_seasonal | Enum | Optional | Indicates whether the feed is only available seasonally (e.g. summer or winter service). <ul><li`False`: Feed is available year-round.</li><li`True`: Feed is only available during a specific season.</li><li`null`: There is not enough information to describe the seasonality of the feed.</li></ul> |
|redirect| Object | Optional | When a feed is deprecated by a provider and replaced with a new URL, redirect information is provided to point to the new feed.|
| - id      | String | Optional | New feed ID that replaces the current feed that is out of date or no longer maintained by the provider. |
| - comment | Optional | Optional | comment to explain redirect if needed (e.g new aggregate feed) |
|location| Object | Required |Contains  <ul><liText that describes the feed's location in the `country_code`, `subdivision_name`, and `municipality` fields.</li><liLatitude, longitude, date and time that describes the feed's bounding box in the `bounding_box` subobject. </li></ul>|
| - country_code       | Text |Required                  | ISO 3166-1 alpha-2 code designating the country where the feed service is located. For a list of valid codes [see here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).                                                    |
| - subdivision_name  | Text |Optional              | ISO 3166-2 subdivision name designating the subdivision (e.g province, state, region) where the feed service is located. For a list of valid names [see here](https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2).|
| - municipality  | Text |Optional              | Primary municipality in which the feed is located.|
| - bounding_box  | Object|System generated             | Bounding box of the feed  when it was first added to the catalog. Contains `minimum_latitude`, `maximum_latitude`, `minimum_longitude`, `maximum_longitude` and `extracted_on` fields. If the bounding box information displays as "null", you can check any potential feed errors with [the GTFS validator](https://github.com/MobilityData/gtfs-validator). Note: it is not always updated in the catalogs JSON file, but is always accurate the Mobility Database API.  |
| --minimum_latitude    | Latitude | System generated                    | The minimum latitude for the feed's bounding box.
| --maximum_latitude    | Latitude | System generated                    | The maximum latitude for the feed's bounding box.
| --minimum_longitude    | Longitude | System generated                    | The minimum longitude for the feed's bounding box.
| --maximum_longitude    | Longitude | System generated                    | The maximum longitude for the feed's bounding box.
| --extracted_on   | Date and Time | System generated                    | The date and timestamp the bounding box was extracted on in UTC.|
| provider     | Text | Required                   | A commonly used name for the transit provider included in the feed. |
| feed_contact_email | Text | Optional | The contact information for the data producer of the feed, discovered via feed_info.feed_contact_email in the feed, the provider's website, or the Mobility Database contributor form. |
| name        |  Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers, or which network is represented by the feed. |
|urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url`, `latest`, and `license` fields.|
|- direct_download |URL|Optional     | URL that automatically opens the feed. |
|- authentication_type |Enum|Optional| The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: <ul> <li**0** or **(empty)** - No authentication required.</li><li**1** - The authentication requires an API key, which should be passed as value of the parameter `api_key_parameter_name` in the URL. Please visit URL in `authentication_info_url` for more information. </li><li**2** - The authentication requires an HTTP header, which should be passed as the value of the header `api_key_parameter_name` in the HTTP request. </li></ul> When not provided, the authentication type is assumed to be **0.**|
|- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` and `authentication_type=2`. |
|- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. |
|- latest | URL | System generated | A stable URL for the latest dataset of a feed. |
|- license |URL| Optional | The license information for the direct download URL. |

The GTFS Realtime schema defines the structure for real-time transit feeds.

Key Fields:

• mdb_source_id: Unique numerical identifier (System generated).
• data_type: Must be gtfs-rt.
• entity_type: Required array of enums (vp for vehicle positions, tu for trip updates, or sa for service alerts).
• provider: Required transit provider name.
• features: Optional array of enums (e.g., occupancy).
• status: Optional enum (active, deprecated, inactive, development). Defaults to active.
• static_reference: Optional array of strings containing MDB source IDs of associated static feeds.
• urls: Required object containing direct_download_url and license_url.
• urls.authentication_type: Optional enum:
  • 0 or empty: No authentication.
  • 1: API key in URL via api_key_parameter_name.
  • 2: API key in HTTP header via api_key_parameter_name.
  • 3: Ad-hoc authentication (refer to authentication_info_url).
• urls.authentication_info_url: Required if authentication_type >= 1.
• urls.api_key_parameter_name: Required if authentication_type is 1 or 2.

|Field Name|Type|Presence|Definition|
|-|-|-|-|
| mdb_source_id | Unique ID | System generated | Unique numerical identifier.      |
| data_type     | Enum| Required| The data format that the feed uses: `gtfs-rt`.                                                                                                |
|entity_type|Array of Enums|Required|The type of realtime entity: `vp`, `tu`, or `sa` which represent vehicle positions, trip updates, and service alerts. |
| provider     | Text | Required | A commonly used name for the transit provider included in the feed. |
| name        | Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers |
|note|Text| Optional|A note to clarify complex use cases for consumers, for example when several static feeds are associated with a realtime feed.  |
| features      | Array of Enums | Optional | An array of features which can be any of: <ul><li`occupancy`</li></ul>|
| status        | Enum | Optional |  Describes status of the feed. Should be one of: <ul><li`active`: The feed service is current.</li><li`deprecated`: Feed is explicitly deprecated and should not be used in public trip planners.</li><li`inactive`: Feed hasn't been recently updated and should be used at risk of providing outdated information.</li><li`development`: Feed is being used for development purposes and should not be used in public trip planners.</li></ul>Feed is assumed to be `active` if status is not explicitly provided.|  |
|redirect| Object | Optional | When a feed is deprecated by a provider and replaced with a new URL, redirect information is provided to point to the new feed.|
| - id      | String | Optional | New feed ID that replaces the current feed that is out of date or no longer maintained by the provider. |
| - comment | String | Optional | comment to explain redirect if needed (e.g new aggregate feed) |
| static_reference |  Array of Strings |Optional              | A list of the static feeds that the real time feed is associated with, represented by their MDB source IDs. |
|urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url` and `license_url` fields, and the authentication info for `direct_download_url` in the `authentication_type`, `authentication_info_url` and `api_key_parameter_name` fields.|
|- direct_download_url |URL|Required     | URL that responds with an encoded [GTFS Realtime protocol buffer message](https://github.com/google/transit/tree/master/gtfs-realtime/spec/en#data-format).|
|- authentication_type |Enum|Optional| The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: <ul> <li**0** or **(empty)** - No authentication required.</li><li**1** - The authentication requires an API key, which should be passed as value of the parameter `api_key_parameter_name` in the URL. Please visit URL in `authentication_info_url` for more information. </li><li**2** - The authentication requires an HTTP header, which should be passed as the value of the header `api_key_parameter_name` in the HTTP request. </li></li>**3**: Ad-hoc authentication required, visit URL in `authentication_info_url` for more information.</li></ul> When not provided, the authentication type is assumed to be **0.**|
|- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` or greater. |
|- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`.   |
|- license_url  |URL| Optional | The license information for  `direct_download_url`. |

The validate_practices function iterates through a set of rules (practices) and applies their associated validator functions to a dataset to check for compliance.

Parameters:

• practices: A pandas DataFrame containing rule definitions. It must include columns: mdb_id, rule_id, validator, file.
• results: A pandas DataFrame acting as the results container where compliance status is recorded.

Behavior: For each rule in practices, it executes best_practice.validator(dataset_path, report_folder_path, best_practice.file) and updates the results DataFrame at the intersection of the current mdb_id and rule_id.

def validate_practices(practices, results):
    for index, best_practice in practices.iterrows():
        results.loc[results.mdb_id == mdb_id, best_practice.rule_id] = \
            best_practice.validator(dataset_path, report_folder_path, best_practice.file)