apple_maps_api.models

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

Classes

AddressCategory	Enum where members are also (and must be) strings
PoiCategory	Enum where members are also (and must be) strings
SearchResultType	Result type filter for /v1/search.
SearchACResultType	Result type filter for /v1/searchAutocomplete.
SearchRegionPriority	Importance of searchRegion for /v1/search and /v1/searchAutocomplete.
Location	A coordinate pair from Apple Maps API.
StructuredAddress	Detailed address components of a place.
MapRegion	A rectangular bounding box on a map.
Place	A place returned by geocode, reverseGeocode, or place lookup endpoints.
SearchPlace	Extended Place returned by /v1/search with POI category info.
PlaceResults	Response from /v1/geocode and /v1/reverseGeocode.
PaginationInfo	Pagination metadata from /v1/search when enablePagination is true.
SearchResponse	Response from /v1/search.
AutocompleteResult	A single autocomplete suggestion from /v1/searchAutocomplete.
SearchAutocompleteResponse	Response from /v1/searchAutocomplete.
TokenResponse	Response from /v1/token.
GeocodeResult	Provider-agnostic geocode result.

Module Contents

class apple_maps_api.models.AddressCategory

Bases: enum.StrEnum

Enum where members are also (and must be) strings

Country = 'Country'

AdministrativeArea = 'AdministrativeArea'

SubAdministrativeArea = 'SubAdministrativeArea'

Locality = 'Locality'

SubLocality = 'SubLocality'

PostalCode = 'PostalCode'

class apple_maps_api.models.PoiCategory

Bases: enum.StrEnum

Enum where members are also (and must be) strings

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 apple_maps_api.models.SearchResultType

Bases: enum.StrEnum

Result type filter for /v1/search.

poi = 'poi'

address = 'address'

physicalFeature = 'physicalFeature'

pointOfInterest = 'pointOfInterest'

class apple_maps_api.models.SearchACResultType

Bases: enum.StrEnum

Result type filter for /v1/searchAutocomplete.

poi = 'poi'

address = 'address'

physicalFeature = 'physicalFeature'

pointOfInterest = 'pointOfInterest'

query = 'query'

class apple_maps_api.models.SearchRegionPriority

Bases: enum.StrEnum

Importance of searchRegion for /v1/search and /v1/searchAutocomplete.

Apple possible values: default, required.

default = 'default'

required = 'required'

class apple_maps_api.models.Location(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.StructuredAddress(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.MapRegion(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.Place(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.SearchPlace(/, **data: Any)

Bases: Place

Extended Place returned by /v1/search with POI category info.

poiCategory: point-of-interest category (e.g. Restaurant, MovieTheater). Unknown values from Apple fail validation so we notice and add support.

poiCategory: PoiCategory | None = None

class apple_maps_api.models.PlaceResults(/, **data: Any)

Bases: pydantic.BaseModel

Response from /v1/geocode and /v1/reverseGeocode.

results: list of Place objects matching the query

results: list[Place]

class apple_maps_api.models.PaginationInfo(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.SearchResponse(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.AutocompleteResult(/, **data: Any)

Bases: pydantic.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 completionTitle: str | None

Primary display text (e.g. place name or street address).

property completionSubtitle: str | None

Secondary display text (e.g. city, state).

class apple_maps_api.models.SearchAutocompleteResponse(/, **data: Any)

Bases: pydantic.BaseModel

Response from /v1/searchAutocomplete.

results: list of autocomplete suggestions

results: list[AutocompleteResult]

class apple_maps_api.models.TokenResponse(/, **data: Any)

Bases: pydantic.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 apple_maps_api.models.GeocodeResult(/, **data: Any)

Bases: pydantic.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