A source of map tiles.
A source turns a tile into image bytes with fetch/2 and describes its tiles with
info/1. Both receive the options given alongside the module, as in
source: {MyApp.Tiles, api_key: "…"}, or [] when the source is a bare module.
info/1
:attribution— the credit the tiles' licence requires, drawn on every image:tile_size— 256 or 512, the pixel size of a tile at scale 1:zoom— the range of tile zooms the source serves:scales— the pixel densities it has tiles for; always includes 1:max_concurrency— optional; how many fetches from this source may run at once across every render in the node, default 8:cache— optional;falsekeeps this source's tiles out of theStaticMaps.TileCacheentirely, including as stale copies when the server fails. Defaults totrue. Several commercial providers forbid server-side caching.
:zoom is in the source's own terms. A 512-pixel source's tile zoom z serves render
zoom z + 1, so its render zooms are its range shifted up by one.
Summary
Types
How long a response may be cached: :max_age in seconds, :no_store, or nil when
the response does not say, and the validators to revalidate it with once it expires.
The tile to fetch. :scale is 2 only for a source that lists it in :scales.
Validators from an earlier response, for a conditional request.
Callbacks
Returns the encoded image for tile, tile_size * scale pixels on a side.
Fetches tile conditionally, saying how long the result may be cached.
Describes the source's tiles.
Types
@type cache_meta() :: %{ max_age: non_neg_integer() | :no_store | nil, etag: String.t() | nil, last_modified: String.t() | nil }
How long a response may be cached: :max_age in seconds, :no_store, or nil when
the response does not say, and the validators to revalidate it with once it expires.
With nil, a new tile is kept for 7 days, and a 304 keeps the lifetime of the tile
it renews.
@type info() :: %{ :attribution => String.t(), :tile_size => 256 | 512, :zoom => Range.t(), :scales => [1 | 2], optional(:max_concurrency) => pos_integer(), optional(:cache) => boolean() }
@type tile() :: %{ z: non_neg_integer(), x: non_neg_integer(), y: non_neg_integer(), scale: 1 | 2 }
The tile to fetch. :scale is 2 only for a source that lists it in :scales.
Validators from an earlier response, for a conditional request.
Callbacks
Returns the encoded image for tile, tile_size * scale pixels on a side.
@callback fetch_cacheable(tile(), opts :: keyword(), validators()) :: {:ok, binary(), cache_meta()} | {:not_modified, cache_meta()} | {:error, term()}
Fetches tile conditionally, saying how long the result may be cached.
Optional. A source that implements it has its tiles kept in the StaticMaps.TileCache;
every StaticMaps.Source.HTTP source does. validators come from the cached copy, if
there is one; {:not_modified, meta} means that copy is still good.
Describes the source's tiles.