hs.location.geocoder
submodule.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.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.hs.location.authorizationStatus() -> string
hs.location.distance(from, to) -> meters
from
- A locationTable as described in the module headerto
- A locationTable as described in the module headerfrom
and to
in meters. The measurement is made by tracing a line that follows an idealised curvature of the earthhs.location.dstOffset() -> number
hs.location.get() -> locationTable or nil
hs.location.register(tag, fn[, distance])
tag
- A string containing a unique tag, used to identify the callback laterfn
- A function to be called when the system location is updated. The function should expect a single argument which will be a locationTable as described in the module header.distance
- An optional number containing the minimum distance in meters that the system should have moved, before calling the callback. Defaults to 0hs.location.servicesEnabled() -> bool
hs.location.start() -> boolean
hs.location.stop()
hs.location.sunrise(latitude, longitude, offset[, date]) -> number or string
latitude
- A number containing a latitudelongitude
- A number containing a longitudeoffset
- A number containing the offset from UTC (in hours) for the given latitude/longitude.date
- An optional table containing date information (equivalent to the output of os.date("*t")
). Defaults to the current dateos.date("*t", returnvalue)
hs.location.sunrise(locationTable, offset[, date])
.hs.location.sunset(latitude, longitude, offset[, date]) -> number or string
latitude
- A number containing a latitudelongitude
- A number containing a longitudeoffset
- A number containing the offset from UTC (in hours) for the given latitude/longitude.date
- An optional table containing date information (equivalent to the output of os.date("*t")
). Defaults to the current dateos.date("*t", returnvalue)
hs.location.sunset(locationTable, offset[, date])
.hs.location.unregister(tag)
tag
- A string containing the unique tag a callback was registered withhs.location.new() -> locationObject
hs.location:addMonitoredRegion(regionTable) -> locationObject | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Adds a region to be monitored by Location Services | | Parameters |regionTable
- a region table as described in the module headeridentifier
key is not provided, a new UUID string is generated and used as the identifier.identifier
key matches an already monitored region, this region will replace the existing one.hs.location:callback(fn) -> locationObject
notifyOnEntry
field set to true specified with the hs.location:addMonitoredRegion method. The third argument will be the regionTable for the region entered.notifyOnExit
field set to true specified with the hs.location:addMonitoredRegion method. The third argument will be the regionTable for the region exited.hs.location:currentRegion() -> identifier | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the string identifier for the current region | | Parameters |hs.location:distanceFrom(locationTable) -> distance | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Enable callbacks for location changes/refinements for this locationObject | | Parameters |hs.location:location() -> locationTable | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the current location | | Parameters |hs.location:monitoredRegions() -> table | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a table containing the regionTables for the regions currently being monitored for this locationObject | | Parameters |hs.location:removeMonitoredRegion(identifier) -> locationObject | false | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Removes a monitored region from Location Services | | Parameters |identifier
- a string which should contain the identifier of the region to remove from monitoringidentifier
key is not provided, a new UUID string is generated and used as the identifier.identifier
key matches an already monitored region, this region will replace the existing one.hs.location:startTracking() -> locationObject
hs.location:stopTracking() -> locationObject