You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Map card: support a custom basemap where the OSMF tiles are unreachable
#55729
Map card: support a custom basemap where the OSMF tiles are unreachable
Summary
In mainland China the basemap the map card now uses often cannot be reached from the Home Assistant server, so the built-in map renders an empty background. map_style only changes the cartography, and map_tiles hardcodes its upstream. I would like to propose a generic, opt-in extension point for a custom basemap (self-hosted style or TileJSON), instead of a region-specific provider.
Current behaviour
map_tiles proxies vector.openstreetmap.org (vector tiles), tile.openstreetmap.org (raster fallback) and the glyphs/sprites, behind a rotating token (/api/map_tiles/...), an in-memory cache and a fixed User-Agent.
hui-map-card exposes map_style as a fixed set — default, colorful, natural, muted, gray, toner, neon. There is no way to point the card at another style or tile source.
In China, vector.openstreetmap.org is frequently unreachable (network and regulatory reasons). The card then shows a blank/solid basemap; entities, markers and zones still load, only the base map is missing.
Reproduction
Run Home Assistant on a network where vector.openstreetmap.org is unreachable (a mainland China server is enough).
Add the built-in Map card (type: map) to a dashboard.
The card renders without a basemap. Changing map_style does not help, because all styles are built on the same tiles.
Proposal (generic, not China-specific)
Add an opt-in way to supply a basemap style. Default remains exactly as today. Two possible shapes:
A. Card level — map_style_url
An optional MapLibre style JSON or TileJSON URL, fetched by the browser, used only by that card. No server-side fetch, no change to map_tiles, no new security surface on the instance.
B. Instance level
An admin setting that points the existing proxy at a style/TileJSON URL, so caching and headers stay server-side. This needs an allowlist / SSRF policy and defined cache keys, and raises the question of who is responsible for the upstream's terms of use.
I would lean towards A as the smallest and lowest-risk change; B only if maintainers prefer that all tile traffic keeps going through the instance.
Out of scope
No specific commercial provider is proposed here.
Datum shifts (for example GCJ-02) are not proposed for core. If a user-chosen style uses a shifted datum, markers drawn from WGS84 coordinates will not align with the basemap. That needs its own opt-in transform and is a separate discussion.
Proof of concept
ha-map-cn (a HACS custom card) already validates the approach: browser-side raster tiles, the same entity/zone rendering, about 160 KB of native ES modules with no build step. It is a full custom card, though; the proposal here is only the extension point in the official card.
Impact
Opt-in, default unchanged.
Styles can be raster or vector, so the existing raster fallback path can be reused.
The editor gains one optional field; docs need a note on reachability (browser for A, instance for B).
Questions for maintainers
Is a card-level custom style URL acceptable, or should all tile access stay proxied through the instance?
If proxied: what allowlist / SSRF policy, cache key and upstream terms-of-use handling would be expected?
Is a datum-shift option explicitly out of scope for core?
Happy to prepare the PRs (frontend config + editor + tests, and the core changes if option B is preferred) once the direction is agreed.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Map card: support a custom basemap where the OSMF tiles are unreachable
Summary
In mainland China the basemap the map card now uses often cannot be reached from the Home Assistant server, so the built-in map renders an empty background.
map_styleonly changes the cartography, andmap_tileshardcodes its upstream. I would like to propose a generic, opt-in extension point for a custom basemap (self-hosted style or TileJSON), instead of a region-specific provider.Current behaviour
map_tilesproxiesvector.openstreetmap.org(vector tiles),tile.openstreetmap.org(raster fallback) and the glyphs/sprites, behind a rotating token (/api/map_tiles/...), an in-memory cache and a fixedUser-Agent.hui-map-cardexposesmap_styleas a fixed set —default,colorful,natural,muted,gray,toner,neon. There is no way to point the card at another style or tile source.vector.openstreetmap.orgis frequently unreachable (network and regulatory reasons). The card then shows a blank/solid basemap; entities, markers and zones still load, only the base map is missing.Reproduction
vector.openstreetmap.orgis unreachable (a mainland China server is enough).type: map) to a dashboard.map_styledoes not help, because all styles are built on the same tiles.Proposal (generic, not China-specific)
Add an opt-in way to supply a basemap style. Default remains exactly as today. Two possible shapes:
A. Card level —
map_style_urlAn optional MapLibre style JSON or TileJSON URL, fetched by the browser, used only by that card. No server-side fetch, no change to
map_tiles, no new security surface on the instance.B. Instance level
An admin setting that points the existing proxy at a style/TileJSON URL, so caching and headers stay server-side. This needs an allowlist / SSRF policy and defined cache keys, and raises the question of who is responsible for the upstream's terms of use.
I would lean towards A as the smallest and lowest-risk change; B only if maintainers prefer that all tile traffic keeps going through the instance.
Out of scope
Proof of concept
ha-map-cn (a HACS custom card) already validates the approach: browser-side raster tiles, the same entity/zone rendering, about 160 KB of native ES modules with no build step. It is a full custom card, though; the proposal here is only the extension point in the official card.
Impact
Questions for maintainers
Happy to prepare the PRs (frontend config + editor + tests, and the core changes if option B is preferred) once the direction is agreed.
All reactions