Skip to content

markjoshwel/surplus

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

surplus

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

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:

    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