surplus (s+)
surplus (s+) is a Python script to convert Google Maps Plus Codes to iOS Shortcuts-like shareable text
$ s+ 7RGX+GJ Singapore
surplus version 2024.0.0
Singapore Conference Hall
7 Shenton Way
068809
Central, Singapore
- user's handbook
- sharetext technical details
- surplus on wheels
- api reference
- contributing and reporting incorrect output
- changelog
- licences
achtung
surplus started from me and my secondary school friends playing with iOS Automations, sending location as text to our group chat
i wanted the same thing on Android, taking Plus Codes from Google Maps, reverse-geocode them, and produce location text shaped like iOS Shortcuts output. then i supported coordinates, then search queries
eventually, i found out about termux-location in Termux:API and then made surplus on wheels
(s+ow) to run a cron job and pipe it to surplus; alongside bridges for WhatsApp and Telegram
core conversion still works and has since 2023, but sharetext formatting has drifted over time because Nominatim/OpenStreetMap data changes
the longer i maintained it, the messier the interesting part became: not the CLI itself, but wrangling with Nominatim key ordering, regional formats, and the weird ways location text changed when one of us was overseas. the novelty wore off, and i had no reason to maintain surplus
so this site is both documentation and archive for a fun little set of tools for me to share my location in plaintext with my friends! i now deeply respect anyone handling worldwide geocoding and addressing