Skip to content

fix(frontend): replace watermarked CARTO basemap with Esri Gray Canvas - #1034

Merged
eetu merged 1 commit into
mainfrom
fix/esri-basemap
Sep 2, 2026
Merged

eetu merged 1 commit into
mainfrom
fix/esri-basemap

Conversation

@eetu

@eetu eetu commented Sep 2, 2026

Copy link
Copy Markdown
Owner

Problem

CARTO now requires an API key for basemaps.cartocdn.com. Keyless requests still return HTTP 200, so nothing looked broken in logs, but the tiles come back with an "API KEY REQUIRED" watermark burned into the PNG. The rain map has been rendering that across the viewport.

Reproduced directly:

curl -s -o t.png https://a.basemaps.cartocdn.com/dark_all/5/16/9.png   # 200, 8524 bytes, watermarked

A CARTO key is free (5M tiles/month, no CARTO account) but the request form wants a domain and halo is LAN-only. CARTO also states the raster PNG tier is being retired, so getting a key would just defer the work.

Change

Swapped the basemap to Esri Gray Canvas. Keyless, matching dark and light variants, no new dependencies. Everything is in frontend/src/components/RainMap.tsx; nothing else in the repo referenced CARTO.

Two things differ from CARTO and drive the shape of the diff:

  • Canvas splits geometry and place labels into separate services, so the base-layer effect builds two layers instead of one. The labels layer gets a dedicated pane at z-index 450, above overlayPane so the 0.6-opacity precipitation wash doesn't smear the place names, below markerPane so it doesn't bury the home marker. The pane is created in the map lifecycle effect so it survives theme swaps.
  • No {s} subdomains, path is {z}/{y}/{x} with y before x, and there is no @2x tile. detectRetina replaces the old {r} suffix, fetching one zoom deeper on hidpi screens so the wall panel stays sharp.

Attribution updated to Esri, HERE, Garmin, OpenStreetMap. The FMI credit is unchanged.

Verification

  • yarn typecheck, yarn lint, yarn format all pass.
  • All four tile services return 200 at zoom 11 and zoom 19, base as image/jpeg and reference as image/png.

Not yet checked in a browser. Worth confirming the theme toggle swaps both layers cleanly and that labels stay legible over the precipitation wash.

Known tradeoff

Esri deprecated this endpoint for open-source clients in 2022, and its current terms point at a free ArcGIS account plus an API key. It serves fine today, and the swap is confined to a single URL template so replacing it later is a small edit.

Keyless fallbacks, both investigated:

  • OpenFreeMap (tiles.openfreemap.org/styles/{positron,dark}) — the only provider with an explicit no-key, no-registration, no-limit policy. Vector, so it would cost maplibre-gl plus the Leaflet bridge and needs WebGL2 on the display.
  • OpenStreetMap standard tiles with a CSS filter on the layer's own container div for tone. Policy-clean at this volume, but one colorful style that filters imperfectly.

CARTO now requires an API key for basemaps.cartocdn.com. Keyless requests
still return HTTP 200, so nothing appeared broken, but the tiles come back
with an "API KEY REQUIRED" watermark burned into the PNG — the rain map has
been rendering that across the whole viewport.

A CARTO key is free (5M tiles/month, no account needed), but the request
form wants a domain and halo is LAN-only, and CARTO says the raster PNG
tier is being retired. Moving off it is the better fix.

Esri's Gray Canvas is keyless, has matching dark and light variants, and
needs no new dependencies. Two differences from CARTO worth noting:

- Canvas splits geometry and place labels into separate services, so the
  base-layer effect now builds two layers. The labels get a dedicated pane
  at z-index 450 — above overlayPane so the 0.6-opacity precipitation wash
  doesn't smear them, below markerPane so they don't bury the home marker.
- No {s} subdomains, the tile path is {z}/{y}/{x} with y before x, and
  there is no @2x tile, so detectRetina replaces the old {r} suffix.

Attribution updated to Esri, HERE, Garmin, OpenStreetMap. The FMI credit
is unchanged.

Caveat: Esri deprecated this endpoint for open-source clients in 2022 and
its terms now point at a free ArcGIS account plus a key. It serves fine
today and the swap is confined to one URL template, so replacing it later
is a small edit. OpenFreeMap (vector, explicitly no-key) and filtered OSM
standard tiles are the keyless fallbacks if it goes away.
@eetu
eetu enabled auto-merge (squash) September 2, 2026 20:34
@eetu
eetu merged commit 2e17e04 into main Sep 2, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant