the user's handbook

• installation
• as a command line tool
  • options
• as a python library
  • let surplus do the heavy lifting
  • handle query parsing separately
  • start from a query object

installation

install surplus with pip, or pipx (recommended):

pipx install surplus

or directly from the repository using pip:

pip install git+https://github.com/markjoshwel/surplus.git@main

surplus is also a public domain dedicated single python file, so feel free to grab that and embed it into your own program as you see fit.

as a command line tool

surplus accepts a location query and converts it into iOS Shortcuts-like shareable text.

$ s+ 9R3J+R9 Singapore
surplus version 2024.0.0-beta
Thomson Plaza
301 Upper Thomson Road
Sin Ming, Bishan
574408
Central, Singapore

supported query forms:

• 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

• stdin pass - as the query to read input from standard input

options

usage: surplus [-h] [-d] [-v]
               [-c {pluscode,localcode,latlong,sharetext}]
               [-u USER_AGENT] [--show-user-agent] [-t]
               [query ...]

• query full-length Plus Code, shortened Plus Code/local code, latitude-longitude coordinate pair, string query, or - to read from stdin

• -h, --help show the command help and exit

• -d, --debug print latitude, longitude, and reverser response information to stderr

• -v, --version print version information to stderr and exit

• -c, --convert-to choose the output type. accepted values are pluscode, localcode, latlong, and sharetext. the default is sharetext

• -u, --user-agent set the user agent string used for the default geocoding service. by default, surplus generates a fingerprinted user agent so Nominatim can distinguish different surplus users

• --show-user-agent print the generated fingerprinted user agent and exit

• -t, --using-termux-location treat input as termux-location JSON and parse it accordingly

as a python library

surplus can also be imported as a Python library.

let surplus do the heavy lifting

from surplus import Behaviour, surplus

result = surplus("Ngee Ann Polytechnic, Singapore", Behaviour())
print(result.get())

example output:

Ngee Ann Polytechnic
535 Clementi Road
Bukit Timah
599489
Northwest, Singapore

handle query parsing separately

import surplus

behaviour = surplus.Behaviour("6PH58R3M+F8")
query = surplus.parse_query(behaviour)
result = surplus.surplus(query.get(), behaviour)

print(result.get())

start from a query object

import surplus

geocoding = surplus.SurplusDefaultGeocoding()
geocoding.update_geocoding_functions()

localcode = surplus.LocalCodeQuery(code="8R3M+F8", locality="Singapore")
pluscode_str = localcode.to_full_plus_code(geocoder=geocoding.geocoder).get()
pluscode = surplus.PlusCodeQuery(pluscode_str)
result = surplus.surplus(pluscode, surplus.Behaviour())

print(result.get())

notes:

• use a custom Behaviour object to change geocoding, reverse-geocoding, output streams, debug output, conversion type, and Termux-location parsing behaviour

• most surplus functions return a Result object. calling .get() is convenient, but it can raise the stored exception if the operation failed. check the result before calling .get() when you need safer error handling

• the abandoned 2024.0.0-beta refactor still uses the SHAREABLE_TEXT_LINE_*_KEYS dictionaries internally. a replacement system was planned, but did not land before the project was archived. see sharetext technical details for the line breakdown