geotoolbox_skill

Overview

This skill explains portable place representation using PlaceDescriptor from GeoToolbox and how to integrate it with MapKit for geocoding and cross-service identifiers. It shows how to build descriptors from coordinates, addresses, or MKMapItem, perform forward and reverse geocoding with async APIs, and attach multi-service place identifiers for interoperability.

How this skill works

PlaceDescriptor groups multiple PlaceRepresentation values (coordinate, address, commonName) and optional SupportingPlaceRepresentation entries (service identifiers). Use PlaceDescriptor(item: MKMapItem) to convert MapKit results directly. Perform forward and reverse geocoding with MKGeocodingRequest and MKReverseGeocodingRequest and convert MKMapItem results into PlaceDescriptor instances or build descriptors manually.

When to use it

• You need a portable, serializable representation of a place for storage or network transfer.
• Converting MKMapItem results from MapKit into a neutral place structure.
• Forward geocoding: turn an address string into coordinates and a map item.
• Reverse geocoding: resolve coordinates into an address or named place.
• Maintaining cross-service identifiers (Apple Maps, Google, Foursquare) for the same place.

Best practices

• Always import GeoToolbox when using PlaceDescriptor and MapKit for geocoding APIs.
• Check optional properties (coordinate, address, commonName) for nil before use.
• Prefer MKGeocodingRequest / MKReverseGeocodingRequest to get MKMapItem results rather than CLGeocoder/CLPlacemark.
• Wrap CLLocationCoordinate2D in CLLocation for reverse geocoding requests.
• Define constants for service identifier keys to avoid silent failures from typos.
• Handle empty geocoding results and errors with async/await and do/catch.

Example use cases

• Create a PlaceDescriptor from known coordinates and display its commonName and lat/lon.
• Forward geocode a user-entered address, convert the first MKMapItem to a PlaceDescriptor, and attach service IDs.
• Reverse geocode a tap on a map to show an address string and build a descriptor for sharing.
• Migrate place data between mapping services by storing serviceIdentifiers in SupportingPlaceRepresentation.
• Build a search result list by geocoding queries and formatting descriptors with nil-safe property access.