{"id":16691107,"url":"https://github.com/siarheifedartsou/mama","last_synced_at":"2025-07-14T09:12:09.342Z","repository":{"id":146320594,"uuid":"583942207","full_name":"SiarheiFedartsou/mama","owner":"SiarheiFedartsou","description":"Realtime map matching with gRPC-based API","archived":false,"fork":false,"pushed_at":"2023-03-31T15:01:33.000Z","size":755,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-15T16:42:08.292Z","etag":null,"topics":["backend","cpp","grpc","map","map-matching","maps","openstreetmap","osm"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SiarheiFedartsou.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-12-31T15:08:20.000Z","updated_at":"2025-05-03T14:51:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"eced6f53-a376-4271-bdd2-b249eee63f70","html_url":"https://github.com/SiarheiFedartsou/mama","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SiarheiFedartsou/mama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiarheiFedartsou%2Fmama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiarheiFedartsou%2Fmama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiarheiFedartsou%2Fmama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiarheiFedartsou%2Fmama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SiarheiFedartsou","download_url":"https://codeload.github.com/SiarheiFedartsou/mama/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiarheiFedartsou%2Fmama/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265266663,"owners_count":23737279,"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":["backend","cpp","grpc","map","map-matching","maps","openstreetmap","osm"],"created_at":"2024-10-12T16:06:50.024Z","updated_at":"2025-07-14T09:12:09.326Z","avatar_url":"https://github.com/SiarheiFedartsou.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaMa \n[![CI](https://github.com/SiarheiFedartsou/mama/actions/workflows/ci.yml/badge.svg)](https://github.com/SiarheiFedartsou/mama/actions/workflows/ci.yml)\n\n\nMaMa (short for Map Matcher) is a library that lets you perform real-time map matching of locations coming from multiple clients as part of distributed system (but in its core it is just a library which can easily be used locally). Main target of MaMa is blazingly fast performance.\n\n⚠️ Warning: This project is currently in its early stage of development and may contain bugs, incomplete features, and other issues. Please use it at your own risk and feel free to report any problems you encounter.\n🌟 If you find this project helpful or interesting, please consider giving it a star! It helps to boost the project's visibility and encourages us to keep improving it. Thank you! 🙏\n\n##  Quick start \u0026 Demo \n\nHere is example how one can configure and run `mama` map matching service for Berlin:\n```\nmkdir tiles\ncd tiles\n# download OSM data\nwget http://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf\n# generate mama tiles\ndocker run -t -v $(pwd):/tiles ghcr.io/siarheifedartsou/mama:main tilegen /tiles/berlin-latest.osm.pbf /tiles\n# run mama-server\ndocker run -t -p 50051:50051 -v $(pwd):/tiles ghcr.io/siarheifedartsou/mama:main mama_server /tiles \n```\n\nThis service exposes API via [gRPC](https://grpc.io/), so you have to use gRPC client to access it(see [mama.proto](https://github.com/SiarheiFedartsou/mama/blob/main/server/mama.proto) for service definition). For test purposes it can be done with [`grpcurl`](https://github.com/fullstorydev/grpcurl):\n```\ndocker run --add-host host.docker.internal:host-gateway fullstorydev/grpcurl \\\n  -plaintext \\\n  -d '{\"entries\": [{\"location\": {\"latitude\": 52.517037, \"longitude\": 13.388860, \"timestamp\": \"2023-01-01T00:00:00Z\"}}]}' \\\n  host.docker.internal:50051 \\\n  mama.server.api.MamaService.Match\n```\nIt should output something like:\n```\n{\n  \"entries\": [\n    {\n      \"location\": {\n        \"timestamp\": \"2023-01-01T00:00:00Z\",\n        \"latitude\": 52.51703335973838,\n        \"longitude\": 13.38879800553748,\n        \"bearing\": 354.47464844888776\n      },\n      \"state\": \"ChYKDwoICMfC+ggQsk4VYb4bPxXuZgi/ChYKDwoICMfC+ggQ6U8V5TLCPhXuZgi/ChYKDwoICMfC+ggQsk4V/xUHPxVdNkK/ChYKDwoICMfC+ggQ6U8VqYPrPhVdNkK/ChYKDwoICMfC+ggQojAVfiZuPxXDgaDAChYKDwoICMfC+ggQ60MVwmd9PxWFtLDAChEKCgoICMfC+ggQ508VhbSwwAoRCgoKCAjHwvoIEOhPFYW0sMAKFgoPCggIx8L6CBCiMBUm40c/FSLD48AKFgoPCggIx8L6CBCiMBWosi0/FSi1L8EKFgoPCggIx8L6CBDoTxXF60Q+FV6MQMEKFgoPCggIx8L6CBCxThVt/oM9FUrOSMEKFgoPCggIx8L6CBCQQRWYL38/FSnjVcEKFgoPCggIx8L6CBCuThWX9H4/FSnjVcEKEQoKCggIx8L6CBCwThUp41XBChYKDwoICMfC+ggQsU4V+4wXPhX5yV7BChYKDwoICMfC+ggQ60MVrQc9PxVh8pDBChYKDwoICMfC+ggQ508VKcCAPhVh8pDBEhoKBgiAmsOdBhE26bZELkJKQBnzcW2oGMcqQBolCgYIgJrDnQYROIItJi5CSkAZJxE9iBDHKkAiCQkf0fgomCd2QA==\"\n    }\n  ]\n}\n```\nNote `state` field, it encodes map matching state for particular vehicle. You can pass this state field in subsequent requests to take advantage of the knowledge of past vehicle locations:\n```\ndocker run --add-host host.docker.internal:host-gateway fullstorydev/grpcurl \\\n  -plaintext \\\n  -d '{\"entries\": [{\"state\": \"ChYKDwoICMfC+ggQsk4VYb4bPxXuZgi/ChYKDwoICMfC+ggQ6U8V5TLCPhXuZgi/ChYKDwoICMfC+ggQsk4V/xUHPxVdNkK/ChYKDwoICMfC+ggQ6U8VqYPrPhVdNkK/ChYKDwoICMfC+ggQojAVfiZuPxXDgaDAChYKDwoICMfC+ggQ60MVwmd9PxWFtLDAChEKCgoICMfC+ggQ508VhbSwwAoRCgoKCAjHwvoIEOhPFYW0sMAKFgoPCggIx8L6CBCiMBUm40c/FSLD48AKFgoPCggIx8L6CBCiMBWosi0/FSi1L8EKFgoPCggIx8L6CBDoTxXF60Q+FV6MQMEKFgoPCggIx8L6CBCxThVt/oM9FUrOSMEKFgoPCggIx8L6CBCQQRWYL38/FSnjVcEKFgoPCggIx8L6CBCuThWX9H4/FSnjVcEKEQoKCggIx8L6CBCwThUp41XBChYKDwoICMfC+ggQsU4V+4wXPhX5yV7BChYKDwoICMfC+ggQ60MVrQc9PxVh8pDBChYKDwoICMfC+ggQ508VKcCAPhVh8pDBEhoKBgiAmsOdBhE26bZELkJKQBnzcW2oGMcqQBolCgYIgJrDnQYROIItJi5CSkAZJxE9iBDHKkAiCQkf0fgomCd2QA==\", \"location\": {\"latitude\": 52.517301, \"longitude\": 13.38884, \"timestamp\": \"2023-01-01T00:00:03Z\"}}]}' \\\n  host.docker.internal:50051 \\\n  mama.server.api.MamaService.Match\n```\n\nSee our [demo](./demo) for example of real life usage.\n\n## How it works\n\n#### `tilegen`\n\nIn order to work `mama` preprocess OSM data to more convenient representation. `tilegen` is a tool used for that.\n\n`tilegen` takes `.osm.pbf` as input and slices it to tiles. Tile scheme corresponds to level 11 of [S2Geometry](https://s2geometry.io/), i.e. has approximately 20 km^2 in area:\n\n\u003cimg width=\"700\" alt=\"Screenshot 2023-01-24 at 17 55 55\" src=\"https://user-images.githubusercontent.com/266271/214357432-6d7ec7af-9c13-418f-8d11-0ed338056dc9.png\"\u003e\n\nEach tile stores metadata about road graph edges accessible by cars in particular area and [S2 index](https://s2geometry.io/devguide/s2shapeindex.html) which allows to effectively find projections on road graph. \n\n`tilegen` also optionally precomputes shortest paths used in map matching algorithm, which significantly boosts runtime performance. \n\n#### `libmama`\n`libmama` is C++ library implementing core features of `mama`. [`mama_server`](https://github.com/SiarheiFedartsou/mama/blob/cb15123ca81d6712f2cccff06cc842a1b6e2b9ce/server/mama_server.cc#L57) can be a good example of how it should be used. \n\n#### `mama_server`\n`mama_server` is gRPC service which wraps `libmama` and provides map matching capabilities to external clients. This service doesn't store any state and it is responsibility of clients to store map matching states(see [demo](./demo) for example how Redis can be used for that purpose). \n\n\n## Credits\n- Map matching algorithm itself is mainly inspired by \"classic\" Microsoft paper [`Hidden Markov Map Matching Through Noise and Sparseness`](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/12/map-matching-ACM-GIS-camera-ready.pdf).\n- Shortest paths precomputation is inspired by [`Fast map matching, an algorithm integrating hidden\nMarkov model with precomputation`](https://people.kth.se/~cyang/bib/fmm.pdf) paper.\n\n## License\nMaMa uses [MIT license](https://github.com/SiarheiFedartsou/mama/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiarheifedartsou%2Fmama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiarheifedartsou%2Fmama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiarheifedartsou%2Fmama/lists"}