apple-maps-api 0.1.0__tar.gz → 0.2.1__tar.gz

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: apple-maps-api
-Version: 0.1.0
+Version: 0.2.1
 Summary: A modern Python client for the Apple Maps Server API with automatic JWT management and type safety
 Keywords: apple-maps,geocoding,search,geolocation
 Author: Michael Bianco
@@ -12,6 +12,7 @@ Requires-Dist: httpx2>=2.7.0
 Requires-Dist: funcy>=2.0
 Requires-Python: >=3.11
 Project-URL: Repository, https://github.com/iloveitaly/apple-maps-api
+Project-URL: Documentation, https://iloveitaly.github.io/python-apple-maps-api/
 Description-Content-Type: text/markdown
 
 [![Release Notes](https://img.shields.io/github/release/iloveitaly/apple-maps-api)](https://github.com/iloveitaly/apple-maps-api/releases)
@@ -32,6 +33,13 @@ The goal of this library is to provide similar functionality to the radar python
 - **Resilient**: Automatic retries with exponential backoff for transient network and server errors.
 - **Modern**: Uses `httpx` for synchronous requests, with a structure that's ready for future async support.
 
+## Full-stack Example
+
+See [`examples/full-stack/`](examples/full-stack/) for a runnable FastAPI + React/MapKit JS app that demonstrates:
+
+- Minting MapKit JS tokens server-side (`create_mapkit_token`) and rendering an interactive map
+- Address autocomplete via this client, proxied through a small FastAPI API
+
 ## Installation
 
 ```bash
@@ -42,7 +50,7 @@ uv add apple-maps-api
 
 ### Basic Setup
 
-You'll need your Team ID, Key ID, and the private key from your Apple Developer account.
+You'll need your Team ID, Key ID, and the private key from your Apple Developer account. Step-by-step portal setup (Maps ID, MapKit JS key, domains/localhost): [`docs/mapkit-js-credential-setup.md`](docs/mapkit-js-credential-setup.md).
 
 ```python
 from apple_maps_api import AppleMapsClient
@@ -52,7 +60,7 @@ client = AppleMapsClient(
     key_id="YOUR_KEY_ID",
     private_key="""-----BEGIN PRIVATE KEY-----
 ...
------END PRIVATE KEY-----"""
+-----END PRIVATE KEY-----""",
 )
 ```
 
@@ -73,6 +81,29 @@ from apple_maps_api import AppleMapsClient
 client = AppleMapsClient.from_env()
 ```
 
+### Generating a Long-lived Frontend Token
+
+MapKit JS needs a signed JWT (not the Server API access token). Use `create_mapkit_token()`:
+
+```python
+from apple_maps_api import AppleMapsClient
+
+client = AppleMapsClient.from_env()
+
+# default TTL is 1 hour — fine for production token endpoints
+token = client.create_mapkit_token()
+
+# long-lived token for local FE work (e.g. 30 days)
+token = client.create_mapkit_token(ttl_seconds=30 * 24 * 60 * 60)
+print(token)
+```
+
+Paste the printed JWT into MapKit JS / [mapkit-react](https://github.com/Nicolapps/mapkit-react) during development so you do not need a backend token endpoint.
+
+Optional domain lock: set `origin` on the client (or `APPLE_MAPS_ORIGIN`) so the token only works from that origin (e.g. `http://localhost:5173`). Omit `origin` for unrestricted local play.
+
+Do not ship long-lived tokens in production frontend builds — mint short-lived tokens from your server instead (see [`examples/full-stack/`](examples/full-stack/)).
+
 ### Geocoding
 
 Convert an address string to coordinates:
@@ -95,7 +126,7 @@ for place in results.results:
 Convert coordinates back to a structured address:
 
 ```python
-results = client.reverse_geocode((37.3346, -122.0090))
+results = client.reverse_geocode(lat=37.3346, lng=-122.0090)
 
 if results.results:
     print(results.results[0].formattedAddressLines)
@@ -110,8 +141,7 @@ if results.results:
 Search for points of interest near a location:
 
 ```python
-results = client.search("pizza", near="37.3346,-122.0090")
-# or: client.search("pizza", lat=37.3346, lng=-122.0090)
+results = client.search("pizza", lat=37.3346, lng=-122.0090)
 
 for place in results.results:
     print(f"{place.name} - {place.formattedAddressLines}")
@@ -127,7 +157,12 @@ for place in results.results:
 Provide search completions for a partial query and filter by country:
 
 ```python
-results = client.autocomplete("1 Apple Park", limit_to_countries="US", lat=37.3346, lng=-122.0090)
+results = client.autocomplete(
+    "1 Apple Park",
+    limit_to_countries=["US"],
+    lat=37.3346,
+    lng=-122.0090,
+)
 
 for completion in results.results:
     print(completion.displayLines)
@@ -137,6 +172,47 @@ for completion in results.results:
 # results.results[0].completionUrl => "/v1/search?q=1%20Apple%20Park%20Way..."
 ```
 
+Multi-value filters (countries, categories, result types, …) accept a list; a single string still works.
+
+### Importance of Lat/Lng Hinting for Result Relevance
+
+Always pass `lat`/`lng`. Autocomplete ranking is heavily biased by location — without it you get scattered results across the country for common street names. For server-side autocomplete, resolve the user's approximate location from their IP:
+
+1. Get the client public IP with [fastapi-ipware](https://github.com/iloveitaly/fastapi-ipware)
+2. Look up lat/lng via [observabilitystack/geoip-api](https://github.com/observabilitystack/geoip-api) (`ghcr.io/observabilitystack/geoip-api:latest`)
+
+### Location Bias Options
+
+Search, autocomplete, and geocode share the same location-hint shape:
+
+- **`lat` / `lng`** — app-defined search bias (Apple `searchLocation`). Prefer nearby results around this map point.
+- **`user_lat` / `user_lng`** — the user's current position (Apple `userLocation`). Used for ranking; if `lat`/`lng` are omitted, some endpoints may fall back to this.
+- **`search_region`** — bounding-box hint as a `MapRegion` (Apple `searchRegion`).
+- **`search_region_priority`** — `SearchRegionPriority.default` or `.required` (or the strings `"default"` / `"required"`).
+
+```python
+from apple_maps_api import MapRegion, SearchRegionPriority
+
+region = MapRegion(
+    northLatitude=37.5,
+    eastLongitude=-121.7,
+    southLatitude=37.1,
+    westLongitude=-122.5,
+)
+
+results = client.search(
+    "coffee",
+    lat=37.3346,
+    lng=-122.0090,
+    user_lat=37.3317,
+    user_lng=-122.0307,
+    search_region=region,
+    search_region_priority=SearchRegionPriority.required,
+    categories=["Cafe"],
+    limit_to_countries=["US"],
+)
+```
+
 ### Helper Functions
 
 The library includes high-level helpers for common geocoding operations:
@@ -207,7 +283,7 @@ result = geocode_coordinates(client, lat=40.7589, lon=-73.9851)
 Apple Park, Cupertino CA (`37.3346, -122.0090`):
 
 ```python
-place = client.reverse_geocode((37.3346, -122.0090)).results[0]
+place = client.reverse_geocode(lat=37.3346, lng=-122.0090).results[0]
 # place.name                                      => "Apple Park"
 # place.formattedAddressLines                     => ["Apple Park", "1 Apple Park Way", "Cupertino, CA  95014", "United States"]
 # place.structuredAddress.administrativeArea      => "California"
@@ -226,7 +302,7 @@ place = client.reverse_geocode((37.3346, -122.0090)).results[0]
 Times Square, NYC (`40.7589, -73.9851`):
 
 ```python
-place = client.reverse_geocode((40.7589, -73.9851)).results[0]
+place = client.reverse_geocode(lat=40.7589, lng=-73.9851).results[0]
 # place.name                                      => "Times Square"
 # place.formattedAddressLines                     => ["Times Square", "1552–1568 Broadway", "New York, NY  10036", "United States"]
 # place.structuredAddress.administrativeArea      => "New York"
@@ -245,7 +321,7 @@ place = client.reverse_geocode((40.7589, -73.9851)).results[0]
 Beverly Hills, CA (`34.1025226, -118.4167959`) — note `locality` vs formatted address mismatch:
 
 ```python
-place = client.reverse_geocode((34.1025226, -118.4167959)).results[0]
+place = client.reverse_geocode(lat=34.1025226, lng=-118.4167959).results[0]
 # place.name                                      => "1731 N Franklin Canyon Dr"
 # place.formattedAddressLines                     => ["1731 N Franklin Canyon Dr", "Beverly Hills, CA  90210", "United States"]
 # place.structuredAddress.administrativeArea      => "California"
@@ -261,6 +337,11 @@ place = client.reverse_geocode((34.1025226, -118.4167959)).results[0]
 # place.structuredAddress.dependentLocalities     => ["Beverly Crest"]
 ```
 
+## Related Projects
+
+- [fastapi-ipware](https://github.com/iloveitaly/fastapi-ipware) — client IP extraction for FastAPI (useful for lat/lng hinting via GeoIP)
+- [mapkit-react](https://github.com/Nicolapps/mapkit-react) — React bindings for MapKit JS (used in the full-stack example)
+
 ## [MIT License](LICENSE.md)
 
 ---

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/README.md

@@ -16,6 +16,13 @@ The goal of this library is to provide similar functionality to the radar python
 - **Resilient**: Automatic retries with exponential backoff for transient network and server errors.
 - **Modern**: Uses `httpx` for synchronous requests, with a structure that's ready for future async support.
 
+## Full-stack Example
+
+See [`examples/full-stack/`](examples/full-stack/) for a runnable FastAPI + React/MapKit JS app that demonstrates:
+
+- Minting MapKit JS tokens server-side (`create_mapkit_token`) and rendering an interactive map
+- Address autocomplete via this client, proxied through a small FastAPI API
+
 ## Installation
 
 ```bash
@@ -26,7 +33,7 @@ uv add apple-maps-api
 
 ### Basic Setup
 
-You'll need your Team ID, Key ID, and the private key from your Apple Developer account.
+You'll need your Team ID, Key ID, and the private key from your Apple Developer account. Step-by-step portal setup (Maps ID, MapKit JS key, domains/localhost): [`docs/mapkit-js-credential-setup.md`](docs/mapkit-js-credential-setup.md).
 
 ```python
 from apple_maps_api import AppleMapsClient
@@ -36,7 +43,7 @@ client = AppleMapsClient(
     key_id="YOUR_KEY_ID",
     private_key="""-----BEGIN PRIVATE KEY-----
 ...
------END PRIVATE KEY-----"""
+-----END PRIVATE KEY-----""",
 )
 ```
 
@@ -57,6 +64,29 @@ from apple_maps_api import AppleMapsClient
 client = AppleMapsClient.from_env()
 ```
 
+### Generating a Long-lived Frontend Token
+
+MapKit JS needs a signed JWT (not the Server API access token). Use `create_mapkit_token()`:
+
+```python
+from apple_maps_api import AppleMapsClient
+
+client = AppleMapsClient.from_env()
+
+# default TTL is 1 hour — fine for production token endpoints
+token = client.create_mapkit_token()
+
+# long-lived token for local FE work (e.g. 30 days)
+token = client.create_mapkit_token(ttl_seconds=30 * 24 * 60 * 60)
+print(token)
+```
+
+Paste the printed JWT into MapKit JS / [mapkit-react](https://github.com/Nicolapps/mapkit-react) during development so you do not need a backend token endpoint.
+
+Optional domain lock: set `origin` on the client (or `APPLE_MAPS_ORIGIN`) so the token only works from that origin (e.g. `http://localhost:5173`). Omit `origin` for unrestricted local play.
+
+Do not ship long-lived tokens in production frontend builds — mint short-lived tokens from your server instead (see [`examples/full-stack/`](examples/full-stack/)).
+
 ### Geocoding
 
 Convert an address string to coordinates:
@@ -79,7 +109,7 @@ for place in results.results:
 Convert coordinates back to a structured address:
 
 ```python
-results = client.reverse_geocode((37.3346, -122.0090))
+results = client.reverse_geocode(lat=37.3346, lng=-122.0090)
 
 if results.results:
     print(results.results[0].formattedAddressLines)
@@ -94,8 +124,7 @@ if results.results:
 Search for points of interest near a location:
 
 ```python
-results = client.search("pizza", near="37.3346,-122.0090")
-# or: client.search("pizza", lat=37.3346, lng=-122.0090)
+results = client.search("pizza", lat=37.3346, lng=-122.0090)
 
 for place in results.results:
     print(f"{place.name} - {place.formattedAddressLines}")
@@ -111,7 +140,12 @@ for place in results.results:
 Provide search completions for a partial query and filter by country:
 
 ```python
-results = client.autocomplete("1 Apple Park", limit_to_countries="US", lat=37.3346, lng=-122.0090)
+results = client.autocomplete(
+    "1 Apple Park",
+    limit_to_countries=["US"],
+    lat=37.3346,
+    lng=-122.0090,
+)
 
 for completion in results.results:
     print(completion.displayLines)
@@ -121,6 +155,47 @@ for completion in results.results:
 # results.results[0].completionUrl => "/v1/search?q=1%20Apple%20Park%20Way..."
 ```
 
+Multi-value filters (countries, categories, result types, …) accept a list; a single string still works.
+
+### Importance of Lat/Lng Hinting for Result Relevance
+
+Always pass `lat`/`lng`. Autocomplete ranking is heavily biased by location — without it you get scattered results across the country for common street names. For server-side autocomplete, resolve the user's approximate location from their IP:
+
+1. Get the client public IP with [fastapi-ipware](https://github.com/iloveitaly/fastapi-ipware)
+2. Look up lat/lng via [observabilitystack/geoip-api](https://github.com/observabilitystack/geoip-api) (`ghcr.io/observabilitystack/geoip-api:latest`)
+
+### Location Bias Options
+
+Search, autocomplete, and geocode share the same location-hint shape:
+
+- **`lat` / `lng`** — app-defined search bias (Apple `searchLocation`). Prefer nearby results around this map point.
+- **`user_lat` / `user_lng`** — the user's current position (Apple `userLocation`). Used for ranking; if `lat`/`lng` are omitted, some endpoints may fall back to this.
+- **`search_region`** — bounding-box hint as a `MapRegion` (Apple `searchRegion`).
+- **`search_region_priority`** — `SearchRegionPriority.default` or `.required` (or the strings `"default"` / `"required"`).
+
+```python
+from apple_maps_api import MapRegion, SearchRegionPriority
+
+region = MapRegion(
+    northLatitude=37.5,
+    eastLongitude=-121.7,
+    southLatitude=37.1,
+    westLongitude=-122.5,
+)
+
+results = client.search(
+    "coffee",
+    lat=37.3346,
+    lng=-122.0090,
+    user_lat=37.3317,
+    user_lng=-122.0307,
+    search_region=region,
+    search_region_priority=SearchRegionPriority.required,
+    categories=["Cafe"],
+    limit_to_countries=["US"],
+)
+```
+
 ### Helper Functions
 
 The library includes high-level helpers for common geocoding operations:
@@ -191,7 +266,7 @@ result = geocode_coordinates(client, lat=40.7589, lon=-73.9851)
 Apple Park, Cupertino CA (`37.3346, -122.0090`):
 
 ```python
-place = client.reverse_geocode((37.3346, -122.0090)).results[0]
+place = client.reverse_geocode(lat=37.3346, lng=-122.0090).results[0]
 # place.name                                      => "Apple Park"
 # place.formattedAddressLines                     => ["Apple Park", "1 Apple Park Way", "Cupertino, CA  95014", "United States"]
 # place.structuredAddress.administrativeArea      => "California"
@@ -210,7 +285,7 @@ place = client.reverse_geocode((37.3346, -122.0090)).results[0]
 Times Square, NYC (`40.7589, -73.9851`):
 
 ```python
-place = client.reverse_geocode((40.7589, -73.9851)).results[0]
+place = client.reverse_geocode(lat=40.7589, lng=-73.9851).results[0]
 # place.name                                      => "Times Square"
 # place.formattedAddressLines                     => ["Times Square", "1552–1568 Broadway", "New York, NY  10036", "United States"]
 # place.structuredAddress.administrativeArea      => "New York"
@@ -229,7 +304,7 @@ place = client.reverse_geocode((40.7589, -73.9851)).results[0]
 Beverly Hills, CA (`34.1025226, -118.4167959`) — note `locality` vs formatted address mismatch:
 
 ```python
-place = client.reverse_geocode((34.1025226, -118.4167959)).results[0]
+place = client.reverse_geocode(lat=34.1025226, lng=-118.4167959).results[0]
 # place.name                                      => "1731 N Franklin Canyon Dr"
 # place.formattedAddressLines                     => ["1731 N Franklin Canyon Dr", "Beverly Hills, CA  90210", "United States"]
 # place.structuredAddress.administrativeArea      => "California"
@@ -245,6 +320,11 @@ place = client.reverse_geocode((34.1025226, -118.4167959)).results[0]
 # place.structuredAddress.dependentLocalities     => ["Beverly Crest"]
 ```
 
+## Related Projects
+
+- [fastapi-ipware](https://github.com/iloveitaly/fastapi-ipware) — client IP extraction for FastAPI (useful for lat/lng hinting via GeoIP)
+- [mapkit-react](https://github.com/Nicolapps/mapkit-react) — React bindings for MapKit JS (used in the full-stack example)
+
 ## [MIT License](LICENSE.md)
 
 ---

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/apple_maps_api/__init__.py

@@ -18,6 +18,7 @@ from .models import (
     SearchACResultType,
     SearchAutocompleteResponse,
     SearchPlace,
+    SearchRegionPriority,
     SearchResponse,
     SearchResultType,
     StructuredAddress,
@@ -26,11 +27,8 @@ from .models import (
 from .version import __version__
 
 __all__ = [
-    "__version__",
-    "AppleMapsClient",
-    "geocode_coordinates",
-    "geocode_postal_code",
     "AddressCategory",
+    "AppleMapsClient",
     "AutocompleteResult",
     "GeocodeResult",
     "Location",
@@ -41,8 +39,12 @@ __all__ = [
     "SearchACResultType",
     "SearchAutocompleteResponse",
     "SearchPlace",
+    "SearchRegionPriority",
     "SearchResponse",
     "SearchResultType",
     "StructuredAddress",
     "TokenResponse",
+    "__version__",
+    "geocode_coordinates",
+    "geocode_postal_code",
 ]

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/apple_maps_api/client.py

@@ -10,7 +10,7 @@ import logging
 import os
 import time
 from collections.abc import Sequence
-from typing import TypedDict, Unpack
+from typing import Required, TypedDict, Unpack, overload
 from urllib.parse import parse_qs, urlparse
 
 import funcy as f
@@ -27,11 +27,12 @@ from tenacity import (
 from apple_maps_api.models import (
     AddressCategory,
     AutocompleteResult,
-    Location,
+    MapRegion,
     PlaceResults,
     PoiCategory,
     SearchACResultType,
     SearchAutocompleteResponse,
+    SearchRegionPriority,
     SearchResponse,
     SearchResultType,
     TokenResponse,
@@ -41,7 +42,7 @@ log = logging.getLogger(__name__)
 
 
 def _csv(value: str | Sequence | None) -> str | None:
-    """Serialize a plain string or a sequence of StrEnum values to a comma-separated string."""
+    """Serialize a string or sequence of values to Apple's comma-separated form."""
     if value is None:
         return None
     if isinstance(value, str):
@@ -49,17 +50,12 @@ def _csv(value: str | Sequence | None) -> str | None:
     return ",".join(str(v) for v in value)
 
 
-def _search_location(
+def _lat_lng_to_apple_str(
     *,
-    near: str | None = None,
     lat: float | None = None,
     lng: float | None = None,
 ) -> str | None:
-    """Resolve searchLocation from near="lat,lng" or separate lat/lng floats."""
-    if near is not None:
-        assert lat is None and lng is None, "pass near or lat/lng, not both"
-        return near
-
+    """Serialize an optional lat/lng pair to Apple's 'lat,lng' string form."""
     if lat is None and lng is None:
         return None
 
@@ -67,6 +63,17 @@ def _search_location(
     return f"{lat},{lng}"
 
 
+def _search_region(region: MapRegion | None) -> str | None:
+    """Serialize MapRegion to Apple's searchRegion form: northLat,eastLng,southLat,westLng."""
+    if region is None:
+        return None
+
+    return (
+        f"{region.northLatitude},{region.eastLongitude},"
+        f"{region.southLatitude},{region.westLongitude}"
+    )
+
+
 # shared timeout: 10s connect, 30s read
 _TIMEOUT = httpx2.Timeout(connect=10, read=30, write=10, pool=10)
 
@@ -103,50 +110,119 @@ _retry_policy = retry(
 )
 
 
-class GeocodeOptions(TypedDict, total=False):
-    limit_to_countries: str
-    lang: str
-    search_location: str
-    search_region: str
-    user_location: str
+class _GeocodeOptionsBase(TypedDict, total=False):
+    """Shared optional kwargs for :meth:`AppleMapsClient.geocode`.
 
+    Location params (all optional; different roles):
+
+    - ``lat`` / ``lng``: app-defined point hint; sent as Apple's
+      ``searchLocation`` (must pass both). Primary geographic bias.
+    - ``search_region``: app-defined bounding-box hint as :class:`MapRegion`.
+    - ``user_lat`` / ``user_lng``: the *user's* current position (must pass both).
+      Used for ranking/relevance; if ``lat``/``lng`` are omitted, some Apple
+      endpoints may fall back to user position as the search hint.
+    """
 
-class ReverseGeocodeOptions(TypedDict, total=False):
+    limit_to_countries: str | Sequence[str]
     lang: str
+    search_region: MapRegion
+    user_lat: float
+    user_lng: float
 
 
-class SearchOptions(TypedDict, total=False):
-    near: str
+class GeocodeOptionsLatLng(_GeocodeOptionsBase, total=False):
+    """Geocode options with required ``lat`` and ``lng`` location bias."""
+
+    lat: Required[float]
+    lng: Required[float]
+
+
+class GeocodeOptions(_GeocodeOptionsBase, total=False):
+    """All optional kwargs for :meth:`AppleMapsClient.geocode`."""
+
     lat: float
     lng: float
-    categories: str | Sequence[PoiCategory]
-    exclude_categories: str | Sequence[PoiCategory]
-    limit_to_countries: str
+
+
+# Location bias is optional; when set both lat and lng are required.
+# Overloads below enforce that for pyright; runtime asserts in _lat_lng_to_apple_str.
+class _SearchOptionsBase(TypedDict, total=False):
+    """Shared optional kwargs for :meth:`AppleMapsClient.search`.
+
+    Location params (all optional; different roles):
+
+    - ``lat`` / ``lng``: app-defined point hint; sent as Apple's
+      ``searchLocation`` (must pass both). Primary geographic bias —
+      "search near this map point".
+    - ``search_region``: app-defined bounding-box hint as :class:`MapRegion`.
+    - ``user_lat`` / ``user_lng``: the *user's* current position (must pass both).
+      Used for ranking/relevance; Search may fall back to it as
+      ``searchLocation`` when ``lat``/``lng`` are omitted.
+    """
+
+    categories: str | Sequence[str | PoiCategory]
+    exclude_categories: str | Sequence[str | PoiCategory]
+    limit_to_countries: str | Sequence[str]
     lang: str
-    result_type_filter: str | Sequence[SearchResultType]
-    search_region: str
-    user_location: str
-    search_region_priority: str
+    result_type_filter: str | Sequence[str | SearchResultType]
+    search_region: MapRegion
+    user_lat: float
+    user_lng: float
+    search_region_priority: SearchRegionPriority | str
     enable_pagination: bool
     page_token: str
-    include_address_categories: str | Sequence[AddressCategory]
-    exclude_address_categories: str | Sequence[AddressCategory]
-
-
-class AutocompleteOptions(TypedDict, total=False):
-    near: str | None
-    lat: float | None
-    lng: float | None
-    limit_to_countries: str | None
-    lang: str | None
-    result_type_filter: str | Sequence[SearchACResultType] | None
-    include_poi_categories: str | Sequence[PoiCategory] | None
-    exclude_poi_categories: str | Sequence[PoiCategory] | None
-    search_region: str | None
-    user_location: str | None
-    search_region_priority: str | None
-    include_address_categories: str | Sequence[AddressCategory] | None
-    exclude_address_categories: str | Sequence[AddressCategory] | None
+    include_address_categories: str | Sequence[str | AddressCategory]
+    exclude_address_categories: str | Sequence[str | AddressCategory]
+
+
+class SearchOptionsLatLng(_SearchOptionsBase, total=False):
+    """Search options with required ``lat`` and ``lng`` location bias."""
+
+    lat: Required[float]
+    lng: Required[float]
+
+
+class SearchOptions(_SearchOptionsBase, total=False):
+    """All optional kwargs for :meth:`AppleMapsClient.search`."""
+
+    lat: float
+    lng: float
+
+
+class _AutocompleteOptionsBase(TypedDict, total=False):
+    """Shared optional kwargs for :meth:`AppleMapsClient.autocomplete`.
+
+    Location params match search (see :class:`_SearchOptionsBase`):
+    ``lat``/``lng`` → ``searchLocation`` bias; ``search_region`` as MapRegion;
+    ``user_lat``/``user_lng`` is the user's position (ranking; may fall back as
+    ``searchLocation`` when lat/lng are omitted).
+    """
+
+    limit_to_countries: str | Sequence[str]
+    lang: str
+    result_type_filter: str | Sequence[str | SearchACResultType]
+    include_poi_categories: str | Sequence[str | PoiCategory]
+    exclude_poi_categories: str | Sequence[str | PoiCategory]
+    search_region: MapRegion
+    user_lat: float
+    user_lng: float
+    search_region_priority: SearchRegionPriority | str
+    include_address_categories: str | Sequence[str | AddressCategory]
+    exclude_address_categories: str | Sequence[str | AddressCategory]
+
+
+class AutocompleteOptionsLatLng(_AutocompleteOptionsBase, total=False):
+    """Autocomplete options with required ``lat`` and ``lng`` location bias."""
+
+    lat: Required[float]
+    lng: Required[float]
+
+
+class AutocompleteOptions(_AutocompleteOptionsBase, total=False):
+    """All optional kwargs for :meth:`AppleMapsClient.autocomplete`."""
+
+    lat: float
+    lng: float
 
 
 class AppleMapsClient:
@@ -355,17 +431,33 @@ class AppleMapsClient:
 
         return response.json()
 
+    @overload
+    def geocode(
+        self, query: str, **kwargs: Unpack[GeocodeOptionsLatLng]
+    ) -> PlaceResults: ...
+
+    @overload
+    def geocode(
+        self, query: str, **kwargs: Unpack[_GeocodeOptionsBase]
+    ) -> PlaceResults: ...
+
     def geocode(self, query: str, **kwargs: Unpack[GeocodeOptions]) -> PlaceResults:
         """Convert an address string to coordinates.
 
         Maps to GET /v1/geocode.
 
         :param query: Address to geocode (e.g., "1 Apple Park Way").
-        :param limit_to_countries: Comma-separated ISO 3166-1 alpha-2 country codes to limit results.
+        :param limit_to_countries: ISO 3166-1 alpha-2 country codes to limit results
+            (e.g. ``["US", "CA"]``).
         :param lang: BCP 47 language code (default: "en-US").
-        :param search_location: Lat/lng hint for search bias (e.g., "37.78,-122.42").
-        :param search_region: Bounding box hint as "northLat,eastLng,southLat,westLng".
-        :param user_location: User's current location as "lat,lng".
+        :param lat: Latitude for app-defined search bias (must pass with lng).
+            Sent as Apple's ``searchLocation``.
+        :param lng: Longitude for app-defined search bias (must pass with lat).
+        :param search_region: App-defined bounding-box hint as :class:`MapRegion`.
+        :param user_lat: Latitude of the user's position (must pass with user_lng).
+            Used for ranking/relevance; if ``lat``/``lng`` are omitted, some
+            endpoints may fall back to this as the search hint.
+        :param user_lng: Longitude of the user's position (must pass with user_lat).
         """
         if not query:
             raise ValueError("query must be provided.")
@@ -374,11 +466,17 @@ class AppleMapsClient:
             f.compact(
                 {
                     "q": query,
-                    "limitToCountries": kwargs.get("limit_to_countries"),
+                    "limitToCountries": _csv(kwargs.get("limit_to_countries")),
                     "lang": kwargs.get("lang"),
-                    "searchLocation": kwargs.get("search_location"),
-                    "searchRegion": kwargs.get("search_region"),
-                    "userLocation": kwargs.get("user_location"),
+                    "searchLocation": _lat_lng_to_apple_str(
+                        lat=kwargs.get("lat"),
+                        lng=kwargs.get("lng"),
+                    ),
+                    "searchRegion": _search_region(kwargs.get("search_region")),
+                    "userLocation": _lat_lng_to_apple_str(
+                        lat=kwargs.get("user_lat"),
+                        lng=kwargs.get("user_lng"),
+                    ),
                 }
             )
         )
@@ -388,70 +486,98 @@ class AppleMapsClient:
 
     def reverse_geocode(
         self,
-        coordinates: tuple[float, float] | Location,
-        **kwargs: Unpack[ReverseGeocodeOptions],
+        *,
+        lat: float,
+        lng: float,
+        lang: str | None = None,
     ) -> PlaceResults:
         """Convert coordinates to an address.
 
         Maps to GET /v1/reverseGeocode.
 
-        :param coordinates: (latitude, longitude) tuple or Location object.
+        :param lat: Latitude of the point to reverse geocode.
+        :param lng: Longitude of the point to reverse geocode.
         :param lang: BCP 47 language code (default: "en-US").
         """
-        if isinstance(coordinates, Location):
-            loc_str = f"{coordinates.latitude},{coordinates.longitude}"
-        else:
-            loc_str = f"{coordinates[0]},{coordinates[1]}"
-
-        params: dict[str, str] = dict(
-            f.compact({"loc": loc_str, "lang": kwargs.get("lang")})
-        )
+        params: dict[str, str] = dict(f.compact({"loc": f"{lat},{lng}", "lang": lang}))
 
         raw = self._make_request("/v1/reverseGeocode", params)
         return PlaceResults.model_validate(raw)
 
-    def search(self, query: str, **kwargs: Unpack[SearchOptions]) -> SearchResponse:
+    @overload
+    def search(
+        self, query: str, **kwargs: Unpack[SearchOptionsLatLng]
+    ) -> SearchResponse: ...
+
+    @overload
+    def search(
+        self, query: str = "", **kwargs: Unpack[_SearchOptionsBase]
+    ) -> SearchResponse: ...
+
+    def search(
+        self, query: str = "", **kwargs: Unpack[SearchOptions]
+    ) -> SearchResponse:
         """Search for places by name or category.
 
         Maps to GET /v1/search.
 
-        :param query: Search query (e.g., "coffee", "Apple Park").
-        :param near: Location bias as "lat,lng" (maps to searchLocation).
-            Mutually exclusive with lat/lng.
-        :param lat: Latitude for location bias (requires lng).
-        :param lng: Longitude for location bias (requires lat).
-        :param categories: Comma-separated POI categories to include (e.g., "MovieTheater").
-        :param exclude_categories: Comma-separated POI categories to exclude.
-        :param limit_to_countries: Comma-separated ISO 3166-1 alpha-2 country codes to limit results.
+        Location bias (optional): pass ``lat=`` and ``lng=`` together.
+
+        For page 2+, pass only ``page_token`` from a prior response's
+        ``paginationInfo.nextPageToken``. Apple rejects other search params
+        (including ``q`` and ``enablePagination``) on token requests.
+
+        :param query: Search query (e.g., "coffee", "Apple Park"). Required
+            unless ``page_token`` is set.
+        :param lat: Latitude for app-defined search bias (must pass with lng).
+            Sent as Apple's ``searchLocation`` — "search near this map point".
+        :param lng: Longitude for app-defined search bias (must pass with lat).
+        :param categories: POI categories to include (e.g. ``["MovieTheater", "Cafe"]``).
+        :param exclude_categories: POI categories to exclude (e.g. ``["Parking"]``).
+        :param limit_to_countries: ISO 3166-1 alpha-2 country codes
+            (e.g. ``["US", "CA"]``).
         :param lang: BCP 47 language code (default: "en-US").
-        :param result_type_filter: Comma-separated result types (e.g., "Poi", "Address").
-        :param search_region: Bounding box hint as "northLat,eastLng,southLat,westLng".
-        :param user_location: User's current location as "lat,lng".
-        :param search_region_priority: "default" or "required".
-        :param enable_pagination: Request paginated results.
-        :param page_token: Token identifying which page of results to return.
-        :param include_address_categories: Comma-separated AddressCategory values to include.
-        :param exclude_address_categories: Comma-separated AddressCategory values to exclude.
+        :param result_type_filter: Result types (e.g. ``["Poi", "Address"]``).
+        :param search_region: App-defined bounding-box hint as :class:`MapRegion`.
+        :param user_lat: Latitude of the user's position (must pass with user_lng).
+            Used for ranking/relevance; Search may fall back to it as
+            ``searchLocation`` when ``lat``/``lng`` are omitted.
+        :param user_lng: Longitude of the user's position (must pass with user_lat).
+        :param search_region_priority: Importance of ``search_region``
+            (:class:`SearchRegionPriority` or ``"default"`` / ``"required"``).
+        :param enable_pagination: Request paginated results (first page only).
+        :param page_token: Token from ``paginationInfo`` for a subsequent page.
+            When set, sent alone — do not combine with query or other filters.
+        :param include_address_categories: Address categories to include
+            (e.g. ``["AdministrativeArea"]``).
+        :param exclude_address_categories: Address categories to exclude.
         """
+        page_token = kwargs.get("page_token")
+        if page_token:
+            # Apple: pageToken requests must not include q, enablePagination, etc.
+            raw = self._make_request("/v1/search", {"pageToken": page_token})
+            return SearchResponse.model_validate(raw)
+
         if not query:
             raise ValueError("query must be provided.")
 
         raw_params: dict[str, object] = {
             "q": query,
-            "searchLocation": _search_location(
-                near=kwargs.get("near"),
+            "searchLocation": _lat_lng_to_apple_str(
                 lat=kwargs.get("lat"),
                 lng=kwargs.get("lng"),
             ),
             "includePoiCategories": _csv(kwargs.get("categories")),
             "excludePoiCategories": _csv(kwargs.get("exclude_categories")),
-            "limitToCountries": kwargs.get("limit_to_countries"),
+            "limitToCountries": _csv(kwargs.get("limit_to_countries")),
             "lang": kwargs.get("lang"),
             "resultTypeFilter": _csv(kwargs.get("result_type_filter")),
-            "searchRegion": kwargs.get("search_region"),
-            "userLocation": kwargs.get("user_location"),
+            "searchRegion": _search_region(kwargs.get("search_region")),
+            "userLocation": _lat_lng_to_apple_str(
+                lat=kwargs.get("user_lat"),
+                lng=kwargs.get("user_lng"),
+            ),
             "searchRegionPriority": kwargs.get("search_region_priority"),
-            "pageToken": kwargs.get("page_token"),
             "includeAddressCategories": _csv(kwargs.get("include_address_categories")),
             "excludeAddressCategories": _csv(kwargs.get("exclude_address_categories")),
         }
@@ -463,6 +589,16 @@ class AppleMapsClient:
         raw = self._make_request("/v1/search", params)
         return SearchResponse.model_validate(raw)
 
+    @overload
+    def autocomplete(
+        self, query: str, **kwargs: Unpack[AutocompleteOptionsLatLng]
+    ) -> SearchAutocompleteResponse: ...
+
+    @overload
+    def autocomplete(
+        self, query: str, **kwargs: Unpack[_AutocompleteOptionsBase]
+    ) -> SearchAutocompleteResponse: ...
+
     def autocomplete(
         self, query: str, **kwargs: Unpack[AutocompleteOptions]
     ) -> SearchAutocompleteResponse:
@@ -470,25 +606,32 @@ class AppleMapsClient:
 
         Maps to GET /v1/searchAutocomplete.
 
+        Location bias (optional): pass ``lat=`` and ``lng=`` together.
+
         Result count is fixed by Apple; the API has no limit/maxResults parameter.
         For more results, use search() (supports enable_pagination) or
         search_completion() to expand a single autocomplete hit.
 
         :param query: Partial address or place name to autocomplete.
-        :param near: Location bias as "lat,lng" to prefer nearby results.
-            Mutually exclusive with lat/lng.
-        :param lat: Latitude for location bias (requires lng).
-        :param lng: Longitude for location bias (requires lat).
-        :param limit_to_countries: Comma-separated ISO 3166-1 alpha-2 country codes to limit results.
+        :param lat: Latitude for app-defined search bias (must pass with lng).
+            Sent as Apple's ``searchLocation`` — "search near this map point".
+        :param lng: Longitude for app-defined search bias (must pass with lat).
+        :param limit_to_countries: ISO 3166-1 alpha-2 country codes
+            (e.g. ``["US", "CA"]``).
         :param lang: BCP 47 language code (default: "en-US").
-        :param result_type_filter: Comma-separated result types (e.g., "Address", "Poi").
-        :param include_poi_categories: Comma-separated POI categories to include.
-        :param exclude_poi_categories: Comma-separated POI categories to exclude.
-        :param search_region: Bounding box hint as "northLat,eastLng,southLat,westLng".
-        :param user_location: User's current location as "lat,lng".
-        :param search_region_priority: "default" or "required".
-        :param include_address_categories: Comma-separated AddressCategory values to include.
-        :param exclude_address_categories: Comma-separated AddressCategory values to exclude.
+        :param result_type_filter: Result types (e.g. ``["Address", "Poi"]``).
+        :param include_poi_categories: POI categories to include
+            (e.g. ``["Cafe"]``).
+        :param exclude_poi_categories: POI categories to exclude.
+        :param search_region: App-defined bounding-box hint as :class:`MapRegion`.
+        :param user_lat: Latitude of the user's position (must pass with user_lng).
+            Used for ranking/relevance; may fall back as ``searchLocation``
+            when ``lat``/``lng`` are omitted.
+        :param user_lng: Longitude of the user's position (must pass with user_lat).
+        :param search_region_priority: Importance of ``search_region``
+            (:class:`SearchRegionPriority` or ``"default"`` / ``"required"``).
+        :param include_address_categories: Address categories to include.
+        :param exclude_address_categories: Address categories to exclude.
         """
         if not query:
             raise ValueError("query must be provided.")
@@ -497,19 +640,21 @@ class AppleMapsClient:
             f.compact(
                 {
                     "q": query,
-                    "searchLocation": _search_location(
-                        near=kwargs.get("near"),
+                    "searchLocation": _lat_lng_to_apple_str(
                         lat=kwargs.get("lat"),
                         lng=kwargs.get("lng"),
                     ),
                     # Note: Apple maps documentation says to use 'limitToCountries' param but it seems to work only with almost full address
-                    "limitToCountries": kwargs.get("limit_to_countries"),
+                    "limitToCountries": _csv(kwargs.get("limit_to_countries")),
                     "lang": kwargs.get("lang"),
                     "resultTypeFilter": _csv(kwargs.get("result_type_filter")),
                     "includePoiCategories": _csv(kwargs.get("include_poi_categories")),
                     "excludePoiCategories": _csv(kwargs.get("exclude_poi_categories")),
-                    "searchRegion": kwargs.get("search_region"),
-                    "userLocation": kwargs.get("user_location"),
+                    "searchRegion": _search_region(kwargs.get("search_region")),
+                    "userLocation": _lat_lng_to_apple_str(
+                        lat=kwargs.get("user_lat"),
+                        lng=kwargs.get("user_lng"),
+                    ),
                     "searchRegionPriority": kwargs.get("search_region_priority"),
                     "includeAddressCategories": _csv(
                         kwargs.get("include_address_categories")

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/apple_maps_api/exceptions.py

@@ -1,14 +1,10 @@
 class AppleMapsError(Exception):
     """Base exception for all Apple Maps API errors."""
 
-    pass
-
 
 class AppleMapsAuthError(AppleMapsError):
     """Raised when authentication fails (e.g., invalid JWT, expired token)."""
 
-    pass
-
 
 class AppleMapsRequestError(AppleMapsError):
     """Raised when the API returns a client error (4xx besides 429)."""
@@ -22,8 +18,6 @@ class AppleMapsRequestError(AppleMapsError):
 class AppleMapsRateLimitError(AppleMapsRequestError):
     """Raised when the API returns a 429 Too Many Requests error."""
 
-    pass
-
 
 class AppleMapsServerError(AppleMapsError):
     """Raised when the API returns a 5xx server error."""

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/apple_maps_api/helpers.py

@@ -119,7 +119,7 @@ def geocode_coordinates(
         GeocodeResult with lat, lon, zip_code, city, and state information.
         Returns None if geocoding fails.
     """
-    location_result = client.reverse_geocode((lat, lon))
+    location_result = client.reverse_geocode(lat=lat, lng=lon)
 
     if len(location_result.results) == 0:
         _log_geocode_event(

{apple_maps_api-0.1.0 → apple_maps_api-0.2.1}/apple_maps_api/models.py

@@ -119,6 +119,16 @@ class SearchACResultType(StrEnum):
     query = "query"
 
 
+class SearchRegionPriority(StrEnum):
+    """Importance of searchRegion for /v1/search and /v1/searchAutocomplete.
+
+    Apple possible values: default, required.
+    """
+
+    default = "default"
+    required = "required"
+
+
 class Location(BaseModel):
     """A coordinate pair from Apple Maps API.
 
@@ -195,10 +205,11 @@ class Place(BaseModel):
 class SearchPlace(Place):
     """Extended Place returned by /v1/search with POI category info.
 
-    poiCategory: point-of-interest category (e.g. "Restaurant", "MovieTheater")
+    poiCategory: point-of-interest category (e.g. Restaurant, MovieTheater).
+    Unknown values from Apple fail validation so we notice and add support.
     """
 
-    poiCategory: str | None = None
+    poiCategory: PoiCategory | None = None
 
 
 class PlaceResults(BaseModel):
@@ -210,15 +221,31 @@ class PlaceResults(BaseModel):
     results: list[Place]
 
 
+class PaginationInfo(BaseModel):
+    """Pagination metadata from /v1/search when enablePagination is true.
+
+    nextPageToken / prevPageToken: opaque tokens for pageToken on the next request
+    totalPageCount: total pages available
+    totalResults: total matching results
+    """
+
+    nextPageToken: str | None = None
+    prevPageToken: str | None = None
+    totalPageCount: int | float | None = None
+    totalResults: int | float | None = None
+
+
 class SearchResponse(BaseModel):
     """Response from /v1/search.
 
     results: list of SearchPlace objects with optional POI category
     displayMapRegion: suggested map viewport encompassing all results
+    paginationInfo: present when the request set enablePagination
     """
 
     results: list[SearchPlace]
     displayMapRegion: MapRegion | None = None
+    paginationInfo: PaginationInfo | None = None
 
 
 class AutocompleteResult(BaseModel):

apple_maps_api-0.2.1/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "apple-maps-api"
+version = "0.2.1"
+description = "A modern Python client for the Apple Maps Server API with automatic JWT management and type safety"
+keywords = [
+    "apple-maps",
+    "geocoding",
+    "search",
+    "geolocation",
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.12.3",
+    "tenacity>=9.1.2",
+    "PyJWT[crypto]>=2.9.0",
+    "httpx2>=2.7.0",
+    "funcy>=2.0",
+]
+
+[[project.authors]]
+name = "Michael Bianco"
+email = "mike@mikebian.co"
+
+[project.urls]
+Repository = "https://github.com/iloveitaly/apple-maps-api"
+Documentation = "https://iloveitaly.github.io/python-apple-maps-api/"
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.pyright]
+exclude = [
+    "examples/",
+    "playground/",
+    "tmp/",
+    ".venv/",
+]
+reportCallIssue = "error"
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["apple_maps_api"]
+
+[tool.coverage.report]
+fail_under = 50
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.15",
+    "coverage>=7.14.1",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+    "pytest-httpx2>=1.0.0",
+]
+docs = [
+    "sphinx>=7.1.2",
+    "shibuya",
+    "myst-parser>=2.0.0",
+    "sphinx-design>=0.5.0",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-autobuild",
+    "sphinx-autoapi",
+    "sphinx-llm",
+]

apple_maps_api-0.1.0/pyproject.toml → apple_maps_api-0.2.1/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "apple-maps-api"
-version = "0.1.0"
+version = "0.2.1"
 description = "A modern Python client for the Apple Maps Server API with automatic JWT management and type safety"
 keywords = ["apple-maps", "geocoding", "search", "geolocation"]
 readme = "README.md"
@@ -14,10 +14,10 @@ dependencies = [
 ]
 
 authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
-urls = { "Repository" = "https://github.com/iloveitaly/apple-maps-api" }
+urls = { "Repository" = "https://github.com/iloveitaly/apple-maps-api", "Documentation" = "https://iloveitaly.github.io/python-apple-maps-api/" }
 
 [build-system]
-requires = ["uv_build>=0.11.17,<0.12"]
+requires = ["uv_build>=0.11.17,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -34,6 +34,17 @@ dev = [
     "covdefaults>=2.3.0",
     "pytest-httpx2>=1.0.0",
 ]
+# Sphinx toolchain for local/CI docs builds — not a published package extra
+docs = [
+    "sphinx>=7.1.2",
+    "shibuya",
+    "myst-parser>=2.0.0",
+    "sphinx-design>=0.5.0",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-autobuild",
+    "sphinx-autoapi",
+    "sphinx-llm",
+]
 
 [tool.pyright]
 exclude = ["examples/", "playground/", "tmp/", ".venv/"]