hs.location
ModuleDetermine the Mac's location via macOS Location Services.
Location data is obtained through WiFi network scanning and, where available, GPS
hardware. User permission is required — call hs.permissions.requestLocation()
before using any tracking features.
The module exposes a geocoder sub-object for forward/reverse geocoding without
requiring Location Services.
locationTable
A locationTable is a plain JS object with the following keys:
| Key | Type | Description |
|---|---|---|
latitude |
number | Degrees north (positive) or south (negative) |
longitude |
number | Degrees east (positive) or west (negative) |
altitude |
number | Metres above sea level (0 if unknown) |
horizontalAccuracy |
number | Uncertainty radius in metres (-1 if invalid) |
verticalAccuracy |
number | Altitude accuracy in metres (-1 if invalid) |
course |
number | Direction of travel in degrees (-1 if invalid) |
speed |
number | Metres per second (-1 if invalid) |
timestamp |
number | Seconds since the Unix epoch |
Types
This module provides the following types:
Properties
Methods
hs.location.lookupAddress(address) -> Promise<placemarkTable[]>
Geocodes an address string into an array of placemarkTables.
Returns a Promise that resolves with an array of placemarkTable objects
(sorted by relevance) or rejects with an error message.
Declaration
hs.location.lookupAddress(address) -> Promise<placemarkTable[]>Parameters
| Name | Type | Description |
|---|---|---|
| address | string | a free-form address string in any locale |
Returns
Promise<placemarkTable[]>
a Promise resolving to an array of placemarkTables
Example
hs.location.geocoder.lookupAddress("Apple Park, Cupertino")
.then(p => console.log(p[0].locality, p[0].countryCode))hs.location.lookupLocation(locationTable) -> Promise<placemarkTable[]>
Reverse-geocodes a locationTable into an array of placemarkTables.
Returns a Promise that resolves with matching placemarks or rejects with
an error.
Declaration
hs.location.lookupLocation(locationTable) -> Promise<placemarkTable[]>Parameters
| Name | Type | Description |
|---|---|---|
| locationTable | JSValue | an object with at least `latitude` and `longitude` |
Returns
Promise<placemarkTable[]>
a Promise resolving to an array of placemarkTables
Example
hs.location.geocoder.lookupLocation({ latitude: 37.3349, longitude: -122.0090 })
.then(p => console.log(p[0].name))hs.location.servicesEnabled() -> boolean
Returns true if Location Services are enabled system-wide.
Declaration
hs.location.servicesEnabled() -> booleanReturns
boolean
true if enabled, false otherwise
Example
hs.location.servicesEnabled() // → true or falsehs.location.authorizationStatus() -> string
Returns the app's current Location Services authorization status as a string.
Declaration
hs.location.authorizationStatus() -> stringReturns
string
`"authorized"`, `"denied"`, `"restricted"`, or `"notDetermined"`
Example
const status = hs.location.authorizationStatus()
if (status === 'notDetermined') hs.permissions.requestLocation()hs.location.get() -> [AnyHashable: Any]
Returns the most recently cached location as a locationTable, or null.
Activates Location Services if not already running. The cache is updated
periodically while any watcher is running.
Declaration
hs.location.get() -> [AnyHashable: Any]Returns
[AnyHashable: Any]
a locationTable, or null if no cached location is available
Example
const loc = hs.location.get()
if (loc) console.log(loc.latitude, loc.longitude)hs.location.distance(from, to) -> number
Calculates the straight-line distance in metres between two locationTables.
Does not require Location Services.
Declaration
hs.location.distance(from, to) -> numberParameters
| Name | Type | Description |
|---|---|---|
| from | JSValue | locationTable with at least `latitude` and `longitude` |
| to | JSValue | locationTable with at least `latitude` and `longitude` |
Returns
number
distance in metres, or `-1` if either table is invalid
Example
const d = hs.location.distance(
{ latitude: 51.5074, longitude: -0.1278 },
{ latitude: 48.8566, longitude: 2.3522 }
) // → ~341,000 metreshs.location.sunrise(latitude, longitude, date) -> NSNumber
Returns the time of sunrise for the given coordinates and date as seconds
since the Unix epoch, or null if the sun does not rise on that date (polar
night). Pass a JS `Date` for `date`, or omit/pass null to use today.
Declaration
hs.location.sunrise(latitude, longitude, date) -> NSNumberParameters
| Name | Type | Description |
|---|---|---|
| latitude | number | degrees north (positive) or south (negative) |
| longitude | number | degrees east (positive) or west (negative) |
| date | JSValue | optional JS `Date`; defaults to today |
Returns
NSNumber
seconds since epoch of sunrise, or null
Example
const rise = hs.location.sunrise(51.5, -0.1)
console.log(new Date(rise * 1000).toTimeString())hs.location.sunset(latitude, longitude, date) -> NSNumber
Returns the time of sunset for the given coordinates and date as seconds
since the Unix epoch, or null if the sun does not set on that date (midnight
sun). Pass a JS `Date` for `date`, or omit/pass null to use today.
Declaration
hs.location.sunset(latitude, longitude, date) -> NSNumberParameters
| Name | Type | Description |
|---|---|---|
| latitude | number | degrees north (positive) or south (negative) |
| longitude | number | degrees east (positive) or west (negative) |
| date | JSValue | optional JS `Date`; defaults to today |
Returns
NSNumber
seconds since epoch of sunset, or null
Example
const set = hs.location.sunset(51.5, -0.1)
console.log(new Date(set * 1000).toTimeString())hs.location.addWatcher() -> HSLocationWatcher
Creates a new location watcher object. Call `.start()` on it to begin
receiving updates. The watcher is automatically stopped when the module
shuts down.
Declaration
hs.location.addWatcher() -> HSLocationWatcherReturns
HSLocationWatcher
an HSLocationWatcher
Example
const w = hs.location.addWatcher()
w.setCallback((event, data) => console.log(event, data))
w.start()hs.location.removeWatcher(watcher) -> None
Removes a previously created watcher and stops it if running.
Declaration
hs.location.removeWatcher(watcher) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| watcher | HSLocationWatcher | the watcher returned by `addWatcher()` |
Returns
None
Example
const w = hs.location.addWatcher()
w.start()
hs.location.removeWatcher(w)