apple-maps-api 0.1.0__py3-none-any.whl

apple_maps_api/helpers.py

@@ -0,0 +1,145 @@
+"""Helper functions for common geocoding operations."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from apple_maps_api.models import GeocodeResult, Place
+
+if TYPE_CHECKING:
+    from apple_maps_api.client import AppleMapsClient
+
+log = logging.getLogger(__name__)
+
+
+def _log_geocode_event(message: str, level: str = "info", **extras: object) -> None:
+    extra_str = ", ".join(f"{k}={v!r}" for k, v in extras.items())
+    full_message = f"{message} ({extra_str})" if extra_str else message
+    getattr(log, level)(full_message)
+
+
+def _place_to_geocode_result(
+    place: Place,
+    *,
+    lat: float | None = None,
+    lon: float | None = None,
+    postal_code_override: str | None = None,
+) -> GeocodeResult | None:
+    """Extract a GeocodeResult from an Apple Maps Place object.
+
+    Returns None if coordinates cannot be determined.
+    """
+    coord = place.coordinate
+
+    if lat is not None and lon is not None:
+        result_lat = lat
+        result_lon = lon
+    elif coord:
+        result_lat = coord.latitude
+        result_lon = coord.longitude
+    else:
+        return None
+
+    addr = place.structuredAddress
+    address1 = addr.fullThoroughfare if addr else None
+    city = addr.locality if addr else None
+    state_code = addr.administrativeAreaCode if addr else None
+    postal_code = postal_code_override or (addr.postCode if addr else None)
+
+    formatted_address = None
+    if place.formattedAddressLines:
+        formatted_address = ", ".join(place.formattedAddressLines)
+
+    return GeocodeResult(
+        lat=result_lat,
+        lon=result_lon,
+        address1=address1,
+        postal_code=postal_code,
+        city=city,
+        state_code=state_code,
+        country_code=place.countryCode,
+        formatted_address=formatted_address,
+    )
+
+
+def geocode_postal_code(
+    client: "AppleMapsClient",
+    *,
+    postal_code: str,
+    country: str = "US",
+) -> GeocodeResult | None:
+    """Geocode a postal code and extract coordinates and address information.
+
+    Args:
+        client: AppleMapsClient instance to use for geocoding
+        postal_code: The postal code to geocode
+        country: Country code (default: "US")
+
+    Returns:
+        GeocodeResult with lat, lon, city, and state information.
+        Returns None if geocoding fails.
+    """
+    location_result = client.geocode(postal_code, limit_to_countries=country)
+
+    if len(location_result.results) == 0:
+        _log_geocode_event(
+            "no geocoding results for zip code",
+            level="info",
+            zip=postal_code,
+            country=country,
+        )
+
+        return None
+
+    if len(location_result.results) > 1:
+        _log_geocode_event(
+            "multiple geocoding results for zip code",
+            zip=postal_code,
+            results=len(location_result.results),
+        )
+
+    place = location_result.results[0]
+
+    return _place_to_geocode_result(place, postal_code_override=postal_code)
+
+
+def geocode_coordinates(
+    client: "AppleMapsClient",
+    *,
+    lat: float,
+    lon: float,
+) -> GeocodeResult | None:
+    """Reverse geocode coordinates and extract address information.
+
+    Args:
+        client: AppleMapsClient instance to use for geocoding
+        lat: Latitude
+        lon: Longitude
+
+    Returns:
+        GeocodeResult with lat, lon, zip_code, city, and state information.
+        Returns None if geocoding fails.
+    """
+    location_result = client.reverse_geocode((lat, lon))
+
+    if len(location_result.results) == 0:
+        _log_geocode_event(
+            "no geocoding results for coordinates",
+            level="info",
+            lat=lat,
+            lon=lon,
+        )
+
+        return None
+
+    if len(location_result.results) > 1:
+        _log_geocode_event(
+            "multiple geocoding results for coordinates",
+            lat=lat,
+            lon=lon,
+            results=len(location_result.results),
+        )
+
+    place = location_result.results[0]
+
+    # preserve the caller's coordinates, not whatever Apple rounded to
+    return _place_to_geocode_result(place, lat=lat, lon=lon)

apple_maps_api/models.py

@@ -0,0 +1,288 @@
+"""Pydantic models for Apple Maps Server API responses.
+
+Model names and field names match Apple's official API documentation exactly.
+Docstrings explain what each field represents in familiar terms.
+
+See: https://developer.apple.com/documentation/applemapsserverapi
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class AddressCategory(StrEnum):
+    Country = "Country"
+    AdministrativeArea = "AdministrativeArea"
+    SubAdministrativeArea = "SubAdministrativeArea"
+    Locality = "Locality"
+    SubLocality = "SubLocality"
+    PostalCode = "PostalCode"
+
+
+class PoiCategory(StrEnum):
+    Airport = "Airport"
+    AirportGate = "AirportGate"
+    AirportTerminal = "AirportTerminal"
+    AmusementPark = "AmusementPark"
+    AnimalService = "AnimalService"
+    Aquarium = "Aquarium"
+    ATM = "ATM"
+    AutomotiveRepair = "AutomotiveRepair"
+    Bakery = "Bakery"
+    Bank = "Bank"
+    Baseball = "Baseball"
+    Basketball = "Basketball"
+    Beach = "Beach"
+    Beauty = "Beauty"
+    Bowling = "Bowling"
+    Brewery = "Brewery"
+    Cafe = "Cafe"
+    Campground = "Campground"
+    CarRental = "CarRental"
+    Castle = "Castle"
+    ConventionCenter = "ConventionCenter"
+    Distillery = "Distillery"
+    EVCharger = "EVCharger"
+    Fairground = "Fairground"
+    FireStation = "FireStation"
+    Fishing = "Fishing"
+    FitnessCenter = "FitnessCenter"
+    FoodMarket = "FoodMarket"
+    Fortress = "Fortress"
+    GasStation = "GasStation"
+    GoKart = "GoKart"
+    Golf = "Golf"
+    Hiking = "Hiking"
+    Hospital = "Hospital"
+    Hotel = "Hotel"
+    Kayaking = "Kayaking"
+    Landmark = "Landmark"
+    Laundry = "Laundry"
+    Library = "Library"
+    Mailbox = "Mailbox"
+    Marina = "Marina"
+    MiniGolf = "MiniGolf"
+    MovieTheater = "MovieTheater"
+    Museum = "Museum"
+    MusicVenue = "MusicVenue"
+    NationalMonument = "NationalMonument"
+    NationalPark = "NationalPark"
+    Nightlife = "Nightlife"
+    Park = "Park"
+    Parking = "Parking"
+    Pharmacy = "Pharmacy"
+    Planetarium = "Planetarium"
+    Playground = "Playground"
+    Police = "Police"
+    PostOffice = "PostOffice"
+    PublicTransport = "PublicTransport"
+    ReligiousSite = "ReligiousSite"
+    Restaurant = "Restaurant"
+    Restroom = "Restroom"
+    RockClimbing = "RockClimbing"
+    RVPark = "RVPark"
+    School = "School"
+    SkatePark = "SkatePark"
+    Skating = "Skating"
+    Skiing = "Skiing"
+    Soccer = "Soccer"
+    Spa = "Spa"
+    Stadium = "Stadium"
+    Store = "Store"
+    Surfing = "Surfing"
+    Swimming = "Swimming"
+    Tennis = "Tennis"
+    Theater = "Theater"
+    University = "University"
+    Volleyball = "Volleyball"
+    Winery = "Winery"
+    Zoo = "Zoo"
+
+
+class SearchResultType(StrEnum):
+    """Result type filter for /v1/search."""
+
+    poi = "poi"
+    address = "address"
+    physicalFeature = "physicalFeature"
+    pointOfInterest = "pointOfInterest"
+
+
+class SearchACResultType(StrEnum):
+    """Result type filter for /v1/searchAutocomplete."""
+
+    poi = "poi"
+    address = "address"
+    physicalFeature = "physicalFeature"
+    pointOfInterest = "pointOfInterest"
+    query = "query"
+
+
+class Location(BaseModel):
+    """A coordinate pair from Apple Maps API.
+
+    latitude: north-south position (e.g. 37.334)
+    longitude: east-west position (e.g. -122.009)
+    """
+
+    latitude: float
+    longitude: float
+
+
+class StructuredAddress(BaseModel):
+    """Detailed address components of a place.
+
+    Apple uses different terminology than most geocoding APIs:
+    - locality = city
+    - administrativeArea = state/province name
+    - administrativeAreaCode = state/province short code (e.g. "NY")
+    - subAdministrativeArea = county name
+    - postCode = postal/ZIP code
+    - fullThoroughfare = full street address (number + street, e.g. "841 Broadway")
+    - thoroughfare = street name (e.g. "Broadway")
+    - subThoroughfare = street/house number (e.g. "841")
+    - subLocality = neighborhood or area within the city
+    - areasOfInterest = common names for the surrounding area
+    - dependentLocalities = neighborhood names
+    """
+
+    administrativeArea: str | None = None
+    administrativeAreaCode: str | None = None
+    subAdministrativeArea: str | None = None
+    areasOfInterest: list[str] | None = None
+    dependentLocalities: list[str] | None = None
+    fullThoroughfare: str | None = None
+    locality: str | None = None
+    postCode: str | None = None
+    subLocality: str | None = None
+    subThoroughfare: str | None = None
+    thoroughfare: str | None = None
+
+
+class MapRegion(BaseModel):
+    """A rectangular bounding box on a map.
+
+    Expressed as south-west and north-east corners.
+    """
+
+    eastLongitude: float
+    northLatitude: float
+    southLatitude: float
+    westLongitude: float
+
+
+class Place(BaseModel):
+    """A place returned by geocode, reverseGeocode, or place lookup endpoints.
+
+    coordinate: lat/lng of the place
+    formattedAddressLines: human-readable address lines (e.g. ["841 Broadway", "New York, NY 10003"])
+    structuredAddress: parsed address components
+    displayMapRegion: suggested map viewport for displaying this place
+    """
+
+    id: str | None = None
+    name: str | None = None
+    coordinate: Location | None = None
+    formattedAddressLines: list[str] | None = None
+    structuredAddress: StructuredAddress | None = None
+    country: str | None = None
+    countryCode: str | None = None
+    displayMapRegion: MapRegion | None = None
+    alternateIds: list[str] | None = None
+
+
+class SearchPlace(Place):
+    """Extended Place returned by /v1/search with POI category info.
+
+    poiCategory: point-of-interest category (e.g. "Restaurant", "MovieTheater")
+    """
+
+    poiCategory: str | None = None
+
+
+class PlaceResults(BaseModel):
+    """Response from /v1/geocode and /v1/reverseGeocode.
+
+    results: list of Place objects matching the query
+    """
+
+    results: list[Place]
+
+
+class SearchResponse(BaseModel):
+    """Response from /v1/search.
+
+    results: list of SearchPlace objects with optional POI category
+    displayMapRegion: suggested map viewport encompassing all results
+    """
+
+    results: list[SearchPlace]
+    displayMapRegion: MapRegion | None = None
+
+
+class AutocompleteResult(BaseModel):
+    """A single autocomplete suggestion from /v1/searchAutocomplete.
+
+    completionUrl: relative URL to /v1/search to fetch full details for this suggestion
+    displayLines: raw text lines Apple returns — use completionTitle / completionSubtitle instead
+    location: approximate coordinate of the suggestion
+    structuredAddress: parsed address components if available
+    """
+
+    completionUrl: str | None = None
+    displayLines: list[str] | None = None
+    location: Location | None = None
+    structuredAddress: StructuredAddress | None = None
+
+    @property
+    def completionTitle(self) -> str | None:
+        """Primary display text (e.g. place name or street address)."""
+        return self.displayLines[0] if self.displayLines else None
+
+    @property
+    def completionSubtitle(self) -> str | None:
+        """Secondary display text (e.g. city, state)."""
+        return (
+            self.displayLines[1]
+            if self.displayLines and len(self.displayLines) > 1
+            else None
+        )
+
+
+class SearchAutocompleteResponse(BaseModel):
+    """Response from /v1/searchAutocomplete.
+
+    results: list of autocomplete suggestions
+    """
+
+    results: list[AutocompleteResult]
+
+
+class TokenResponse(BaseModel):
+    """Response from /v1/token.
+
+    accessToken: short-lived Bearer token for API requests
+    expiresInSeconds: token lifetime (typically 1800 = 30 minutes)
+    """
+
+    accessToken: str
+    expiresInSeconds: int
+
+
+class GeocodeResult(BaseModel):
+    """Provider-agnostic geocode result.
+
+    Identical to radar-mapping-api's GeocodeResult for drop-in replacement.
+    This abstraction allows swapping Apple Maps for Radar without changing consuming code.
+    """
+
+    lat: float
+    lon: float
+    address1: str | None = None
+    address2: str | None = None
+    postal_code: str | None
+    city: str | None
+    state_code: str | None
+    country_code: str | None = None
+    formatted_address: str | None

apple_maps_api/version.py

@@ -0,0 +1,34 @@
+"""Version handling for apple-maps-api."""
+
+import importlib.metadata
+from pathlib import Path
+
+
+def is_local_source_checkout() -> bool:
+    """Check if the code is running from a local source checkout."""
+    package_dir = Path(__file__).resolve().parent
+    # Since this is a flat layout (module-root = ""), repo root is the parent of the package dir
+    repo_root = package_dir.parent
+
+    return (repo_root / ".git").exists() and (repo_root / "pyproject.toml").exists()
+
+
+def get_version() -> str:
+    """Get the version string, appending .dev if running from source."""
+    try:
+        # Try to get the version of the installed package
+        version = importlib.metadata.version("apple-maps-api")
+    except importlib.metadata.PackageNotFoundError:
+        # Fallback for local development if not installed
+        version = "0.1.0"
+
+    if not is_local_source_checkout():
+        return version
+
+    if version.endswith(".dev"):
+        return version
+
+    return f"{version}.dev"
+
+
+__version__ = get_version()