{"id":39664703,"url":"https://github.com/markjoshwel/surplus","last_synced_at":"2026-01-18T09:27:58.016Z","repository":{"id":172045957,"uuid":"648777663","full_name":"markjoshwel/surplus","owner":"markjoshwel","description":"Plus Code/latlong/query to iOS-Shortcuts-like shareable text","archived":false,"fork":false,"pushed_at":"2024-11-15T16:30:57.000Z","size":548,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"future","last_synced_at":"2024-11-15T17:31:53.389Z","etag":null,"topics":["openlocationcode","plus-code","pluscode","spow"],"latest_commit_sha":null,"homepage":"https://surplus.joshwel.co","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markjoshwel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","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},"funding":{"github":"markjoshwel","custom":"links.joshwel.co/donate"}},"created_at":"2023-06-02T19:39:50.000Z","updated_at":"2024-11-15T16:30:54.000Z","dependencies_parsed_at":"2024-06-13T00:56:46.035Z","dependency_job_id":"3c0bef7b-f854-4f13-8e35-2d118dae44da","html_url":"https://github.com/markjoshwel/surplus","commit_stats":null,"previous_names":["markjoshwel/surplus"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/markjoshwel/surplus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markjoshwel%2Fsurplus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markjoshwel%2Fsurplus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markjoshwel%2Fsurplus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markjoshwel%2Fsurplus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markjoshwel","download_url":"https://codeload.github.com/markjoshwel/surplus/tar.gz/refs/heads/future","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markjoshwel%2Fsurplus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["openlocationcode","plus-code","pluscode","spow"],"created_at":"2026-01-18T09:27:57.327Z","updated_at":"2026-01-18T09:27:58.002Z","avatar_url":"https://github.com/markjoshwel.png","language":"Python","readme":"# surplus\n\nsurplus (s+) is a Python script to convert [Google Maps Plus Codes](https://maps.google.com/pluscodes/)\nto iOS Shortcuts-like shareable text\n\n- [quickstart](#quickstart)\n- [documentation](https://surplus.joshwel.co)\n  - [the user's guide (command-line)](https://surplus.joshwel.co/using#as-a-command-line-tool)\n  - [the user's guide (library)](https://surplus.joshwel.co/using#as-a-library)\n  - [the developer's guide](https://surplus.joshwel.co/developing)\n      - [api reference](https://surplus.joshwel.co/developing)\n  - [the contributor's guide](https://surplus.joshwel.co/contributing)\n\nthis repository is also monorepo for the following sibling projects:\n\n- **surplus on wheels** (s+ow)  \n  a pure shell script to get your location using `termux-location`, process it through surplus, and\n  send it to messaging service or wherever, using \"bridges\"\n- **surplus on wheels: Whatsapp Bridge**\n- **surplus on wheels: Telegram Bridge**\n\n## quickstart\n\n\u003e [!TIP]  \n\u003e termux users can consider [surplus on wheels](https://surplus.joshwel.co/onwheels), a sibling\n\u003e project that allows you to run surplus regularly throughout the day and send it to someone on a\n\u003e messaging platform\n\n\u003e [!IMPORTANT]  \n\u003e python 3.11 or later is required due to a bug in earlier versions\n\u003e [(python/cpython#88089)](https://github.com/python/cpython/issues/88089)\n\ninstall surplus with pip, or [pipx](https://pipx.pypa.io/) (recommended):\n\n```text\npipx install surplus\n```\n\nthen, use the `surplus` command, or its `s+` shorthand:\n\n```text\n$ s+ 7RGX+GJ Singapore\nsurplus version 2024.0.0-beta\nSingapore Conference Hall\n7 Shenton Way\n068809\nCentral, Singapore\n```\n\nthe types of queries you can pass in are:\n\n- full-length Plus Codes  \n  `6PH58QMF+FX`\n- shortened Plus Codes / 'local codes'  \n  `8QMF+FX Singapore`\n- latitude and longitude coordinate pairs  \n  `1.3336875, 103.7749375`\n- string queries  \n  `Wisma Atria`\n\nor, alternatively pass in `-` to read from stdin\n\nmore documentation is available at \u003chttps://surplus.joshwel.co\u003e,\nor alternatively available locally in the [docs/](docs) folder\n\n## licences\n\n- [**surplus**](src/surplus)  \n  The Unlicence\n\n  surplus is free and unencumbered software released into the public domain. for more information,\n  please refer to the [UNLICENCE](src/surplus/UNLICENCE), \u003chttps://unlicense.org\u003e, or the python\n  module docstring\n\n  however, the dependencies surplus relies on are licenced under different, but still permissive\n  and open-source licences:\n\n    - [**geopy**](https://pypi.org/project/geopy/) — \n      Python Geocoding Toolbox  \n      MIT Licence\n\n        - [**geographiclib**](https://pypi.org/project/geographiclib/) — \n          The geodesic routines from GeographicLib  \n          MIT Licence\n\n    - [**pluscodes**](https://pypi.org/project/pluscodes/) — \n      Compute Plus Codes (Open Location Codes)  \n      Apache 2.0\n\n- [**surplus on wheels**](src/surplus-on-wheels)  \n  The Unlicence\n\n  surplus on wheels is free and unencumbered software released into the public domain. for more\n  information, please refer to [UNLICENCE](src/surplus-on-wheels/UNLICENCE) or\n  \u003chttp://unlicense.org/\u003e\n\n- [**surplus on wheels: WhatsApp Bridge**](src/spow-whatsapp-bridge)  \n  Mozilla Public Licence 2.0\n\n  the s+ow WhatsApp Bridge is based off mdtest code from the\n  [whatsmeow](https://github.com/tulir/whatsmeow) project, which is licenced under the Mozilla\n  Public Licence 2.0. for more information, see [LICENCE](src/spow-whatsapp-bridge/LICENCE), or\n  \u003chttps://www.mozilla.org/en-US/MPL/2.0/\u003e\n\n  the direct dependencies s+ow-whatsapp-bridge relies on are licenced under different, but still\n  permissive and open-source licences:\n\n    - [**whatsmeow**](https://github.com/tulir/whatsmeow) — \n      Go library for the WhatsApp web multidevice API  \n      Mozilla Public Licence 2.0\n\n- [**surplus on wheels: Telegram Bridge**](src/spow-telegram-bridge)  \n  The Unlicence\n\n  the s+ow Telegram Bridge is free and unencumbered software released into the public domain. for\n  more information, please refer to the [UNLICENCE](src/spow-telegram-bridge/UNLICENCE),\n  \u003chttps://unlicense.org\u003e, or the python module docstring\n\n  however, the direct dependencies surplus relies on are licenced under different, but still\n  permissive and open-source licences:\n\n    - [**Telethon**](https://pypi.org/project/Telethon/) — \n      Pure Python 3 MTProto API Telegram client library, for bots too!  \n      MIT Licence\n\n- [**surplus documentation**](docs)  \n  CC0 1.0 Universal\n\n  the textual contents of surplus documentation by [Mark Joshwel](https://joshwel.co) is marked\n  with [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).\n  to view a copy of this license, visit \u003chttps://creativecommons.org/publicdomain/zero/1.0/\u003e\n\n  the fonts the documentation website relies on are licenced under different, but still\n  permissive and open-source licences:\n\n    - [**Geist and Geist Mono**](https://github.com/vercel/geist-font)  \n      SIL Open Font Licence 1.1 ([file](docs/fonts/LICENSE.txt))\n    \n  the direct software dependencies the documentation are also licenced under different, but still\n  permissive and open-source licences:\n\n    - [**mkdocs-material**](https://squidfunk.github.io/mkdocs-material/) — \n      Documentation that simply works  \n      MIT Licence\n\n    - [**mkdocs**](https://www.mkdocs.org/) — \n      Project documentation with Markdown  \n      BSD-2-Clause Licence\n","funding_links":["https://github.com/sponsors/markjoshwel","links.joshwel.co/donate"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkjoshwel%2Fsurplus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkjoshwel%2Fsurplus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkjoshwel%2Fsurplus/lists"}