docs » hs.location

Determine the machine's location and useful information about that location

This module provides functions for getting current location information and tracking location changes. It expands on the earlier version of the module by adding the ability to create independant locationObjects which can enable/disable location tracking independant of other uses of Location Services by Hammerspoon, adds region monitoring for exit and entry, and adds the retrieval of geocoding information through the hs.location.geocoder submodule.

This module is backwards compatible with its predecessor with the following changes:

• hs.location.get - no longer requires that you invoke hs.location.start before using this function. The information returned will be the last cached value, which is updated internally whenever additional WiFi networks are detected or lost (not necessarily joined). When update tracking is enabled with the hs.location.start function, calculations based upon the RSSI of all currently seen networks are preformed more often to provide a more precise fix, but it's still based on the WiFi networks near you. In many cases, the value retrieved when the WiFi state is changed should be sufficiently accurate.
• hs.location.servicesEnabled - replaces hs.location.services_enabled. While the earlier function is included for backwards compatibility, it will display a deprecation warning to the console the first time it is invoked and may go away completely in the future.

The following labels are used to describe tables which are used by functions and methods as parameters or return values in this module and in hs.location.geocoder. These tables are described as follows:

• locationTable - a table specifying location coordinates containing one or more of the following key-value pairs:

  • latitude - a number specifying the latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator. When not specified in a table being used as an argument, this defaults to 0.0.
  • longitude - a number specifying the longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian. When not specified in a table being used as an argument, this defaults to 0.0.
  • altitude - a number indicating altitude above (positive) or below (negative) sea-level. When not specified in a table being used as an argument, this defaults to 0.0.
  • horizontalAccuracy - a number specifying the radius of uncertainty for the location, measured in meters. If negative, the latitude and longitude keys are invalid and should not be trusted. When not specified in a table being used as an argument, this defaults to 0.0.
  • verticalAccuracy - a number specifying the accuracy of the altitude value in meters. If negative, the altitude key is invalid and should not be trusted. When not specified in a table being used as an argument, this defaults to -1.0.
  • course - a number specifying the direction in which the device is traveling. If this value is negative, then the value is invalid and should not be trusted. On current Macintosh models, this will almost always be a negative number. When not specified in a table being used as an argument, this defaults to -1.0.
  • speed - a number specifying the instantaneous speed of the device in meters per second. If this value is negative, then the value is invalid and should not be trusted. On current Macintosh models, this will almost always be a negative number. When not specified in a table being used as an argument, this defaults to -1.0.
  • timestamp - a number specifying the time at which this location was determined. This number is the number of seconds since January 1, 1970 at midnight, GMT, and is a floating point number, so you should use math.floor on this number before using it as an argument to Lua's os.date function. When not specified in a table being used as an argument, this defaults to the current time.

• regionTable - a table specifying a circular region containing one or more of the following key-value pairs:

  • identifier - a string for use in identifying the region. When not specified in a table being used as an argument, a new value is generated with hs.host.uuid.
  • latitude - a number specifying the latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator. When not specified in a table being used as an argument, this defaults to 0.0.
  • longitude - a number specifying the latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator. When not specified in a table being used as an argument, this defaults to 0.0.
  • radius - a number specifying the radius (measured in meters) that defines the region’s outer boundary. When not specified in a table being used as an argument, this defaults to 0.0.
  • notifyOnEntry - a boolean specifying whether or not a callback with the "didEnterRegion" message should be generated when the machine enters the region. When not specified in a table being used as an argument, this defaults to true.
  • notifyOnExit - a boolean specifying whether or not a callback with the "didExitRegion" message should be generated when the machine exits the region. When not specified in a table being used as an argument, this defaults to true.