Bubble Map
Signature
sp.bubble_map(title, labels=None, values=None, *, variant="proportional", map="world", region=None, center_lat=None, center_lon=None, **kwargs) -> Chart
Aliases: sp.bubble_map, sp.bubblemap, sp.bubble_map_chart, sp.geo_bubble, sp.geo_bubble_map, sp.build_bubble_map
Description
sp.bubble_map() marks matched regions on a map with a proportionally-sized circle at each centroid by default — real bubbles, not filled shapes; pick variant="filled" instead when it’s the regions themselves the reader should compare, not a magnitude. map selects which registered geographic region set to draw; region optionally restricts drawing to one named group inside that set. All three are read live from the same register/inventory system the rest of the framework uses — nothing below is hardcoded.
Variants
Region Sets
Parameters
Returns
Chart — object with .html property and .show() method.
The default, and the real graduated-symbol map: the base is muted, and a circle sits on each matched region’s centroid, its radius scaled by sqrt(value) so area — not radius — reads proportionally to magnitude. min_bubble_size / max_bubble_size set the radius range in pixels.
Not a bubble at all by design: each matched region filled solid with its own palette color and labeled at its centroid — a categorical highlight map, for when it’s the regions themselves the reader should compare rather than a magnitude. Reach for choropleth instead if the fill color should encode a continuous value.
Proportional circles projected onto an orthographic sphere — every centroid is converted to real latitude/longitude and re-projected with actual globe math, so bubbles on the far side simply aren’t drawn. center_lat / center_lon aim the view (default 15, 10). Only region sets that expose a coordinate inversion support this — today, "world".
A hollow circle instead of a filled one — stroke-width carries the magnitude, not just radius, so a thin ring reads small and a thick ring reads large even where two circles overlap and one would otherwise hide behind the other.
Two faint concentric rings behind the solid marker, fading out with distance — a static radar-ping look, well suited to data that reads as an alert or a hotspot rather than a plain quantity.
A density map, not a values map: pass raw lats/lons samples instead of labels/values and each point is binned into a hexagonal grid — real axial hex-coordinate binning with cube-coordinate rounding, the same technique a proper geographic hexbin uses, not a nearest-center search. Each hexagon is sized and colored by how many samples landed inside it, with the count itself labeled once a cell holds more than one.