Home
pinpoint is a python based script that is able to find the location of your Mac using either Apple's or Google's GeoCoding APIs. It works based off of the same idea as Prey, Find My iPhone, or LoJack. However, pinpoint is different in a few ways:
- Continuously checks for location updates in the background
- Stores location locally on disk in a plist for easy parsing
- Has no server backend
- Extendable with preflight and postflight scripts
- Free
pinpoint requires a wireless adapter to obtain location data. On older Macs that did not ship with a wireless adapter this script will exit. Your Mac does not need to be connected to an active SSID for location data to be found, just enabled. If you normally keep your wireless adapter disabled pinpoint can enable it for the run and disable it post run.
First some terminology.
-
Geocoding - is the process of converting a postal address into geographical coordinates.
-
Reverse Geocoding - is the process of converting geographical coordinates into a human readable address (frequently a street address).
For pinpoint we are sending information on wireless networks; MAC addresses, signal strength, SSID names, and other network details to APIs. When the API call returns data we get Latitude and Longitude. After we have gotten the Latitude and Longitude and make a secondary API call to Reverse Geocode the data into an address. So that the terminology doesn't overlap, pinpoint uses the word 'lookup' for geocoding and 'address' lookup for reverse geocoding.
Core Location is used by default for both geocoding lookup requests and address (reverse) lookup requests. This is often times a more accurate location since we are using Apple's Core Location framework. This is the same framework that the system uses and is also tied to the same database that iPhones use.
For this lookup to work Location Services (LS) will need to be enabled, which pinpoint will do if it is currently disabled. On each run if LS will be enabled, if turned off, and the System Python binary will be given access to LS. Due to how LS and the Core Location framework interact the first run to enable all of the services will take ~45 seconds. Sequential runs take about 8-12 seconds.
Note: when a lookup is being processed a visual is shown in the menu bar.
Below are some direct quotes from Apple regarding Core Location:
The Core Location framework lets you determine the current location or heading associated with a device. The framework uses the available hardware to determine the user’s position and heading. You use the classes and protocols in this framework to configure and schedule the delivery of location and heading events. You can also use it to define geographic regions and monitor when the user crosses the boundaries of those regions. In iOS, you can also define a region around a Bluetooth beacon.
The CLGeocoder class provides services for converting between a coordinate (specified as a latitude and longitude) and the user-friendly representation of that coordinate. A user-friendly representation of the coordinate typically consists of the street, city, state, and country information corresponding to the given location, but it may also contain a relevant point of interest, landmarks, or other identifying information. A geocoder object is a single-shot object that works with a network-based service to look up placemark information for its specified coordinate value.
Your approximate location is determined using information from local Wi-Fi networks, and is collected by Location Services in a manner that doesn’t personally identify you.
You have the option of using Google's Geocoding API for lookup and address (reverse) lookup requests.
This works by scanning for wireless networks using Apple's airport command located:
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/A/Resources/airportAfter a XML list of near wireless networks is returned we process that data to find the 5 wireless access point's (WAP) that are closest to your Mac. We do this by sorting based on the wireless signal strength. Then we send those networks to Google's Geocoding API in a http GET request in order to find our Latitude and Longitude. Followed by a secondary API call to do the address lookup.
This API comes with the following limits:
- 2,500 free requests per day
- 10 requests per second
However, it comes with the huge benefit of not needing Python to be enabled in Location Services.
Additionally, to use the service you will need an API key. Please refer to the preferences for using the Google location service api. Requires v2.0.1. Get your key here.
Additional information can be found: https://developers.google.com/maps/documentation/geocoding/usage-limits