Rover.Tiles (Rover v0.9.0)

Copy Markdown View Source

Named basemaps, and the escape hatches to any raster or vector tile server.

Pass one to Rover.Components.map/1:

<.map id="m" tiles={:carto_light} ... />
<.map id="m" tiles={{:xyz, "https://tiles.example.com/{z}/{x}/{y}.png"}} ... />
<.map id="m" tiles={{:xyz, url, attributions: "© Example", max_zoom: 18}} ... />
<.map id="m" tiles={:carto_light_vector} ... />
<.map id="m" tiles={{:vector, "https://example.com/style.json"}} ... />

Every preset carries the attribution its provider requires, and Rover renders it in the map's attribution control. Removing it is usually a licence violation — OpenStreetMap tiles in particular are free, but not unconditional. Both OSM and Carto presets point at public demo servers with usage policies that forbid heavy traffic; for anything beyond development, point {:xyz, …} at tiles you are entitled to use.

Carto API keys

Carto's basemaps now need an API key. Without one the tiles still load — they arrive with API KEY REQUIRED stamped diagonally across every one, so the symptom is a legible map wearing a watermark rather than a blank map or an error in the console. That is worth knowing before you go looking for a 401 that never comes.

The key is free: Carto issue it by return email, with no approval queue and no Carto account, and it covers 5 million tile requests a month across their raster and vector services. Their terms require the CARTO and OpenStreetMap attribution to stay visible, which Rover renders for you. Request one at https://carto.com/basemaps/apikey/.

Configure a default for the whole app:

config :rover, Rover.Tiles, carto_api_key: "YOUR_KEY"

or pass one per call, which overrides the configured default:

<.map id="m" tiles={{:carto_dark, key: "YOUR_KEY"}} ... />

Carto is retiring these raster endpoints in favor of vector tiles (MapLibre- style GL JSON served as MVT); :carto_light, :carto_dark, and :carto_voyager keep working for existing configurations, but a new caller should reach for their vector counterparts instead:

<.map id="m" tiles={:carto_light_vector} ... />

:carto_light_vector, :carto_dark_vector, and :carto_voyager_vector take the same carto_api_key configuration and per-call key: opt described above. For any other MapLibre-compatible style (Mapbox, MapTiler, self-hosted), pass its style URL directly:

<.map id="m" tiles={{:vector, "https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY"}} ... />

Raster stays fully supported — it is not being removed — but it is the deprecated path for the three Carto presets above.

France

:ign_plan and :ign_ortho serve the French Géoportail — the reference plan and the aerial orthophotography, both open data and both intended for production use, which is what sets them apart from the demo endpoints above. :ign_ortho over a field is a different conversation with a grower than a road map is.

<.map id="parcels" tiles={:ign_ortho} shapes={@parcels} />

Summary

Types

preset()
t()

Functions

presets()

The list of available preset names.

resolve!(name)

Resolves a tile specification into the map handed to the JavaScript runtime.

Types

preset()

@type preset() ::
  :osm
  | :osm_hot
  | :carto_light
  | :carto_dark
  | :carto_voyager
  | :opentopomap
  | :esri_world_imagery
  | :ign_plan
  | :ign_ortho
  | :carto_light_vector
  | :carto_dark_vector
  | :carto_voyager_vector

t()

@type t() ::
  preset()
  | {preset(), keyword()}
  | :none
  | {:xyz, String.t()}
  | {:xyz, String.t(), keyword()}
  | {:vector, String.t()}
  | {:vector, String.t(), keyword()}
  | {:wmts, String.t(), keyword()}

Functions

presets()

@spec presets() :: [preset()]

The list of available preset names.

Examples

iex> :carto_dark in Rover.Tiles.presets()
true

resolve!(name)

@spec resolve!(t()) :: map() | nil

Resolves a tile specification into the map handed to the JavaScript runtime.

Returns nil for :none, which renders a map with no basemap at all — useful when you only want the vector layers, or supply your own background.

Examples

iex> Rover.Tiles.resolve!(:osm).max_zoom
19

iex> Rover.Tiles.resolve!({:xyz, "https://x/{z}/{x}/{y}.png", attributions: "© Me"})
%{type: :raster, attributions: "© Me", max_zoom: 19, url: "https://x/{z}/{x}/{y}.png"}

iex> Rover.Tiles.resolve!(:carto_light_vector).type
:vector

iex> Rover.Tiles.resolve!({:vector, "https://example.com/style.json"})
%{type: :vector, attributions: nil, max_zoom: 24, style_url: "https://example.com/style.json"}

iex> Rover.Tiles.resolve!({:wmts, "https://example.com/wmts", layer: "ORTHO"}).layer
"ORTHO"

iex> Rover.Tiles.resolve!(:none)
nil