Disclosure: I work on ClearWhirl, an iPhone app that works out what is in your photo library on the device, with no upload. Places is one of its features.
Every photo with a location carries a latitude and longitude. Turning that into "Lisbon, Portugal" normally means CLGeocoder, which sends the coordinates to Apple's servers and is rate limited. For an app whose promise is that your library never leaves the phone, and which has to do it for thousands of photos, that was a non-starter. We replaced it with one bundled binary file, memory-mapped, and plain geometry. This is how it works.
What reading the location costs you
PHAsset.location is metadata. No new permission is needed beyond the photo library access you already have, and no pixel is read. That is the first privacy win: you are using data the library already holds. What you do with the coordinates then decides whether it stays private.
The data
- Regions: Natural Earth 1:10m admin-1 borders (public domain), simplified to about 330 m so the file stays small.
- Cities: GeoNames
cities5000(CC BY 4.0) for names and IANA time zones. Credit it in your app. We have an Acknowledgements screen. - A Python build script packs both into
places.bin, about 4.3 MB.
Memory-map it
Reading 4 MB into arrays at launch is wasteful when a lookup touches a few pages. NSData with .alwaysMapped lets the OS page the file in on demand:
init?(contentsOf url: URL) { guard let d = try? NSData(contentsOf: url, options: .alwaysMapped), d.length >= 128 else { return nil } file = d base = d.bytes func u32(_ o: Int) -> Int { Int(base.loadUnaligned(fromByteOffset: o, as: UInt32.self)) } guard base.load(fromByteOffset: 0, as: UInt32.self) == 0x4C50_5743 /* "CWPL" */, UInt32(u32(4)) == Self.formatVersion else { return nil } // ... read section offsets, and check each offset + length <= d.length } Design rules for the format:
- Magic number and version first. A wrong or old file returns
nilinstead of garbage. - A section table in the header (offset and length per section), and a bounds check on every one. A corrupt file must fail at open, not crash during a lookup.
- Fixed-width integers, little-endian,
loadUnaligned. Mapped data is not guaranteed to be aligned for aUInt32load at an arbitrary offset. UseloadUnaligned(fromByteOffset:as:)unless you control the layout. - A data version number you store with results, so a new file makes every phone recompute.
The lookup, in steps
- Reject non-locations: missing, out of range, or exactly (0, 0).
- Grid: a 360×180 grid of 1-degree cells, each listing the polygon rings whose bounding box touches it. You test only those few rings, not every country.
- Point in polygon: the even-odd rule per ring. Combine the rings of one state so holes work.
- Coastline fallback: no polygon contains the point? If a ring edge is within 5 km, use it. Otherwise it is open water and has no place.
- City: among places of the same country within 80 km (200 km if none), give each an influence radius
max(3 km, 0.008 * sqrt(population) km)and pick the smallest distance-to-radius ratio. A place in another state counts 1.5 times as far and reads "Near".
Step 5 is where a naive nearest-city lookup goes wrong: a village next to a big city should usually read as the city, and a photo on the far side of a border should not. Scaling by population fixes most of it.
Memoise and keep it off the main thread
Photos taken in one afternoon share almost the same coordinate. A small dictionary keyed by a quantised coordinate answers repeats without redoing the polygon tests, behind an NSLock. The work runs on its own low-priority queue in chunks, never on the main thread, and is safe to repeat: an item that was read is not read again.
What you store
Do not store coordinates. Store a small packed number per photo (which state, which city, which zone) plus the data version and the rules version. Ours also never reaches widgets, notifications, Live Activities, share sheets or logs: log lines carry counts and timings only. A setting turns the whole thing off, and when off nothing is computed or kept.
Test it against a golden file
The build script has its own reference implementation of the same matcher and writes places-golden.tsv: coordinates and expected results. The Swift unit test, which runs on a Mac with plain Foundation, compares your implementation to it. Any change to a radius or penalty bumps a matchRulesVersion, and the golden file is regenerated in the same commit.
Limits, honestly
- Borders are simplified: a point within a few hundred metres of a border can land on the wrong side.
- Cities are the ones above 5,000 people. A photo in a very remote area can only read "Near" something.
- Names come from the data in the file, so they are only as good as it is, and localised names are a separate job.
These are why the UI says "Near" instead of pretending to precision.
Why bother
Once you can name a place on the device, a library becomes browsable by country, region and city, and search ("Lisbon") can use it, without a single request leaving the phone. That is the point of doing it offline.
ClearWhirl uses this for its Places folders: https://apps.apple.com/us/app/phone-cleaner-clearwhirl-ai/id6835310950
