This package obtains your current location by obtaining the MAC addresses of nearby wifi access points and then submitting that list to third-party geolocation APIs. Those geolocation services use the known locations of the wifi access points and the relative strength of each signal to triangulate your latitude and longitude. The main entry point is: - `geolocation-update-position' which calls `geolocation-get-position' on a regular interval, and sets `geolocation-location' with the result. The `geolocation-update-hook' functions are called after each update. Customize the hook functions if you want to invoke functions based on your position, and customize the `geolocation-update-interval' with the time granularity you need, keeping in mind the underlying positioning APIs may have rate limits and/or costs associated with high frequency querying. The variable `geolocation-location' will contain nil or an alist: - `latitude' - latitude of the current position - `longitude' - longitude of the current position - `accuracy' - an error radius, in meters - `timestamp' - timestamp via `float-time' Other potentially useful functions include: - `geolocation-get-position' which retrieves your estimated position once and invokes a callback with the position data. The callback receives an alist with the same format as `geolocation-location.' - `geolocation-scan-wifi' which scans asynchronously for nearby wifi access points using available system utilities, and invokes a callback with the wifi data. The callback receives a list of alists containing: - `bssid' - mac address that uniquely identifies the AP - `signal' - relative signal strength, or RSSI - `channel' - transmission channel - `geolocation-update-calendar' stores the latest position in `calendar-latitude' and `calendar-longitude'. This function works as a `geolocation-update-hook'. At present, wifi scanning is supported on Mac OSX and Windows. Linux support is planned but not yet implemented. You have a choice of third party services to use for the positioning: - Google Maps Geolocation API https://developers.google.com/maps/documentation/geolocation/intro - HERE Technologies Positioning API https://developer.here.com/develop/rest-apis - Unwired Labs Location API https://unwiredlabs.com/home This package offers a set of customizable variables you can use to select which service is used, declare your API access token, choose the nearest API endpoint, and so on. Those settings can be found in `M-x customize`, then browse for "Environment", then "hardware", and then "Geolocation". By default, access tokens are expected to be accessed via the built-in `auth-source` package. You can configure any backend, as this package only requires the token to be searchable via `auth-source-pick-first-password`. Rate Limits and Costs: Each of these services requires you to create your own account, and potentially provide billing information as well. You will be agreeing to the vendor's end-user agreements including such things as acceptable usage policies and privacy terms, when you create your account. Care has been taken to choose services that include either a free tier, or equivalently, an allowance of a certain amount of usage per day or per month. It's your responsibility to set up your account with those services, obtain and protect your token, and manage your usage of those APIs because there can be associated costs if your usage exceeds the usage terms of the subscription or plan you choose. WARNING: THIS PACKAGE COLLECTS INFORMATION THAT IMPLIES YOUR PHYSICAL LOCATION. THAT DATA WILL BE SENT TO THIRD-PARTY GEOLOCATION SERVICES WHICH CAN PINPOINT YOUR LOCATION TYPICALLY WITHIN 100 METERS OR LESS. WHILE THIS PACKAGE DOES NOT ITSELF STORE YOUR LOCATION, WE CANNOT GUARANTEE WHAT A GIVEN THIRD-PARTY SERVICE MAY DO WITH THE DATA IT RECEIVES IN THESE API TRANSACTIONS. RATHER, YOU UNDERSTAND AND AGREE TO THE PRIVACY AGREEMENTS AND END USER AGREEMENTS OF EACH OF THE INDIVIDUAL GEOLOCATION APIS YOU USE.