Render map

Previous value: -"Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result."New value: +"Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result. Do send `kind` whenever you know what the numbers are, `midpoint` when they have a meaningful center, and a short `unit`: the values alone cannot tell 42% from 0.42 or a change from a level."

Previous value: -"Number format for every choropleth surface: class labels, gradient ticks and value labels. Always pass an object, e.g. {\"preset\": \"compact\"}, never a bare string. Presets: `auto` (default, inferred from magnitude), `plain` (39,538,223), `compact` (39.5M), `percent` (the input is a FRACTION, so 0.42 prints as 42% and 0.423 as 42.3%, because the preset trims trailing zeros. An explicit {\"style\": \"percent\", \"decimals\": 1} keeps them and prints 42.0%. For data already in percent points use {\"suffix\": \"%\"}), `currency` ($39,538,223). Or combine options, e.g. {\"decimals\": 1, \"suffix\": \"M\"} or {\"style\": \"currency\", \"currency\": \"EUR\"}. {\"d3\": \"~s\"} is a raw d3-format escape hatch. The result echoes the resolved format."New value: +"Number format for every choropleth surface: class labels, gradient ticks and value labels. Always pass an object, e.g. {\"preset\": \"compact\"}, never a bare string. Presets: `auto` (default, inferred from magnitude), `plain` (39,538,223), `compact` (39.5M), `percent` (the input is a FRACTION, so 0.42 prints as 42% and 0.423 as 42.3%, because the preset trims trailing zeros. An explicit {\"style\": \"percent\", \"decimals\": 1} keeps them and prints 42.0%. For data already in percent points use {\"suffix\": \"%\"}), `currency` ($39,538,223). Or combine options, e.g. {\"decimals\": 1, \"suffix\": \"M\"} or {\"style\": \"currency\", \"currency\": \"EUR\"}. {\"d3\": \"~s\"} is a raw d3-format escape hatch. Add \"locale\" for a non-US number style: \"de-DE\" (1.234,5 / 1,2 Mio.), \"fr-FR\" (1 234,5), \"es-ES\", \"it-IT\", \"pt-BR\", \"de-CH\" (1’234.5), \"en-IN\" (12,34,567 / 12L), \"nl-NL\", \"pl-PL\", \"sv-SE\"; it combines with presets and d3, and {\"locale\": \"de-DE\"} alone is the automatic format in that style. The result echoes the resolved format."

Added value: +{
+  "default": "en-US",
+  "description": "Number style: separators, currency placement and compact suffixes. `{\"decimals\": 1, \"locale\": \"de-DE\"}` turns 1234567.5 into \"1.234.567,5\"; with `compact: true` it gives \"1,2 Mio.\". Combines with `preset` and `d3`; on its own (`{\"locale\": \"de-DE\"}`) it is the automatic format in that number style.\n",
+  "enum": [
+    "en-US",
+    "de-DE",
+    "fr-FR",
+    "es-ES",
+    "it-IT",
+    "pt-BR",
+    "de-CH",
+    "en-IN",
+    "nl-NL",
+    "pl-PL",
+    "sv-SE"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "What the numbers are. Send it whenever you know. `percent` = already ×100 (42 prints \"42%\"), `fraction` = a 0–1 share (0.42 prints \"42%\"), `currency` (set `unit` to the code, e.g. \"EUR\"), `year` (1788, no separator), `change` (signed labels, diverging around 0), or `count`, `rate`, `index`. Once a kind is given, the palette is diverging only with `midpoint` or `kind: \"change\"`, so data that merely dips below zero stays sequential.",
+  "enum": [
+    "count",
+    "rate",
+    "percent",
+    "fraction",
+    "currency",
+    "change",
+    "year",
+    "index"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Steps legends: also print the two outer ends of the bar (ignored for groups and gradient legends). An end that the automatic breaks left open, or that the data reaches past, reads \"< 10\" / \"≥ 90\" rather than a round bound the data never reaches. Groups legends already print every range and gradients their ends, so only steps change. Default false.\n",
+  "type": "boolean"
+}

Previous value: -"Break method. Absent = suggested from the data. quantile = equal number of regions per class, equalInterval = equal-width value intervals, jenks = natural breaks (minimal within-class variance), pretty = rounded human-readable edges. Additive-only enum: more methods may be added, none removed.\n"New value: +"Break method. Absent = round, publishable edges picked from the data (a constant step such as 0 · 10 · 20 · 30, or a 1-2-5 ladder such as 0 · 10K · 25K · 50K · 100K for skewed data), reported as `pretty`. quantile = equal number of regions per class, equalInterval = equal-width value intervals, jenks = natural breaks (minimal within-class variance), pretty = rounded human-readable edges. Additive-only enum: more methods may be added, none removed.\n"

Added value: +{
+  "description": "The meaningful center of the data: 0 for a change or balance, 100 for an index where 100 is the reference (EU27 = 100), 1 for a ratio. Gives a diverging palette with its neutral color on this value. Leave it out for one-directional data.",
+  "type": "number"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Adds a \"No data\" row to the legend for regions without a value: true, or {\"label\": \"Not reported\"}. Off unless you send it. Send it whenever your data does not cover the whole map (the result reports how many regions have no value); without it those regions are drawn in a gray the legend does not explain. With full coverage the row is left out. A `nodata_low_contrast` warning means the default fill for those regions is hard to tell from the palette (gray palettes): send `noDataColor`.",
+  "properties": {
+    "label": {
+      "maxLength": 40,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "type": [
+    "boolean",
+    "object"
+  ]
+}

Previous value: -"Fill for regions absent from `values`. Choropleth mode only. Overrides `style.defaultRegionColor` when both are set.\n"New value: +"Fill for regions absent from `values`. Choropleth mode only. Overrides `style.defaultRegionColor` when both are set. When neither is set, the theme's region color is used if it stays apart from the palette (CIEDE2000 ≥ 12 from the lightest class, ≥ 8 from every class) or is transparent by design; otherwise a light, slightly theme-tinted gray that does and keeps the region borders visible, so missing data never reads as the lowest class or as the neutral of a diverging palette. Gray palettes can leave no such color: the theme color is then darkened and a `nodata_low_contrast` warning asks for an explicit `noDataColor`.\n"

Previous value: -"ColorBrewer palette id (the server matches case-insensitively). Absent = suggested from the data: diverging when the values cross zero (rdbu when they sit symmetrically around zero, rdylgn when they do not), sequential blues otherwise. Note that `rdylgn` only comes back out. It is not in the enum above, and requesting it is a `400`. Sequential palettes suit one-directional data, and diverging palettes (rdbu, brbg, spectral, piyg, prgn, puor, rdgy, rdylbu) suit data around a midpoint.\n"New value: +"ColorBrewer palette id (the server matches case-insensitively). Absent = suggested: `rdbu` centered on `midpoint` when one is given (or `kind` is `change`); with no hints, `rdbu` centered on 0 when the values spread on both sides of zero; sequential blues otherwise. Sequential palettes suit one-directional data, and diverging palettes (rdbu, brbg, spectral, piyg, prgn, puor, rdgy, rdylbu) suit data around a midpoint.\n"

Added value: +{
+  "description": "Short unit printed on every label, up to 16 characters: \"%\", \"°C\", \"t\", \"km²\". Put long units (\"litres of pure alcohol per person\") in `legend.title` instead. With `kind: \"currency\"` it is the currency code or symbol. Ignored for `kind: \"fraction\"` and when `format` is set, except {\"locale\": \"de-DE\"} (or {\"preset\": \"auto\", \"locale\": \"de-DE\"}), which keeps kind and unit in that number style. An explicit `format` decides only the labels: `kind` and `midpoint` still decide sequential vs diverging.",
+  "maxLength": 16,
+  "minLength": 1,
+  "type": "string"
+}

Previous value: -"Surrounding land, as a filled area of neighbouring countries or states."New value: +"Surrounding land, as a filled area of neighboring countries or states."

Previous value: -"Major cities as labelled points."New value: +"Major cities as labeled points."

Previous value: -"left/right take a column carved from the map area (180 px, at most 30% of the width); top/bottom take a horizontal band between the title and the map. Absent = left for item/group legends, bottom for gradient/steps. Gradient and steps legends are horizontal-only, so left/right becomes bottom with a warning. Legends do not wrap: a wide legend on a narrow image can overflow, reported as a `legend_overflow` warning."New value: +"left/right take a column carved from the map area (180 px, widened up to 260 px for long labels or a legend title, at most 30% of the width); top/bottom take a horizontal band between the title and the map. Absent = picked per render: inside the map over empty space (sea, the margin beside a narrow map) when the legend fits there clear of land, else gradient/steps go to the bottom band and item/group legends to the left column or the bottom band, whichever leaves the map larger. Leave it out unless you need the legend outside the map. Gradient and steps legends are horizontal-only, so left/right becomes bottom with a warning. Band items wrap into rows; a bar too wide for a narrow image is reported as a `legend_overflow` warning."

Added value: +{
+  "description": "Line under the legend title, at the label size in the regular weight, e.g. the source or the base year. Same wrapping as `title`.\n",
+  "maxLength": 160,
+  "minLength": 1,
+  "type": "string"
+}

Added value: +{
+  "description": "Heading above the legend rows. Send one for every data legend: what is measured, its unit and the year, e.g. \"Median household income (US$, 2023)\". It is never derived from `choropleth.unit`: short units (\"%\", \"°C\") go in `unit` and print on every label, long ones belong here. Long titles wrap to fit the legend; `\\n` forces a break.",
+  "maxLength": 120,
+  "minLength": 1,
+  "type": "string"
+}

Previous value: -"warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn.\n"New value: +"warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn. Region keys in `style.labels.hide` count too: a typo there is a 400 under error.\n"

Previous value: -"Optional. When omitted, derives as a snug fit: the map's aspect ratio applied to the map area that remains after the title band (50 px) and any left/right legend column take their cut. A top/bottom legend adds its band (60 px for item legends, 70 px for gradient/steps bars) on top of that. An explicit height is delivered exactly, and the title and legend then shrink the map rather than the canvas.\n"New value: +"Optional. When omitted, derives as a snug fit: the map's aspect ratio applied to the map area that remains after the title band (50 px) and any left/right legend column take their cut. A top/bottom legend adds its band (60 px for item legends, 70 px for gradient/steps bars, plus the height of a `legend.title`/`subtitle`) on top of that. A left/right legend too tall for that canvas (many items, a wrapped title) grows the derived height until it fits. An explicit height is delivered exactly, and the title and legend then shrink the map rather than the canvas.\n"

Previous value: -"Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default.\n"New value: +"Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default (in choropleth mode, a contrasting gray when the theme's region color is too close to the palette's lightest class).\n"

Previous value: -"Region labels, off by default. Each map ships its own curated label set; on a map with `labels: false` in list_maps, `show: true` renders nothing and a `labels_unavailable` warning is reported."New value: +"Region labels, off by default. Each map ships its own curated label set; on a map with `labels: false` in list_maps, `show: true` renders nothing and a `labels_unavailable` warning is reported. `content`: \"name\" (default), \"value\" (the choropleth number in the legend's format, or the category label; regions without data get no label) or \"name_value\" (name above value; regions without data show the name only). `fit`: \"auto\" (default) shortens labels that don't fit or overlap (to the value on a choropleth, the name on a category map); labels never disappear, and any still overlapping are listed in a `labels_overlap` warning. \"off\" draws every label in full. `hide`: region keys whose label never shows (matched like data keys). A typo is auto-corrected or reported as unmatched; under `onUnmatched: \"error\"` an unmatched key fails the request like a data key."

Previous value: -"What each label prints. `name` is the region's name. `value` prints the region's choropleth number instead, formatted by the resolved `choropleth.format` (the same string the legend and tooltips show). Regions without a value get no label. Requires `choropleth`. With `categories`, or with neither, it is a `validation_error`. Labels are not collision-checked: a long number in a small region overflows it, exactly as in Studio."New value: +"What each label prints. `name` is the region's name. `value` prints the region's value instead: the choropleth number formatted by the resolved `choropleth.format` (the same string the legend and tooltips show), or the category label. Regions without a value get no label. `name_value` prints the name with the value on a line below it; regions without a value show the name only. Both value modes require `choropleth` or `categories`; with neither it is a `validation_error`."

Previous value: -[
-  "name",
-  "value"
-]New value: +[
+  "name",
+  "value",
+  "name_value"
+]

Added value: +{
+  "default": "auto",
+  "description": "`auto` shortens labels that don't fit or overlap and never hides one; `off` draws every label in full. Under `auto` a `name_value` label too big for its region, or overlapping a higher-priority one, drops to its value (choropleth; the legend only gives a range) or its name (categories; the fill already says the category). Priority: curated outside labels (small regions labeled beside the map), then larger regions. Labels still overlapping are drawn and reported in a `labels_overlap` warning. Studio's own default is off; a map opened in Studio from a render keeps the value sent.",
+  "enum": [
+    "auto",
+    "off"
+  ],
+  "type": "string"
+}

Added value: +{
+  "description": "Region keys whose label never shows. Matched like data keys; corrections and misses are reported in `regionMatching`. Ignored with a `label_lists_ignored` warning when `show` is false.",
+  "items": {
+    "maxLength": 200,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 5000,
+  "type": "array"
+}

Added value: +{
+  "description": "Regions of the map with no value, drawn in the no-data color.",
+  "minimum": 0,
+  "type": "integer"
+}

Added value: +{
+  "description": "`labels_overlap` only: region labels still overlapping.",
+  "minimum": 0,
+  "type": "integer"
+}

Added value: +{
+  "description": "`labels_overlap` only: first overlapping region keys (up to 10).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "`labels_overlap` only: labels shortened.",
+  "minimum": 0,
+  "type": "integer"
+}