{"id":28120637,"url":"https://github.com/mobilitydata/mobility-feed-api","last_synced_at":"2026-03-11T20:01:02.406Z","repository":{"id":174782163,"uuid":"646983841","full_name":"MobilityData/mobility-feed-api","owner":"MobilityData","description":"This repository contains the source code for the Mobility Database website and API. It powers the public platform where you can explore, share, and access GTFS and GBFS mobility data from around the world.","archived":false,"fork":false,"pushed_at":"2026-02-25T19:15:19.000Z","size":14412,"stargazers_count":28,"open_issues_count":251,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-05T07:37:03.559Z","etag":null,"topics":["open-source"],"latest_commit_sha":null,"homepage":"https://mobilitydatabase.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MobilityData.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-29T19:54:05.000Z","updated_at":"2026-02-25T19:15:50.000Z","dependencies_parsed_at":"2026-01-07T23:00:16.036Z","dependency_job_id":null,"html_url":"https://github.com/MobilityData/mobility-feed-api","commit_stats":{"total_commits":460,"total_committers":15,"mean_commits":"30.666666666666668","dds":0.3326086956521739,"last_synced_commit":"5c511ea65f98f9864108c780f36d4f2f24bb122f"},"previous_names":["mobilitydata/mobility-feed-api"],"tags_count":80,"template":false,"template_full_name":null,"purl":"pkg:github/MobilityData/mobility-feed-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobilityData%2Fmobility-feed-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobilityData%2Fmobility-feed-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobilityData%2Fmobility-feed-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobilityData%2Fmobility-feed-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MobilityData","download_url":"https://codeload.github.com/MobilityData/mobility-feed-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobilityData%2Fmobility-feed-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30398155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["open-source"],"created_at":"2025-05-14T07:41:25.419Z","updated_at":"2026-03-11T20:01:02.394Z","avatar_url":"https://github.com/MobilityData.png","language":"Python","readme":"# Mobility Feed API\n\n![Deploy Feeds API - QA](https://github.com/MobilityData/mobility-feed-api/workflows/Deploy%20Feeds%20API%20-%20QA/badge.svg?branch=main)\n![Deploy Web App - QA](https://github.com/MobilityData/mobility-feed-api/actions/workflows/web-qa.yml/badge.svg?branch=main)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nThe Mobility Feed API service a list of open mobility data sources from across the world. This repository is the effort the initial effort to convert the current [The Mobility Database Catalogs](https://github.com/MobilityData/mobility-database-catalogs) in an API service. [More info about the Mobility Database can be found on the website](https://mobilitydatabase.org/).\n\nThe contents of the database is available in csv format [here](https://files.mobilitydatabase.org/feeds_v2.csv). This includes all feeds, including ones we automatically import from sources outside the catalogs repo.\n\nThe schema for the csv file is available [here](docs/SpreadsheetSchemaV2.md).\n\n## GBFS Feeds\nThe repository also includes GBFS feeds extracted from [`systems.csv`](https://github.com/MobilityData/gbfs/blob/master/systems.csv) in the [GBFS repository](https://github.com/MobilityData/gbfs). However, these feeds are not being served yet. The supported versions of these feeds are specified in the file [api/src/scripts/gbfs_utils/gbfs_versions.py](https://github.com/MobilityData/mobility-feed-api/blob/main/api/src/scripts/gbfs_utils/gbfs_versions.py).\n\n# Authentication\n\nTo access the Mobility Feed API, users need to authenticate using an access token. Here is the step-by-step process to obtain and use an access token:\n\n## Registering for an Account\n\n1. **Sign up** at [mobilitydatabase.org](https://mobilitydatabase.org) to create an account.\n2. Once registered, you can view your **refresh token** on the Account Details screen. This token is used to generate your access token.\n\n## Generating an Access Token\n\nYou can generate an access token either via the UI on the website or using a `curl` command:\n\n- **Via UI**: After logging in, navigate to the account page to generate or obtain your access token.\n- **Via Command Line**:\n  ```bash\n  curl --location 'https://api.mobilitydatabase.org/v1/tokens' \\\n  --header 'Content-Type: application/json' \\\n  --data '{ \"refresh_token\": \"[Your Refresh Token]\" }'\n  Replace `[Your Refresh Token]` with the refresh token obtained after registration.\n  ```\n\n## Using the Access Token\n\nOnce you have the access token, you can use it to make authenticated requests to the API.\nFor Testing Access:\n\n```bash\ncurl --location 'https://api.mobilitydatabase.org/v1/metadata' \\\n--header 'Accept: application/json' \\\n--header 'Authorization: Bearer [Your Access Token]'\n```\n\nReplace `[Your Access Token]` with your actual access token.\n\n### Via Swagger UI\n\nYou can also use the [Swagger UI](https://mobilitydata.github.io/mobility-feed-api/SwaggerUI/index.html) to make requests. Input your access token in the required field in the Swagger interface.\n\n## Refreshing the Access Token\n\nAccess tokens are subject to expiration. Use your refresh token to generate a new access token when necessary.\n\n# Local development\n\nFolder `api` contains source code of the API implementation. This repository relies on [openapi-generator](https://openapi-generator.tech/) for spec-first development with [fastapi](https://openapi-generator.tech/docs/generators/python-fastapi) as the server stub generator. Generated files are placed in `src\\feeds_gen`; this folder is ignored in git as it should not be modified. API's endpoint classes and methods are located in `src\\feeds\\impl`.\n\n## Requirements.\n\nThe tested and recommended with the following versions:\n- Python: `~=3.11`\n- Docker: `\u003e=20.10`\n\n### External dependencies\n - docker\n - docker-compose\n - wget\n - Postgresql\n - sed\n\n## Installation \u0026 Usage\n\n- As a one-time step, download the `openapi-generator-cli.sh` script using:\n\n```bash\nscripts/setup-openapi-generator.sh\n```\n\n- Install dependencies\n\n```bash\ncd api\npip3 install -r requirements.txt\npip3 install -r requirements_dev.txt\n```\n\n- Generates an instance of the database locally using docker-compose\n\n```bash\ndocker-compose --env-file ./config/.env.local  up -d --force-recreate\n```\n\n- Generates the api and database stubs on the first run and every time the schema changes\n\n```bash\nscripts/api-gen.sh\nscripts/db-gen.sh\n```\n\nIn case you modify the database schema, you can run\n`docker-compose --env-file ./config/.env.local  up schemaspy -d --force-recreate` which will update your local instance of the database and the related schema documentation located in `docs/schemapy-dev/index.html`.\n\n- Reset the local database and apply liquibase changes(Only on schema changes)\nThis command is very useful when switching branches that potentially have different DB schema definitions.\n**All the data within the database will be lost**\n\n```bash\n./scripts/populate-db.sh \u003cpath to local sources.csv\u003e\n```\n\n- Reset the local database and populate it with the catalog content`(Optional)`\n  - Note: the wget command has to be available.\n```bash\n./scripts/docker-localdb-rebuild-data.sh --populate-db\n```\nDatasets are not part of the catalog. If you need to test or debug a feature that requires dataset entities use the following command:\n```bash\n./scripts/docker-localdb-rebuild-data.sh --populate-db --populate-test-data\n```\n\n\n- Run local API\n\n```bash\nscripts/api-start.sh\n```\n\n## Linter\n\nThis repository uses Flak8 and Black for code styling\n\nTo run linter checks:\n\n```bash\nscripts/lint-tests.sh\n```\n\nYou can also use the pre-commit installed through [requirements_dev.txt](api%2Frequirements_dev.txt) with\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\n## Local swagger documentation\n\nTo have access to the API's produced swagger documentation:\n\n```bash\nscripts/api-start.sh\n```\n\nand open your browser at `http://localhost:8080/docs/` to see the docs.\n\n## IDE Python modules\n\nIf your Python's IDE is not able to resolve the python module; make sure the api/src folder is marked as `source` directory.\n\n## Tests\n\nTo run the all tests:\n\n```bash\nscripts/api-tests.sh\n```\n\nTo run a single test file:\n\n```bash\nscripts/api-tests.sh \u003cmy_test_filename\u003e.py\n```\n\nNote: the tests rely on having an empty local test DB instance. If you have data in your local test DB, you can run the following command to reset the DB before running the tests\n```bash\n./scripts/docker-localdb-rebuild-data.sh --use-test-db\n```\n\n\n## Running with Docker\n\nBefore starting the docker container make sure the OpenApi generated files are present by running:\n\n```bash\nscripts/api-gen.sh\n```\n\nTo run the server on a Docker container, please execute the following from the root directory:\n\n```bash\n(cd api \u0026\u0026 docker-compose up --build)\n```\n\n## API error responses\n\nThe API HTTP error responses follow the FastAPI structure. Example:\n\n```\n{\n  \"details\": \"The error message\"\n}\n```\n\nTo simplify and standardize HTTP error responses use the helpers function located in [api/src/feeds/impl/error_handling.py](api/src/feeds/impl/error_handling.py). Also keep the error messages as Finals of the mentioned file, this will make it easier to locate and reuse error messages.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobilitydata%2Fmobility-feed-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmobilitydata%2Fmobility-feed-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobilitydata%2Fmobility-feed-api/lists"}