Geocoding from Python on macOS using pyobjc-framework-CoreLocation#

Rhet Turnbull shared this short script for looking up the named timezone for a given location from Python on macOS using objc and the CoreLocation framework. It uses the objc package and pyobjc-framework-CoreLocation.

This piqued my interest, so I conversed with Claude about other things I could do with that same framework. Here’s the script we came up with, for geocoding an address passed to it using Core Location’s CLGeocoder.geocodeAddressString() method:

1
# /// script
2
# requires-python = ">=3.12"
3
# dependencies = [
4
#     "pyobjc-core",
5
#     "pyobjc-framework-CoreLocation",
6
#     "click"
7
# ]
8
# ///
9
"""Basic geocoding using CoreLocation on macOS."""
10

11
import click
12
import objc
13
from CoreLocation import CLGeocoder
14
from Foundation import NSRunLoop, NSDate
15

16
def forward_geocode(address: str) -> list[dict]:
17
    with objc.autorelease_pool():
18
        geocoder = CLGeocoder.alloc().init()
19
        results = {"placemarks": [], "error": None}
20
        completed = False
21

22
        def completion(placemarks, error):
23
            nonlocal completed
24
            if error:
25
                results["error"] = error.localizedDescription()
26
            elif placemarks:
27
                results["placemarks"] = placemarks
28
            completed = True
29

30
        geocoder.geocodeAddressString_completionHandler_(address, completion)
31

32
        while not completed:
33
            NSRunLoop.currentRunLoop().runMode_beforeDate_(
34
                "NSDefaultRunLoopMode",
35
                NSDate.dateWithTimeIntervalSinceNow_(0.1)
36
            )
37

38
        if results["error"]:
39
            raise Exception(f"Geocoding error: {results['error']}")
40

41
        return [{
42
            "latitude": pm.location().coordinate().latitude,
43
            "longitude": pm.location().coordinate().longitude,
44
            "name": pm.name(),
45
            "locality": pm.locality(),
46
            "country": pm.country()
47
        } for pm in results["placemarks"]]
48

49
@click.command()
50
@click.argument('address')
51
def main(address):
52
    try:
53
        locations = forward_geocode(address)
54
        for loc in locations:
55
            click.echo("\nLocation found:")
56
            for key, value in loc.items():
57
                if value:
58
                    click.echo(f"{key}: {value}")
59
    except Exception as e:
60
        click.echo(f"Error: {e}", err=True)
61
        raise click.Abort()
62

63
if __name__ == "__main__":
64
    main()

This can be run using uv run like this:

1
uv run geocode.py '500 Grove St, San Francisco, CA'

Example output:

1
Location found:
2
latitude: 37.777717
3
longitude: -122.42504
4
name: 500 Grove St
5
locality: San Francisco
6
country: United States

I tried this without a network connection and it failed, demonstrating that Core Location uses some form of network-based API to geocode addresses.

There are a few new-to-me tricks in this script.

with objc.autorelease_pool() is a neat memory management pattern provided by PyObjC for establishing an autorelease memory pool for the duration of a Python with block. Everything allocated by Objective C should be automatically cleaned up at the end of that block.

The geocodeAddressString method takes a completion handler. In this code we’re setting that to a Python function that communicates state using shared variables:

1
results = {"placemarks": [], "error": None}
2
completed = False
3

4
def completion(placemarks, error):
5
    nonlocal completed
6
    if error:
7
        results["error"] = error.localizedDescription()
8
    elif placemarks:
9
        results["placemarks"] = placemarks
10
    completed = True

We start that running like so:

1
geocoder = CLGeocoder.alloc().init()
2
geocoder.geocodeAddressString_completionHandler_(address, completion)

Then the clever bit:

1
while not completed:
2
    NSRunLoop.currentRunLoop().runMode_beforeDate_(
3
        "NSDefaultRunLoopMode",
4
        NSDate.dateWithTimeIntervalSinceNow_(0.1)
5
    )

Where did this code come from? It turns out Claude lifted that from the Rhet Turnbull script I fed into it earlier. Here’s that code with Rhet’s comments:

1
WAIT_FOR_COMPLETION = 0.01  # wait time for async completion in seconds
2
# ...
3

4
# reverseGeocodeLocation_completionHandler_ is async so run the event loop until completion
5
# I usually use threading.Event for this type of thing in pyobjc but the the thread blocked forever
6
waiting = 0
7
while not completed:
8
    NSRunLoop.currentRunLoop().runMode_beforeDate_(
9
        "NSDefaultRunLoopMode",
10
        NSDate.dateWithTimeIntervalSinceNow_(WAIT_FOR_COMPLETION),
11
    )
12
    waiting += WAIT_FOR_COMPLETION
13
    if waiting >= COMPLETION_TIMEOUT:
14
        raise TimeoutError(
15
            f"Timeout waiting for completion of reverseGeocodeLocation_completionHandler_: {waiting} seconds"
16
        )

Is this the best pattern for my own, simpler script? I don’t know for sure, but it works. Approach with caution!

Since my script has inline script dependencies and I’ve published it to a Gist you can run it directly with uv run without first installing anything else like this:

1
uv run https://gist.githubusercontent.com/simonw/178ea93ac035293744bde97270d6a7a0/raw/88c817e4103034579ec7523d8591bf60aa11fa67/geocode.py \
2
  '500 Grove St, San Francisco, CA'