Skip to content

Home

Jump to bottom
jelockwood edited this page Dec 15, 2024 · 19 revisions

Introduction

pinpoint is a script that is able to find the location of your Mac using Google's GeoLocation and 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 (unless you count the Google APIs)
  • Does not use or require Apple's Location Services API
  • Free (as long as you stay within the monthly $200 free credit limit)

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.

How it works?

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 we then 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.

Technologies Used

Google's Geolocation and Geocoding APIs

This script only has the option of using Google's Geolocation API to find your location and Geocoding API for address (reverse) lookup requests. It also optionally uses Google's Elevation API to find your altitude.

This works by scanning for wireless networks using Apple's airport command located:

/System/Library/PrivateFrameworks/Apple80211.framework/Versions/A/Resources/airport

After a XML list of nearby wireless networks is returned we process that data to find the up to 12 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 Geolocation API as a JSON request in order to find our Latitude and Longitude. Followed by a secondary API call using Geocoding API to do the address lookup.

This API used to have the following limits:

  • 2,500 free requests per day
  • 10 requests per second

Sadly as of July 18th 2018 it now requires you to enable billing on your API account. You are supposed to get a $200 credit to your account per month and as far as I can see this means you could therefore call their APIs a total of 40,000 times per month so 10,000 for Geolocation + 10,000 for Geocoding + 10,000 for Elevation should be safe. You are also supposed to be able to set billing/usage limits for your API account so if you exceed these figures it should simply reject requests and prevent you incurring (additional) costs.

UPDATE As of March 2025 Google are changing their API usage criteria and this may mean users are more likely to exceed the 'free' use threshold and incur costs. Pinpoint now includes two optional features to help avoid this, the first is a set of changes provided by Ofir Gal which compare the latest SSID list with the previous SSID list and if changes are considered minimal then the changes will not call the Google APIs to do new lookups, these changes are activated by the 'optimise' option. The second change is the use of an optional web-served text document listing known and trusted SSIDs, if your device is connected to one of these then it is assumed your location is already known i.e. you are in your office and again the Google APIs are not called.

For information about the new Google charges that will be introduced in March 2025 see this link.

It is your responsibility to set your API account up appropriately and to be aware of the potential cost consequences.

To use the service you will need an API key. Please refer to the Google APIs for using the Google location service api. Get your key here.

Additional information can be found: https://developers.google.com/maps/documentation/geolocation/usage-limits

pinpoint

External projects

Clone this wiki locally