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
This module has no properties.
Methods
hs.location.lookupAddress(address) -> Promise<[[String:Any]]>
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<[[String:Any]]>Parameters
| Name | Type | Description |
|---|---|---|
| address | string | a free-form address string in any locale |
Returns
Promise<[[String:Any]]>
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<[[String:Any]]>
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<[[String:Any]]>Parameters
| Name | Type | Description |
|---|---|---|
| locationTable | {[key: string]: number} | an object with at least `latitude` and `longitude` |
Returns
Promise<[[String:Any]]>
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() -> [String: 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() -> [String: Any]Returns
[String: 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 | {[key: string]: number} | locationTable with at least `latitude` and `longitude` |
| to | {[key: string]: number} | 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) -> Date
Returns the time of sunrise for the given coordinates and date, or null if the sun does not rise on that date (polar night).
Declaration
hs.location.sunrise(latitude, longitude, date) -> DateParameters
| Name | Type | Description |
|---|---|---|
| latitude | number | degrees north (positive) or south (negative) |
| longitude | number | degrees east (positive) or west (negative) |
| date | Date | the date to calculate for; pass null or omit to use today |
Returns
Date
A Date object representing the time of sunrise, or null
Example
const rise = hs.location.sunrise(51.5, -0.1)
console.log(rise.toTimeString())hs.location.sunset(latitude, longitude, date) -> Date
Returns the time of sunset for the given coordinates and date, or null if the sun does not set on that date (midnight sun).
Declaration
hs.location.sunset(latitude, longitude, date) -> DateParameters
| Name | Type | Description |
|---|---|---|
| latitude | number | degrees north (positive) or south (negative) |
| longitude | number | degrees east (positive) or west (negative) |
| date | Date | the date to calculate for; pass null or omit to use today |
Returns
Date
A Date object representing the time of sunset, or null
Example
const set = hs.location.sunset(51.5, -0.1)
console.log(set.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)