Maps¶

The MapView component shows a native map with markers and polylines passed as typed data. See the Maps guide for setup and platform differences.

Maps: a native map view with markers and polylines.

Enable it in pythonnative.toml:

[plugins]
use = ["maps"]

# Android only. Or leave this out and set GOOGLE_MAPS_API_KEY when building.
[plugins.maps]
android_api_key = "..."

iOS uses MapKit and needs no key. Android uses the Google Maps SDK, which needs an API key and Google Play services on the device. Without either, the view shows a message saying so and calls on_error; the app keeps running.

Example

import pythonnative as pn
from pythonnative.maps import Coordinate, MapView, Marker, Region

OSLO = Coordinate(59.9139, 10.7522)

@pn.component
def Stores() -> pn.Node:
    chosen, set_chosen = pn.use_state(None)
    return pn.Column(
        MapView(
            initial_region=Region(OSLO, 0.05, 0.05),
            markers=[Marker("oslo", OSLO, title="Oslo")],
            on_marker_press=set_chosen,
            style=pn.style(flex=1),
        ),
        pn.Text(chosen or "Pick a store"),
    )

Classes:

Name	Description
`Coordinate`	A point on Earth.
`Region`	The rectangle a map shows.
`Marker`	A pin on the map.
`Polyline`	A line through a list of coordinates.
`MapHandle`	Handle a `ref` on `MapView` receives.

Functions:

Name	Description
`MapView`	Show a native map: MapKit on iOS, Google Maps on Android.

Attributes:

Name	Type	Description
`MapType`		The base map: streets, imagery, or imagery with streets and labels.

MapType `module-attribute` ¶

MapType = Literal['standard', 'satellite', 'hybrid']

The base map: streets, imagery, or imagery with streets and labels.

Coordinate `dataclass` ¶

Coordinate(latitude: float, longitude: float)

A point on Earth.

Attributes:

Name	Type	Description
`latitude`	`float`	Degrees north, from -90 to 90.
`longitude`	`float`	Degrees east, from -180 to 180.

Region `dataclass` ¶

Region(
    center: Coordinate,
    latitude_delta: float,
    longitude_delta: float,
)

The rectangle a map shows.

A map adjusts the region it's given to fit its own shape and zoom levels, so the region on_region_change reports is close to, but rarely equal to, the one requested.

Attributes:

Name	Type	Description
`center`	`Coordinate`	The middle of the rectangle.
`latitude_delta`	`float`	Its height in degrees of latitude.
`longitude_delta`	`float`	Its width in degrees of longitude.

Marker `dataclass` ¶

Marker(
    id: str,
    coordinate: Coordinate,
    title: Optional[str] = None,
    description: Optional[str] = None,
    color: Optional[str] = None,
)

A pin on the map.

Attributes:

Name	Type	Description
`id`	`str`	Identifies the marker across renders and in `on_marker_press`.
`coordinate`	`Coordinate`	Where it sits.
`title`	`Optional[str]`	The callout's title.
`description`	`Optional[str]`	The callout's second line.
`color`	`Optional[str]`	A hex color string for the pin. Google Maps pins take their hue from it, so Android keeps the hue and drops the saturation and brightness.

Polyline `dataclass` ¶

Polyline(
    id: str,
    coordinates: Sequence[Coordinate],
    color: Optional[str] = None,
    width: float = 2,
)

A line through a list of coordinates.

Attributes:

Name	Type	Description
`id`	`str`	Identifies the line across renders.
`coordinates`	`Sequence[Coordinate]`	The points it passes through, in order.
`color`	`Optional[str]`	A hex color string. Defaults to the platform's blue.
`width`	`float`	Stroke width in logical pixels.

MapViewProps `dataclass` ¶

MapViewProps(
    region: Optional[Region] = None,
    initial_region: Optional[Region] = None,
    markers: Sequence[Marker] = (),
    polylines: Sequence[Polyline] = (),
    shows_user_location: bool = False,
    map_type: MapType = "standard",
    zoom_enabled: bool = True,
    scroll_enabled: bool = True,
    accessibility_label: Annotated[
        Optional[str], NativeField()
    ] = None,
    test_id: Annotated[Optional[str], NativeField()] = None,
    on_region_change: Optional[
        Callable[[Region], Any]
    ] = None,
    on_marker_press: Optional[Callable[[str], Any]] = None,
    on_press: Optional[Callable[[Coordinate], Any]] = None,
    on_ready: Optional[Callable[[], Any]] = None,
    on_error: Optional[Callable[[str], Any]] = None,
)

Bases: Props

The wire contract of MapView.

MapHandle ¶

MapHandle(tag: int, type_name: str, backend: Any)

Bases: ViewHandle

Handle a ref on MapView receives.

Example

import pythonnative as pn
from pythonnative.maps import Coordinate, MapView, Region

@pn.component
def Home() -> pn.Node:
    map_ref = pn.use_ref()
    home = Region(Coordinate(59.91, 10.75), 0.02, 0.02)
    return pn.Column(
        MapView(ref=map_ref, initial_region=home, style=pn.style(height=240)),
        pn.Button("Home", on_press=lambda: map_ref.current.animate_to(home)),
    )

Methods:

Name	Description
`animate_to`	Move the map to `region` with the platform's animation.

animate_to ¶

animate_to(region: Region) -> None

Move the map to region with the platform's animation.

Parameters:

Name	Type	Description	Default
`region`	`Region`	Where to go. `on_region_change` fires when it arrives.	required

MapView ¶

MapView(
    *,
    region: Optional[Region] = None,
    initial_region: Optional[Region] = None,
    markers: Sequence[Marker] = (),
    polylines: Sequence[Polyline] = (),
    shows_user_location: bool = False,
    map_type: MapType = "standard",
    zoom_enabled: bool = True,
    scroll_enabled: bool = True,
    on_region_change: Optional[
        Callable[[Region], Any]
    ] = None,
    on_marker_press: Optional[Callable[[str], Any]] = None,
    on_press: Optional[Callable[[Coordinate], Any]] = None,
    on_ready: Optional[Callable[[], Any]] = None,
    on_error: Optional[Callable[[str], Any]] = None,
    accessibility_label: Optional[str] = None,
    test_id: Optional[str] = None,
    style: StyleProp = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Show a native map: MapKit on iOS, Google Maps on Android.

A map has no intrinsic size, so give it one with style, such as pn.style(flex=1) or pn.style(height=240). Passing a ref publishes a MapHandle on ref.current.

Parameters:

Name	Type	Description	Default
`region`	`Optional[Region]`	The region to show, controlled. Each change moves the map without animating. To follow the user's panning, store what `on_region_change` reports and pass it back. A region within a rounding error of the current one is ignored, so this can't loop.	`None`
`initial_region`	`Optional[Region]`	The region to start on, uncontrolled. Later changes are ignored. `region` wins when both are set.	`None`
`markers`	`Sequence[Marker]`	The pins, as data rather than child elements.	`()`
`polylines`	`Sequence[Polyline]`	The lines, as data rather than child elements.	`()`
`shows_user_location`	`bool`	Draw the user's position. The app must already have location permission, which this doesn't ask for: enable the `location` capability and call `Permissions.request("location_when_in_use")` first. Without the permission, Android calls `on_error` and tries again the next time the app resumes, and iOS draws nothing.	`False`
`map_type`	`MapType`	The base map.	`'standard'`
`zoom_enabled`	`bool`	Whether the user can zoom.	`True`
`scroll_enabled`	`bool`	Whether the user can pan.	`True`
`on_region_change`	`Optional[Callable[[Region], Any]]`	Called with the new `Region` when the map stops moving, however it was moved.	`None`
`on_marker_press`	`Optional[Callable[[str], Any]]`	Called with a marker's `id`. On iOS, pressing a marker that's already selected doesn't fire it again.	`None`
`on_press`	`Optional[Callable[[Coordinate], Any]]`	Called with the `Coordinate` pressed on the map itself, not on a marker.	`None`
`on_ready`	`Optional[Callable[[], Any]]`	Called once, when the map can be controlled.	`None`
`on_error`	`Optional[Callable[[str], Any]]`	Called with a message when the map can't work: on Android, no API key, no Google Play services, or no location permission for `shows_user_location`; on iOS, map data that failed to load. A wrong Android API key isn't reported: the SDK only logs it and draws an empty map.	`None`
`accessibility_label`	`Optional[str]`	Screen reader label for the map.	`None`
`test_id`	`Optional[str]`	Identifier for UI tests.	`None`
`style`	`StyleProp`	Layout and visual style.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity among siblings.	`None`

Returns:

Type	Description
`Element`	The map element.

Raises:

Type	Description
`PluginNotEnabledError`	On a device whose build doesn't include `maps`.

Maps¶

MapType module-attribute ¶

Coordinate dataclass ¶

Region dataclass ¶

Marker dataclass ¶

Polyline dataclass ¶

MapViewProps dataclass ¶

MapHandle ¶

animate_to ¶

MapView ¶

MapType `module-attribute` ¶

Coordinate `dataclass` ¶

Region `dataclass` ¶

Marker `dataclass` ¶

Polyline `dataclass` ¶

MapViewProps `dataclass` ¶