{"id":24600766,"url":"https://github.com/mfdz/amarillo","last_synced_at":"2025-10-05T21:32:04.320Z","repository":{"id":40363535,"uuid":"475434344","full_name":"mfdz/amarillo","owner":"mfdz","description":"Aggregates and enhances carpooling-offers and publishes them as GTFS(-RT) ","archived":false,"fork":false,"pushed_at":"2025-01-22T14:34:36.000Z","size":336,"stargazers_count":9,"open_issues_count":13,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-22T15:32:11.750Z","etag":null,"topics":["carpooling","gtfs","gtfs-rt","python","ride-sharing"],"latest_commit_sha":null,"homepage":"https://amarillo.mfdz.de","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfdz.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}},"created_at":"2022-03-29T12:33:18.000Z","updated_at":"2025-01-22T14:34:40.000Z","dependencies_parsed_at":"2023-12-13T07:45:18.040Z","dependency_job_id":"30468c55-42b0-406e-b602-4caabbbd3236","html_url":"https://github.com/mfdz/amarillo","commit_stats":{"total_commits":269,"total_committers":7,"mean_commits":38.42857142857143,"dds":0.3568773234200744,"last_synced_commit":"5fd717121f47c8db9e46cdb104d38239897bd353"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfdz%2Famarillo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfdz%2Famarillo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfdz%2Famarillo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfdz%2Famarillo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfdz","download_url":"https://codeload.github.com/mfdz/amarillo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235448520,"owners_count":18991891,"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":["carpooling","gtfs","gtfs-rt","python","ride-sharing"],"created_at":"2025-01-24T14:01:28.590Z","updated_at":"2025-10-05T21:32:04.315Z","avatar_url":"https://github.com/mfdz.png","language":"Python","readme":"# Amarillo\n\n**CRUD for carpool offers**\n\nAn Amarillo is a [yellow-dressed person](https://oncubanews.com/canaldigital/galerias/por-el-camino/los-amarillos/) helping others to find a car pool in Cuba. \n\n## Setup\n\n- Python 3.12.9 with pip\n- python3-venv\n\nCreate a virtual environment `python3 -m venv venv`.\n\nActivate the environment and install the dependencies `pip install -r requirements.txt`.\n\nAmarillo consists of two services: \n\n* a web service, providing an api for carpool agencies to push carpool data to and for consumers to download the GTFS and GTFS-Realtime date generated from these, and\n* an enhancer service, which performs background processes like enhancing carpool offers or schedule-based GTFS and GTFS-RT generation.\n\nTo start the webservice, run `ADMIN_TOKEN=\u003cyour admin token\u003e uvicorn amarillo.main:app`. In development, you can add `--reload` to have uvicorn detect and reload code changes. \n\nTo start the enhancer service, run `python enhancer.py`.\n\n## Environment Variables\n\n- `env`\n- `ADMIN_TOKEN`\n\n## Security\n\nAll endpoints are protected by an API-Key in the HTTP header. \nThere is a special *admin* user. \nFor this user, the API-Key must be passed in as an environment variable when \nAmarillo is started.\n\nThe admin can create additional API-Keys in the `/agencyconf` endpoint. This \nendpoint is always available but not always shown in `/docs`, especially not\nwhen running in production. \nThe Swagger docs for `/agencyconf` can be seen on the MFDZ demo server. \n\nPermissions work this way\n- the admin is allowed to call all operations on all resources. Only the admin\n  can create new API-Keys by POSTing an `AgencyConf` JSON object to `/agencyconf`. \n- API-Keys for agencies are allowed to POST/PUT/GET/DELETE their own \n  resources and GET some public resources.  \n\n## Integrating new carpool agencies\n\nTo add a new carpool agency, you need to provide agency metadata, which will be used to generated the GTFS agency.txt and an `agencyconf`, which defines how the agency's carpool \ndata is synced and access options. \n\n### Agency Metadata\nTo provide agency metadata information, create a json config file `conf/agency/\u003cagency_id\u003e.json`and specify the following information:\n\n```json\n{\n  \"id\": \"mfdz\",\n  \"name\": \"MITFAHR|DE|ZENTRALE\",\n  \"url\": \"http://mfdz.de\",\n  \"timezone\": \"Europe/Berlin\",\n  \"lang\": \"de\",\n  \"email\": \"no-reply@mfdz.de\"\n}\n```\n\nNote: The value of `id` must match the filename's name (without suffix `.json`).\n\n### Agency configuration\n\nFor agency configuration, create a file `data/agencyconf/\u003cagency_id\u003e.json` and specify the following information:\n\n```json\n{\n  \"agency_id\": \"mfdz\", \n  \"api_key\": \"\u003ca secret api key, at least 20 chars\u003e\",\n  \"offers_download_url\": \"http://mfdz.de/carpools/\", // url providing an endpoint serving a json array of carpool offers according to Amarillo carpool schema \n  \"roles\": [\n    \"carpool_agency\", // if agencyconf has role carpool_agency, it may push carpool offers\n    \"consumer\" // if agencyconf has consumer role, it may download gtfs and gtfs-rt data\n  ],\n  \"add_dropoffs_and_pickups\": true, // if additional stops along the route should be added, default is true\n  \"replace_carpool_stops_by_closest_transit_stops\": true // if origin and destination should be snapped to closest stop, default is true.\n}\n```\n\nNote: The value of `agency_id` must match the filename's name (without suffix `.json`).\n\nNote: `add_dropoffs_and_pickups` and `replace_carpool_stops_by_closest_transit_stops` is currently not supported for carpool offers which provide a route geometry (path) instead of having it calculated by Amarillo. For such agencies, `add_dropoffs_and_pickups` and `replace_carpool_stops_by_closest_transit_stops` must be set to `false`.\n\n### Custom Importer\nIn case an agency does not provide an endpoint serving carpool offers in Amarillo schema, \na custom importer can be implemented and integrated.\n\nFor examples, see `amarillo/services/importing`.\n\nThey need to be added in `amarillo/services/sync.py`:\n\n```python\n    ...\n    async def sync(self, agency_id: str, offers_download_url = None):\n      ...  \n      elif agency_id == \"my-custom-agency\":\n        importer = MyCustomAgencyImporter(offers_download_url)\n      ...\n```\n\n## Development\n\n### GTFS-RT python bindings\n\nIn case you modify or update the proto-files in amarillo/proto, you'll need to regenerate the python bindings. First, create the python files:\n\n```sh\n$ cd amarillo/proto\n$ protoc --version\nlibprotoc 3.21.6\n$ protoc --proto_path=. --python_out=../services/gtfsrt gtfs-realtime.proto realtime_extension.proto\n$ sed 's/import gtfs_realtime_pb2/import amarillo.services.gtfsrt.gtfs_realtime_pb2/g' ../services/gtfsrt/realtime_extension_pb2.py | sponge ../services/gtfsrt/realtime_extension_pb2.py\n```\n\n## Testing\n\nIn the top directory, run `pytest amarillo/tests`.\n\n## Docker\n\nBased on [python:3.12-slim](https://hub.docker.com/_/python/)\n\n- build `docker build -t amarillo .`\n- run `docker run --rm --name amarillo -p 8000:80 -e MAX_WORKERS=\"1\" -e ADMIN_TOKEN=$ADMIN_TOKEN -e RIDE2GO_TOKEN=$RIDE2GO_TOKEN -e TZ=Europe/Berlin -v $(pwd)/data:/app/data amarillo`\n","funding_links":[],"categories":["Producing Data","Recently Updated"],"sub_categories":["GTFS","[Jan 22, 2025](/content/2025/01/22/README.md)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfdz%2Famarillo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfdz%2Famarillo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfdz%2Famarillo/lists"}