surplus

surplus (s+) is a Python script to convert Google Maps Plus Codes to iOS Shortcuts-like shareable text

• quickstart
• documentation
  • the user's guide (command-line)
  • the user's guide (library)
  • the developer's guide
    • api reference
  • the contributor's guide

this repository is also monorepo for the following sibling projects:

• surplus on wheels (s+ow)
  a pure shell script to get your location using termux-location, process it through surplus, and send it to messaging service or wherever, using "bridges"
• surplus on wheels: Whatsapp Bridge
• surplus on wheels: Telegram Bridge

quickstart

Tip

termux users can consider surplus on wheels, a sibling project that allows you to run surplus regularly throughout the day and send it to someone on a messaging platform

Important

python 3.11 or later is required due to a bug in earlier versions (python/cpython#88089)

install surplus with pip, or pipx (recommended):

pipx install surplus

then, use the surplus command, or its s+ shorthand:

$ s+ 7RGX+GJ Singapore
surplus version 2024.0.0-beta
Singapore Conference Hall
7 Shenton Way
068809
Central, Singapore

the types of queries you can pass in are:

• full-length Plus Codes
  6PH58QMF+FX
• shortened Plus Codes / 'local codes'
  8QMF+FX Singapore
• latitude and longitude coordinate pairs
  1.3336875, 103.7749375
• string queries
  Wisma Atria

or, alternatively pass in - to read from stdin

more documentation is available at https://surplus.joshwel.co, or alternatively available locally in the docs/ folder

licences

• surplus
  The Unlicence

  surplus is free and unencumbered software released into the public domain. for more information, please refer to the UNLICENCE, https://unlicense.org, or the python module docstring

  however, the dependencies surplus relies on are licenced under different, but still permissive and open-source licences:

  • geopy — Python Geocoding Toolbox
    MIT Licence

    • geographiclib — The geodesic routines from GeographicLib
      MIT Licence

  • pluscodes — Compute Plus Codes (Open Location Codes)
    Apache 2.0

• surplus on wheels
  The Unlicence

  surplus on wheels is free and unencumbered software released into the public domain. for more information, please refer to UNLICENCE or http://unlicense.org/

• surplus on wheels: WhatsApp Bridge
  Mozilla Public Licence 2.0

  the s+ow WhatsApp Bridge is based off mdtest code from the whatsmeow project, which is licenced under the Mozilla Public Licence 2.0. for more information, see LICENCE, or https://www.mozilla.org/en-US/MPL/2.0/

  the direct dependencies s+ow-whatsapp-bridge relies on are licenced under different, but still permissive and open-source licences:

  • whatsmeow — Go library for the WhatsApp web multidevice API
    Mozilla Public Licence 2.0

• surplus on wheels: Telegram Bridge
  The Unlicence

  the s+ow Telegram Bridge is free and unencumbered software released into the public domain. for more information, please refer to the UNLICENCE, https://unlicense.org, or the python module docstring

  however, the direct dependencies surplus relies on are licenced under different, but still permissive and open-source licences:

  • Telethon — Pure Python 3 MTProto API Telegram client library, for bots too!
    MIT Licence

• surplus documentation
  CC0 1.0 Universal

  the textual contents of surplus documentation by Mark Joshwel is marked with CC0 1.0 Universal. to view a copy of this license, visit https://creativecommons.org/publicdomain/zero/1.0/

  the fonts the documentation website relies on are licenced under different, but still permissive and open-source licences:

  • Geist and Geist Mono
    SIL Open Font Licence 1.1 (file)

  the direct software dependencies the documentation are also licenced under different, but still permissive and open-source licences:

  • mkdocs-material — Documentation that simply works
    MIT Licence

  • mkdocs — Project documentation with Markdown
    BSD-2-Clause Licence