Maps

Codename One ships a modern mapping API in the com.codename1.maps package built around two components:

Both components implement the same MapSurface interface, so application code is identical regardless of which one — or which provider — is backing the map.

The pure-vector MapView renders real maps with zero configuration and no API key — by default it shows the free, keyless OpenFreeMap vector basemap (real OpenStreetMap data):

LatLng is the immutable WGS84 coordinate value type used throughout the API. The camera is described by a center LatLng and a fractional zoom level (the standard slippy-map scale where each whole increment doubles the scale).

Every map — vector or native — exposes the same operations through MapSurface:

Marker icons are supplied as EncodedImage and anchored in normalized (u, v) image space (0.5, 1.0 puts the pin tip on the location). When no icon is given, a marker draws the standard Material Design map pin. Polygon and circle fills accept an 0xAARRGGBB color so you can make them translucent.

A polyline joins the coordinates you hand it with straight lines — it knows nothing about roads. Passing two endpoints to addPolyline therefore draws a single straight segment across the map, which is seldom what a navigation screen wants. Working out the road geometry between two points is a separate job, done by a routing service, and that’s what the com.codename1.maps.routing package is for:

Routing.showRoute(…​) fetches the route, draws it and moves the camera to frame it. Like the keyless OpenFreeMap basemap, it works with no API key and no signup: routing runs over OpenStreetMap data through the built-in OsrmRouteService.

Routing is asynchronous — the call returns immediately and the line appears when the service answers. Use Routing.findRoute(…​) when you want the result itself, for example to style the line or show the distance and the estimated time:

A Route carries the drawable geometry (toPolyline()), the bounds to frame it with, the total distance and duration, and the RouteLeg/RouteStep breakdown behind a turn-by-turn list. A RouteRequest adds waypoints and a TravelMode (DRIVING, WALKING, CYCLING).

To route through a different provider entirely — Google Directions, Mapbox Directions, GraphHopper, your own server — implement RouteService and install it the same way. Every provider of that kind returns the route as an encoded polyline, which Polyline.fromEncoded(geometry) turns straight into something drawable (PolylineCodec also handles the polyline6 variant used by Valhalla).

MapView pulls its tiles from a pluggable com.codename1.maps.vector.TileSource:

For a real app you point MapView at a hosted tile service. The simplest keyless option is OpenFreeMap (OpenStreetMap-based vector tiles); for branded styles or higher quotas use a keyed provider such as MapTiler or your own self-hosted Protomaps/TileServer GL endpoint:

If the URL has no {z} token it’s treated as a TileJSON document and the real tile-URL template (and min/max zoom) are resolved from it automatically, so you can paste a provider’s TileJSON URL directly.

To bundle your own offline tiles instead, drop .mvt/.pbf files into the app’s resources under a {z}/{x}/{y} layout and point BundledTileSource at them — that’s exactly what the test fixtures do.

Vector tiles are painted according to a MapStyle. The built-in MapStyle.light() and MapStyle.dark() cover a usable basemap; MapStyle.fromJson(json) parses a subset of the MapLibre GL style specification (background/fill/line/symbol layers, zoom-stop interpolation, simple ["==", key, value] filters).

NativeMap renders through a native map SDK when the build wires one in:

Which provider (if any) backs the map is decided entirely by build hints — the public API never names a provider, so unused providers add nothing to your app’s size. Select one with the maps.provider build hint (or the per-platform ios.maps.provider / android.maps.provider):

The built-in providers are Apple MapKit (iOS), Google Maps (Android) and Huawei Map Kit (Android). Huawei Map Kit runs on any Android device with HMS Core installed — not only Huawei hardware — so it’s the natural choice for the Android market without Google Play Services. Each reports isAvailable() at runtime (Google checks Play Services, Huawei checks HMS Core), and when the selected provider is unavailable NativeMap falls back to the pure-vector MapView.

When a provider is selected the build server injects that provider’s implementation into your app and wires it in; with no provider selected (or when the provider is unavailable at runtime, for example when Google Play Services is missing) NativeMap simply renders the vector MapView fallback. You can configure the fallback basemap explicitly:

Apple MapKit needs no key. Google Maps requires the usual keys, supplied as build hints:

A native provider only renders on the platforms that ship its SDK. To show a provider’s map everywhere — including platforms with no native SDK for it — register a WebMapProvider, which hosts the provider’s JavaScript SDK inside a BrowserComponent. It draws the basemap and not much else, though: the camera getters report zero and markers, shapes, coordinate conversion and gestures are no-ops, so prefer it only where a static map is what you want:

Because it needs only a web view, the web provider (id web) is the natural last step before the pure-vector fallback in a provider chain. The order is fully customizable from code, so you can express per-platform preferences — for example "try the native Google SDK, then the web map, then the vector `MapView`":

Use MapView when you want a lightweight, dependency-free map that looks the same everywhere and composes with CN1 components. Use NativeMap when you want the platform’s native map look, gestures and performance, and are willing to opt a provider in through build hints — with the guarantee that it still works (as a vector map) where the provider is unavailable.