Wherebox
Get API key

Generated from code

Request body

The JSON body of POST /v1/map. Every field of the map spec, as a tree: routes[] means "each element of routes". Fields without a default are optional unless a description says otherwise.

Path Type / values Default Description
area.query string — Name or id, as in the string form.
area.level integer, 1–11 — Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).
area.country string — Only match areas inside this ISO 3166-1 alpha-2 country.
area.geojson.type Polygon | MultiPolygon | Feature — GeoJSON type.
area.geojson object — A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries.
area string | object — The area to frame and highlight. Ambiguous names return 409 with candidates.
bounds array — Explicit frame [west, south, east, north]; overrides automatic framing. Cannot be combined with center/zoom.
center.lat number, -85.06–85.06 — Latitude (WGS84).
center.lon number, -180–180 — Longitude (WGS84).
center object — Center of the map. With zoom, this is an exact camera (as in other static map APIs) and nothing else affects the frame. Without zoom, the zoom is chosen so the area, routes, shapes and points fit around this center.
zoom number, 0–22 — Zoom level, 0 (whole world) to 22, in the usual web-map zoom units (512 px tiles, as MapLibre and Mapbox GL: at zoom z the world is 512·2^z CSS px wide). With center, an exact camera; without center, the map is centered on the content at this zoom. Not available with the globe projection.
routes[].geometry.type LineString | MultiLineString | Feature — GeoJSON type.
routes[].geometry object — A line you already have (e.g. from your own routing provider).
routes[].polyline string — The line as an encoded polyline (Google algorithm).
routes[].polylinePrecision 5 | 6 5 Polyline precision: 5 (Google) or 6 (Valhalla/OSRM).
routes[].from.lat number, -90–90 — Latitude (WGS84).
routes[].from.lon number, -180–180 — Longitude (WGS84).
routes[].from.place string — Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.
routes[].from object — Start point when the server should compute the line.
routes[].to.lat number, -90–90 — Latitude (WGS84).
routes[].to.lon number, -180–180 — Longitude (WGS84).
routes[].to.place string — Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.
routes[].to object — Finish point when the server should compute the line.
routes[].via[].lat number, -90–90 — Latitude (WGS84).
routes[].via[].lon number, -180–180 — Longitude (WGS84).
routes[].via[].place string — Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.
routes[].via[] object — A route end or via point: {lat, lon} or {place}.
routes[].via array [] Points the route must pass through, in order.
routes[].profile car | bike | foot | straight | geodesic geodesic How endpoints are connected: routed by car/bike/foot (needs a routing engine on the server or your X-Routing-Key), or locally as straight segments or geodesic great-circle arcs. The default geodesic always works (no routing engine, key or plan feature needed) and is the true shortest path, so it suits flights and locator maps; ask for car/bike/foot explicitly for roads.
routes[].provider valhalla | openrouteservice | graphhopper — Routing provider (default: the server's). openrouteservice and GraphHopper need a key (server-side or X-Routing-Key).
routes[].color string #d01c1c Color of the route line.
routes[].width number, 0.5–20 3 Line width in px.
routes[].casingColor string #ffffff Outline drawn under the line so it reads on busy basemaps.
routes[].casingWidth number, 0–10 1.5 Outline width on each side in px; 0 = none.
routes[].dash array — Dash pattern in line widths, e.g. [2, 1.5].
routes[].opacity number, 0–1 1 Line opacity.
routes[].start.label string — Label at this end (default: the place name, if the end was given as a place).
routes[].start.labelPosition auto | right | left | top | bottom | top-right | top-left | bottom-right | bottom-left auto Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.
routes[].start.labelSize number, 6–48 16 Label text size in CSS px.
routes[].start.labelWeight integer, 100–900 — Font weight for this label (overrides font.weight).
routes[].start.labelColor string — Label color (default: the basemap theme's label color).
routes[].start.marker.shape pin | dot | ring | flag | triangle | circle | square | star | diamond — Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.
routes[].start.marker.color string — Marker fill color.
routes[].start.marker.size number, 4–64 — Marker height in CSS pixels (multiplied by scale). Default depends on the shape.
routes[].start.marker.strokeColor string — Outline color (default white where the shape has an outline).
routes[].start.marker.strokeWidth number, 0–8 — Outline width in px; 0 = none. dot and pin have a thin default outline.
routes[].start.marker.icon string — Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.
routes[].start.marker.anchor center | bottom — Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).
routes[].start.marker object — Marker style; every field is optional and falls back to the role default.
routes[].start.show boolean true false hides the marker and label for this end.
routes[].start object {} Marker and label for one end of the route.
routes[].finish.label string — Label at this end (default: the place name, if the end was given as a place).
routes[].finish.labelPosition auto | right | left | top | bottom | top-right | top-left | bottom-right | bottom-left auto Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.
routes[].finish.labelSize number, 6–48 16 Label text size in CSS px.
routes[].finish.labelWeight integer, 100–900 — Font weight for this label (overrides font.weight).
routes[].finish.labelColor string — Label color (default: the basemap theme's label color).
routes[].finish.marker.shape pin | dot | ring | flag | triangle | circle | square | star | diamond — Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.
routes[].finish.marker.color string — Marker fill color.
routes[].finish.marker.size number, 4–64 — Marker height in CSS pixels (multiplied by scale). Default depends on the shape.
routes[].finish.marker.strokeColor string — Outline color (default white where the shape has an outline).
routes[].finish.marker.strokeWidth number, 0–8 — Outline width in px; 0 = none. dot and pin have a thin default outline.
routes[].finish.marker.icon string — Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.
routes[].finish.marker.anchor center | bottom — Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).
routes[].finish.marker object — Marker style; every field is optional and falls back to the role default.
routes[].finish.show boolean true false hides the marker and label for this end.
routes[].finish object {} Marker and label for one end of the route.
routes[] object — A line between points: given as geometry/polyline, routed between from and to, or straight/geodesic.
routes array [] Routes to draw (GET supports one; POST up to 10).
shapes[].geojson.type string — GeoJSON type (LineString, Polygon, Feature, FeatureCollection, …).
shapes[].geojson object — Any GeoJSON geometry, Feature or FeatureCollection.
shapes[].color string #555555 Line color of the shape.
shapes[].width number, 0–20 2 Line width in px; 0 = no line.
shapes[].dash array — Dash pattern in line widths.
shapes[].opacity number, 0–1 1 Line opacity.
shapes[].fill string — Fill color for polygons (no fill if unset).
shapes[].fillOpacity number, 0–1 0.25 Fill opacity for polygons.
shapes[] object — An extra line or polygon drawn on the map (e.g. a boundary arc or a buffer zone).
shapes array [] Extra lines and polygons, drawn in order (later ones on top). Up to 50; in GET, repeat shape.
font.family noto-sans | noto-serif | noto-sans-mono noto-sans A bundled family, or your own TTF/OTF/WOFF as a data: URI or an https URL on an allowed host (WHEREBOX_FONT_HOSTS). Missing glyphs fall back to Noto Sans, then Noto Sans Mono.
font.weight integer, 100–900 400 Weight for all labels (100–900; the nearest bundled weight is used).
font object {} Font for everything we draw (labels, title); the basemap keeps its own fonts.
title.text string — Title text (one line; long titles shrink, then get an ellipsis).
title.position top | bottom top Band above or below the map.
title.align left | center | right left Text alignment in the band.
title.size number, 8–64 18 Text size in CSS px.
title.weight integer, 100–900 600 Font weight.
title.color string — Text color (default: the theme label color).
title.background string — Band background (default: white, or near-black on the dark preset).
title.dividerColor string — Line between the band and the map.
title.dividerWidth number, 0–6 1 Divider width in px; 0 = none.
title.padding number, 0–40 10 Space around the text in px.
title object — A title band, drawn inside the requested width×height (the map gets the rest).
pois[].lat number, -90–90 — Latitude (WGS84). Any coordinate works; no lookup is done.
pois[].lon number, -180–180 — Longitude (WGS84).
pois[].place string — A place name to look up instead of coordinates (cities, peaks, mountain ranges…). Looked up in the imported OSM places first, then in the server's geocoder if one is configured. The label defaults to the place name.
pois[].label string — Label text. A newline (\n in GET) starts a new line.
pois[].labelPosition auto | right | left | top | bottom | top-right | top-left | bottom-right | bottom-left auto Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.
pois[].labelSize number, 6–48 16 Label text size in CSS px.
pois[].labelWeight integer, 100–900 — Font weight for this label (overrides font.weight).
pois[].labelColor string — Label color (default: the basemap theme's label color).
pois[].marker.shape pin | dot | ring | flag | triangle | circle | square | star | diamond — Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.
pois[].marker.color string — Marker fill color.
pois[].marker.size number, 4–64 — Marker height in CSS pixels (multiplied by scale). Default depends on the shape.
pois[].marker.strokeColor string — Outline color (default white where the shape has an outline).
pois[].marker.strokeWidth number, 0–8 — Outline width in px; 0 = none. dot and pin have a thin default outline.
pois[].marker.icon string — Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.
pois[].marker.anchor center | bottom — Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).
pois[].marker object — Marker style; every field is optional and falls back to the role default.
pois[].leader boolean true When no free spot is next to the marker, place the label further out with a thin leader line.
pois[] object — A point on the map: coordinates or a place name, with an optional label and marker.
pois array [] Points with markers and labels (up to 50).
width integer, 64–2048 600 Image width in CSS px (the output is width × scale pixels).
height integer, 64–2048 400 Image height in CSS px, including the title band if any.
scale integer, 1–3 1 Pixel ratio for high-DPI output (2 = retina).
format png | jpeg | webp png Image format (GET can also use the path extension: /v1/map.png, .jpg, .webp).
quality integer, 1–100 90 JPEG/WebP quality.
padding number, 0–0.45 0.04 Space around the framed content as a fraction of the image size.
projection mercator | globe | auto mercator Map projection. mercator is the usual flat web map. globe draws an orthographic globe, which keeps continent-spanning routes and high latitudes true to shape; the content must fit on one hemisphere (within 85° of the view center), and neighbor labels are not available. auto picks the globe when the content spans more than 50° or Mercator would stretch it more than 2.5× between its lowest and highest latitude, else Mercator.
globe.view full | fit full How much of the globe to show. full (default): the whole globe, centered on your content, with space around it; recognizable at a glance as a globe. fit: zoomed in until the content fills the image; a larger scale with more detail along the route, but only part of the globe is visible.
globe object {} Globe options (with projection globe, or auto when it picks the globe).
basemap.preset locator-relief | light | dark | none locator-relief Built-in basemap: shaded relief (Wikipedia locator style), light, dark, or none: no map at all, only a plain background color with your area outline, shapes, routes and points on it (the "outline of Texas with a star" look). No key needed.
basemap.styleUrl string — Any MapLibre style.json URL; overrides preset. {key} in the URL is replaced with providerKey.
basemap.providerKey string — Key for a commercial style (prefer the X-Provider-Key header so it stays out of URLs).
basemap.background transparent — Background color for preset none (default white): any hex color, or transparent for a PNG/WebP with a transparent background that sits on any page. Labels, outline and attribution switch to light colors on a dark background. Only valid with preset none; transparent does not work with JPEG.
basemap object {} The map underneath: a built-in preset or your own style.
highlight.fade number, 0–1 0.45 (varies by preset) How much the surroundings are washed out: 0 = not at all, 1 = fully covered.
highlight.fadeColor string #ffffff (varies by preset) Color the surroundings fade towards.
highlight.outlineColor string #555555 (varies by preset) Area outline color.
highlight.outlineWidth number, 0–10 1.1 (varies by preset) Area outline width in px; 0 = none.
highlight.tint string — Optional color tint drawn over the area.
highlight.tintOpacity number, 0–1 0.15 (varies by preset) Opacity of tint.
highlight.subdivisions boolean | string | integer, auto, 3–11 auto (varies by preset) Inner admin borders: auto draws the next level that splits the area, a number forces that admin level, false hides them.
highlight.subdivisionColor string #8a8a8a (varies by preset) Color of the inner admin borders.
highlight.subdivisionWidth number, 0–6 0.6 (varies by preset) Width of the inner admin borders in px.
highlight.desaturate number, 0–1 0 (varies by preset) Outside the area: 0 = full color, 1 = grayscale (applied on top of fade).
highlight.blur number, 0–20 0 (varies by preset) Outside the area: blur radius in CSS px; 0 = sharp.
highlight.subArea.query string — Name or id, as in the string form.
highlight.subArea.level integer, 1–11 — Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).
highlight.subArea.country string — Only match areas inside this ISO 3166-1 alpha-2 country.
highlight.subArea.geojson.type Polygon | MultiPolygon | Feature — GeoJSON type.
highlight.subArea.geojson object — A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries.
highlight.subArea string | object — A second, smaller area highlighted inside the framed one (e.g. a region within its country).
highlight.subAreaColor string #d03030 (varies by preset) Fill and outline color of subArea.
highlight.subAreaOpacity number, 0–1 0.35 (varies by preset) Fill opacity of subArea.
highlight.subAreaOutlineWidth number, 0–10 1.2 (varies by preset) Outline width of subArea in px; 0 = none.
highlight object {} How the area stands out. Unset fields use the basemap preset's defaults (see the presets reference).
attribution bottom-right | bottom-left | top-right | top-left | none bottom-right Corner for the data attribution, or none to leave it off the image. The data licenses (OpenStreetMap ODbL, and Natural Earth/terrain credits where used) still require it: with none you must show the attribution next to the image yourself. The text to show is returned in the X-Attribution response header.
logo bottom-right | bottom-left | top-right | top-left | none bottom-left Corner for the small wherebox.dev mark (9.5 px text), or none to hide it. Hiding the logo requires a logo-removal license (see the Fair use guide); it is not enforced technically.
legend.position right | left | top | bottom right Side of the map the legend panel goes on.
legend.title string — Heading above the legend entries.
legend.size number, 8–32 13 Legend text size in CSS px; the numbered circles scale with it.
legend.color string — Legend text color (default: the theme label color).
legend.background string — Legend panel background (default: white, near-black on the dark preset, or the background of preset none).
legend.badgeColor string — Fill of the numbered circles (default: each point's marker color; route ends use the route color).
legend.badgeTextColor string #ffffff Number color inside the circles.
legend object — A classic map legend. With it, every labeled point (and labeled route end) is drawn as a numbered circle instead of its label, and the panel lists "number – label" pairs on the chosen side. The panel is inside the requested width×height; the map gets the rest.
neighbors.show name | code | flag | flag+code | flag+name name What to show for each neighboring country: its name, its international vehicle registration code (D, A, SK…), its flag, or a flag with code/name.
neighbors.which touching | visible touching touching = countries bordering the area; visible = every other country in the frame.
neighbors.fit extend | shrink | drop extend When a label does not fit in the visible part of its country: extend grows the image on that side (the output becomes larger than width×height; see X-Image-Width), shrink reduces the label to 70 %, drop omits it.
neighbors.size number, 6–32 12 Text size in CSS px; flags are sized to match.
neighbors.color string — Text color (default: the theme's muted label color).
neighbors.uppercase boolean false Uppercase country names.
neighbors.max integer, 1–30 12 At most this many countries are labeled (largest visible first).
neighbors object — Label the countries around the area (needs an area).
worldview ar | bd | br | cn | de | eg | es | fr | gb | gr | id | il | in | it | jp | kr | ma | nl | np | pk | pl | ps | pt | ru | sa | se | tr | tw | ua | us | vn — Draw country borders as this country sees them (ISO 3166-1 alpha-2, e.g. in, cn, us, ma). Replaces the basemap's country and disputed borders with Natural Earth's borders for that worldview, and uses its country shapes for a highlighted country and for neighbor labels. Regions, cities and everything below country level stay OpenStreetMap. Default: the basemap's borders (OpenStreetMap, on-the-ground control).
lang string — Label language (ISO 639-1). Default: local names (Deutschland, Polska), as on Wikipedia locator maps.

The same schema is part of openapi.json (components.schemas.MapSpec).

Full JSON Schema
{
  "type": "object",
  "properties": {
    "area": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "A name (\"Czechia\", \"Zlínský kraj\"), or an id: `iso:CZ`, `iso:CZ-72`, `osm:r51684`, `wikidata:Q213`.",
          "examples": [
            "Czechia"
          ]
        },
        {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Name or id, as in the string form.",
              "examples": [
                "Nová Ves"
              ]
            },
            "level": {
              "description": "Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).",
              "examples": [
                8
              ],
              "type": "integer",
              "minimum": 1,
              "maximum": 11
            },
            "country": {
              "description": "Only match areas inside this ISO 3166-1 alpha-2 country.",
              "examples": [
                "CZ"
              ],
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          "required": [
            "query"
          ],
          "description": "A name lookup narrowed by admin level and/or country, for ambiguous names."
        },
        {
          "type": "object",
          "properties": {
            "geojson": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "Polygon",
                    "MultiPolygon",
                    "Feature"
                  ],
                  "description": "GeoJSON type.",
                  "examples": [
                    "Polygon"
                  ]
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {},
              "description": "A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries."
            }
          },
          "required": [
            "geojson"
          ],
          "description": "Your own area geometry instead of a lookup."
        }
      ],
      "description": "The area to frame and highlight. Ambiguous names return 409 with candidates.",
      "examples": [
        "Czechia"
      ]
    },
    "bounds": {
      "description": "Explicit frame `[west, south, east, north]`; overrides automatic framing. Cannot be combined with `center`/`zoom`.",
      "examples": [
        [
          12.09,
          48.55,
          18.86,
          51.06
        ]
      ],
      "type": "array",
      "prefixItems": [
        {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        {
          "type": "number",
          "minimum": -85.06,
          "maximum": 85.06
        },
        {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        {
          "type": "number",
          "minimum": -85.06,
          "maximum": 85.06
        }
      ],
      "items": false,
      "minItems": 4,
      "maxItems": 4
    },
    "center": {
      "description": "Center of the map. With `zoom`, this is an exact camera (as in other static map APIs) and nothing else affects the frame. Without `zoom`, the zoom is chosen so the area, routes, shapes and points fit around this center.",
      "examples": [
        {
          "lat": 50.08,
          "lon": 14.42
        }
      ],
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -85.06,
          "maximum": 85.06,
          "description": "Latitude (WGS84).",
          "examples": [
            50.08
          ]
        },
        "lon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Longitude (WGS84).",
          "examples": [
            14.42
          ]
        }
      },
      "required": [
        "lat",
        "lon"
      ]
    },
    "zoom": {
      "description": "Zoom level, 0 (whole world) to 22, in the usual web-map zoom units (512 px tiles, as MapLibre and Mapbox GL: at zoom z the world is 512·2^z CSS px wide). With `center`, an exact camera; without `center`, the map is centered on the content at this zoom. Not available with the globe projection.",
      "examples": [
        12
      ],
      "type": "number",
      "minimum": 0,
      "maximum": 22
    },
    "routes": {
      "default": [],
      "description": "Routes to draw (GET supports one; POST up to 10).",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geometry": {
            "description": "A line you already have (e.g. from your own routing provider).",
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "LineString",
                  "MultiLineString",
                  "Feature"
                ],
                "description": "GeoJSON type.",
                "examples": [
                  "LineString"
                ]
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": {}
          },
          "polyline": {
            "description": "The line as an encoded polyline (Google algorithm).",
            "examples": [
              "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
            ],
            "type": "string",
            "maxLength": 200000
          },
          "polylinePrecision": {
            "default": 5,
            "description": "Polyline precision: 5 (Google) or 6 (Valhalla/OSRM).",
            "examples": [
              5
            ],
            "anyOf": [
              {
                "type": "number",
                "const": 5
              },
              {
                "type": "number",
                "const": 6
              }
            ]
          },
          "from": {
            "description": "Start point when the server should compute the line.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Latitude (WGS84).",
                    "examples": [
                      40.4168
                    ]
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude (WGS84).",
                    "examples": [
                      -3.7038
                    ]
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Coordinates."
              },
              {
                "type": "object",
                "properties": {
                  "place": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.",
                    "examples": [
                      "Sevilla"
                    ]
                  }
                },
                "required": [
                  "place"
                ],
                "description": "A place name to look up."
              }
            ],
            "examples": [
              {
                "lat": 40.4168,
                "lon": -3.7038
              }
            ]
          },
          "to": {
            "description": "Finish point when the server should compute the line.",
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Latitude (WGS84).",
                    "examples": [
                      40.4168
                    ]
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude (WGS84).",
                    "examples": [
                      -3.7038
                    ]
                  }
                },
                "required": [
                  "lat",
                  "lon"
                ],
                "description": "Coordinates."
              },
              {
                "type": "object",
                "properties": {
                  "place": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.",
                    "examples": [
                      "Sevilla"
                    ]
                  }
                },
                "required": [
                  "place"
                ],
                "description": "A place name to look up."
              }
            ],
            "examples": [
              {
                "lat": 40.4168,
                "lon": -3.7038
              }
            ]
          },
          "via": {
            "default": [],
            "description": "Points the route must pass through, in order.",
            "maxItems": 20,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "lat": {
                      "type": "number",
                      "minimum": -90,
                      "maximum": 90,
                      "description": "Latitude (WGS84).",
                      "examples": [
                        40.4168
                      ]
                    },
                    "lon": {
                      "type": "number",
                      "minimum": -180,
                      "maximum": 180,
                      "description": "Longitude (WGS84).",
                      "examples": [
                        -3.7038
                      ]
                    }
                  },
                  "required": [
                    "lat",
                    "lon"
                  ],
                  "description": "Coordinates."
                },
                {
                  "type": "object",
                  "properties": {
                    "place": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "description": "Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.",
                      "examples": [
                        "Sevilla"
                      ]
                    }
                  },
                  "required": [
                    "place"
                  ],
                  "description": "A place name to look up."
                }
              ],
              "description": "A route end or via point: `{lat, lon}` or `{place}`.",
              "examples": [
                {
                  "lat": 40.4168,
                  "lon": -3.7038
                }
              ]
            }
          },
          "profile": {
            "default": "geodesic",
            "type": "string",
            "enum": [
              "car",
              "bike",
              "foot",
              "straight",
              "geodesic"
            ],
            "description": "How endpoints are connected: routed by `car`/`bike`/`foot` (needs a routing engine on the server or your `X-Routing-Key`), or locally as `straight` segments or `geodesic` great-circle arcs. The default `geodesic` always works (no routing engine, key or plan feature needed) and is the true shortest path, so it suits flights and locator maps; ask for `car`/`bike`/`foot` explicitly for roads.",
            "examples": [
              "geodesic"
            ]
          },
          "provider": {
            "description": "Routing provider (default: the server's). openrouteservice and GraphHopper need a key (server-side or `X-Routing-Key`).",
            "examples": [
              "valhalla"
            ],
            "type": "string",
            "enum": [
              "valhalla",
              "openrouteservice",
              "graphhopper"
            ]
          },
          "color": {
            "default": "#d01c1c",
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
            "description": "Color of the route line.",
            "examples": [
              "#d01c1c"
            ]
          },
          "width": {
            "default": 3,
            "description": "Line width in px.",
            "examples": [
              3
            ],
            "type": "number",
            "minimum": 0.5,
            "maximum": 20
          },
          "casingColor": {
            "default": "#ffffff",
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
            "description": "Outline drawn under the line so it reads on busy basemaps.",
            "examples": [
              "#ffffff"
            ]
          },
          "casingWidth": {
            "default": 1.5,
            "description": "Outline width on each side in px; 0 = none.",
            "examples": [
              1.5
            ],
            "type": "number",
            "minimum": 0,
            "maximum": 10
          },
          "dash": {
            "description": "Dash pattern in line widths, e.g. `[2, 1.5]`.",
            "examples": [
              [
                2,
                1.5
              ]
            ],
            "maxItems": 8,
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 50
            }
          },
          "opacity": {
            "default": 1,
            "description": "Line opacity.",
            "examples": [
              1
            ],
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "start": {
            "default": {},
            "type": "object",
            "properties": {
              "label": {
                "description": "Label at this end (default: the place name, if the end was given as a place).",
                "examples": [
                  "Madrid"
                ],
                "type": "string",
                "maxLength": 160
              },
              "labelPosition": {
                "default": "auto",
                "type": "string",
                "enum": [
                  "auto",
                  "right",
                  "left",
                  "top",
                  "bottom",
                  "top-right",
                  "top-left",
                  "bottom-right",
                  "bottom-left"
                ],
                "description": "Where the label goes relative to the marker. `auto` picks the first free spot and falls back to a leader line.",
                "examples": [
                  "auto"
                ]
              },
              "labelSize": {
                "default": 16,
                "description": "Label text size in CSS px.",
                "examples": [
                  16
                ],
                "type": "number",
                "minimum": 6,
                "maximum": 48
              },
              "labelWeight": {
                "description": "Font weight for this label (overrides `font.weight`).",
                "examples": [
                  700
                ],
                "type": "integer",
                "minimum": 100,
                "maximum": 900
              },
              "labelColor": {
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                "description": "Label color (default: the basemap theme's label color).",
                "examples": [
                  "#1a1a1a"
                ]
              },
              "marker": {
                "type": "object",
                "properties": {
                  "shape": {
                    "type": "string",
                    "enum": [
                      "pin",
                      "dot",
                      "ring",
                      "flag",
                      "triangle",
                      "circle",
                      "square",
                      "star",
                      "diamond"
                    ],
                    "description": "Marker preset. Defaults depend on the role: plain point → `pin`, route start → `ring`, route finish → `flag`.",
                    "examples": [
                      "pin"
                    ]
                  },
                  "color": {
                    "type": "string",
                    "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                    "description": "Marker fill color.",
                    "examples": [
                      "#e02020"
                    ]
                  },
                  "size": {
                    "type": "number",
                    "minimum": 4,
                    "maximum": 64,
                    "description": "Marker height in CSS pixels (multiplied by `scale`). Default depends on the shape.",
                    "examples": [
                      20
                    ]
                  },
                  "strokeColor": {
                    "type": "string",
                    "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                    "description": "Outline color (default white where the shape has an outline).",
                    "examples": [
                      "#ffffff"
                    ]
                  },
                  "strokeWidth": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 8,
                    "description": "Outline width in px; 0 = none. `dot` and `pin` have a thin default outline.",
                    "examples": [
                      1.5
                    ]
                  },
                  "icon": {
                    "type": "string",
                    "maxLength": 200000,
                    "description": "Custom icon instead of the shape: an SVG/PNG `data:` URI, or an https URL on a host the server allows (`WHEREBOX_ICON_HOSTS`). SVGs with external references or scripts are rejected.",
                    "examples": [
                      "data:image/svg+xml;base64,PHN2Zy8+"
                    ]
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "center",
                      "bottom"
                    ],
                    "description": "Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).",
                    "examples": [
                      "bottom"
                    ]
                  }
                },
                "description": "Marker style; every field is optional and falls back to the role default."
              },
              "show": {
                "default": true,
                "description": "`false` hides the marker and label for this end.",
                "examples": [
                  true
                ],
                "type": "boolean"
              }
            },
            "description": "Marker and label for one end of the route."
          },
          "finish": {
            "default": {},
            "type": "object",
            "properties": {
              "label": {
                "description": "Label at this end (default: the place name, if the end was given as a place).",
                "examples": [
                  "Madrid"
                ],
                "type": "string",
                "maxLength": 160
              },
              "labelPosition": {
                "default": "auto",
                "type": "string",
                "enum": [
                  "auto",
                  "right",
                  "left",
                  "top",
                  "bottom",
                  "top-right",
                  "top-left",
                  "bottom-right",
                  "bottom-left"
                ],
                "description": "Where the label goes relative to the marker. `auto` picks the first free spot and falls back to a leader line.",
                "examples": [
                  "auto"
                ]
              },
              "labelSize": {
                "default": 16,
                "description": "Label text size in CSS px.",
                "examples": [
                  16
                ],
                "type": "number",
                "minimum": 6,
                "maximum": 48
              },
              "labelWeight": {
                "description": "Font weight for this label (overrides `font.weight`).",
                "examples": [
                  700
                ],
                "type": "integer",
                "minimum": 100,
                "maximum": 900
              },
              "labelColor": {
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                "description": "Label color (default: the basemap theme's label color).",
                "examples": [
                  "#1a1a1a"
                ]
              },
              "marker": {
                "type": "object",
                "properties": {
                  "shape": {
                    "type": "string",
                    "enum": [
                      "pin",
                      "dot",
                      "ring",
                      "flag",
                      "triangle",
                      "circle",
                      "square",
                      "star",
                      "diamond"
                    ],
                    "description": "Marker preset. Defaults depend on the role: plain point → `pin`, route start → `ring`, route finish → `flag`.",
                    "examples": [
                      "pin"
                    ]
                  },
                  "color": {
                    "type": "string",
                    "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                    "description": "Marker fill color.",
                    "examples": [
                      "#e02020"
                    ]
                  },
                  "size": {
                    "type": "number",
                    "minimum": 4,
                    "maximum": 64,
                    "description": "Marker height in CSS pixels (multiplied by `scale`). Default depends on the shape.",
                    "examples": [
                      20
                    ]
                  },
                  "strokeColor": {
                    "type": "string",
                    "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                    "description": "Outline color (default white where the shape has an outline).",
                    "examples": [
                      "#ffffff"
                    ]
                  },
                  "strokeWidth": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 8,
                    "description": "Outline width in px; 0 = none. `dot` and `pin` have a thin default outline.",
                    "examples": [
                      1.5
                    ]
                  },
                  "icon": {
                    "type": "string",
                    "maxLength": 200000,
                    "description": "Custom icon instead of the shape: an SVG/PNG `data:` URI, or an https URL on a host the server allows (`WHEREBOX_ICON_HOSTS`). SVGs with external references or scripts are rejected.",
                    "examples": [
                      "data:image/svg+xml;base64,PHN2Zy8+"
                    ]
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "center",
                      "bottom"
                    ],
                    "description": "Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).",
                    "examples": [
                      "bottom"
                    ]
                  }
                },
                "description": "Marker style; every field is optional and falls back to the role default."
              },
              "show": {
                "default": true,
                "description": "`false` hides the marker and label for this end.",
                "examples": [
                  true
                ],
                "type": "boolean"
              }
            },
            "description": "Marker and label for one end of the route."
          }
        },
        "description": "A line between points: given as geometry/polyline, routed between `from` and `to`, or straight/geodesic."
      }
    },
    "shapes": {
      "default": [],
      "description": "Extra lines and polygons, drawn in order (later ones on top). Up to 50; in GET, repeat `shape`.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geojson": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "GeoJSON type (LineString, Polygon, Feature, FeatureCollection, …).",
                "examples": [
                  "LineString"
                ]
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": {},
            "description": "Any GeoJSON geometry, Feature or FeatureCollection."
          },
          "color": {
            "default": "#555555",
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
            "description": "Line color of the shape.",
            "examples": [
              "#555555"
            ]
          },
          "width": {
            "default": 2,
            "description": "Line width in px; 0 = no line.",
            "examples": [
              2
            ],
            "type": "number",
            "minimum": 0,
            "maximum": 20
          },
          "dash": {
            "description": "Dash pattern in line widths.",
            "examples": [
              [
                3,
                2
              ]
            ],
            "maxItems": 8,
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 50
            }
          },
          "opacity": {
            "default": 1,
            "description": "Line opacity.",
            "examples": [
              1
            ],
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "fill": {
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
            "description": "Fill color for polygons (no fill if unset).",
            "examples": [
              "#ffcc00"
            ]
          },
          "fillOpacity": {
            "default": 0.25,
            "description": "Fill opacity for polygons.",
            "examples": [
              0.25
            ],
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "geojson"
        ],
        "description": "An extra line or polygon drawn on the map (e.g. a boundary arc or a buffer zone)."
      }
    },
    "font": {
      "default": {},
      "type": "object",
      "properties": {
        "family": {
          "default": "noto-sans",
          "description": "A bundled family, or your own TTF/OTF/WOFF as a `data:` URI or an https URL on an allowed host (`WHEREBOX_FONT_HOSTS`). Missing glyphs fall back to Noto Sans, then Noto Sans Mono.",
          "examples": [
            "noto-serif"
          ],
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "noto-sans",
                "noto-serif",
                "noto-sans-mono"
              ],
              "description": "Bundled font family.",
              "examples": [
                "noto-sans"
              ]
            },
            {
              "type": "string",
              "maxLength": 2000000
            }
          ]
        },
        "weight": {
          "default": 400,
          "description": "Weight for all labels (100–900; the nearest bundled weight is used).",
          "examples": [
            600
          ],
          "type": "integer",
          "minimum": 100,
          "maximum": 900
        }
      },
      "description": "Font for everything we draw (labels, title); the basemap keeps its own fonts."
    },
    "title": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Title text (one line; long titles shrink, then get an ellipsis).",
          "examples": [
            "Madrid – Seville"
          ]
        },
        "position": {
          "default": "top",
          "description": "Band above or below the map.",
          "examples": [
            "top"
          ],
          "type": "string",
          "enum": [
            "top",
            "bottom"
          ]
        },
        "align": {
          "default": "left",
          "description": "Text alignment in the band.",
          "examples": [
            "left"
          ],
          "type": "string",
          "enum": [
            "left",
            "center",
            "right"
          ]
        },
        "size": {
          "default": 18,
          "description": "Text size in CSS px.",
          "examples": [
            18
          ],
          "type": "number",
          "minimum": 8,
          "maximum": 64
        },
        "weight": {
          "default": 600,
          "description": "Font weight.",
          "examples": [
            600
          ],
          "type": "integer",
          "minimum": 100,
          "maximum": 900
        },
        "color": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Text color (default: the theme label color).",
          "examples": [
            "#1a1a1a"
          ]
        },
        "background": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Band background (default: white, or near-black on the dark preset).",
          "examples": [
            "#ffffff"
          ]
        },
        "dividerColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Line between the band and the map.",
          "examples": [
            "#cfcfcf"
          ]
        },
        "dividerWidth": {
          "default": 1,
          "description": "Divider width in px; 0 = none.",
          "examples": [
            1
          ],
          "type": "number",
          "minimum": 0,
          "maximum": 6
        },
        "padding": {
          "default": 10,
          "description": "Space around the text in px.",
          "examples": [
            10
          ],
          "type": "number",
          "minimum": 0,
          "maximum": 40
        }
      },
      "required": [
        "text"
      ],
      "description": "A title band, drawn inside the requested width×height (the map gets the rest)."
    },
    "pois": {
      "default": [],
      "description": "Points with markers and labels (up to 50).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "description": "Latitude (WGS84). Any coordinate works; no lookup is done.",
            "examples": [
              49.13
            ],
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "lon": {
            "description": "Longitude (WGS84).",
            "examples": [
              17.33
            ],
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "place": {
            "description": "A place name to look up instead of coordinates (cities, peaks, mountain ranges…). Looked up in the imported OSM places first, then in the server's geocoder if one is configured. The label defaults to the place name.",
            "examples": [
              "Chřiby"
            ],
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "label": {
            "description": "Label text. A newline (`\\n` in GET) starts a new line.",
            "examples": [
              "Crash Site\n(near Urda)"
            ],
            "type": "string",
            "maxLength": 160
          },
          "labelPosition": {
            "default": "auto",
            "type": "string",
            "enum": [
              "auto",
              "right",
              "left",
              "top",
              "bottom",
              "top-right",
              "top-left",
              "bottom-right",
              "bottom-left"
            ],
            "description": "Where the label goes relative to the marker. `auto` picks the first free spot and falls back to a leader line.",
            "examples": [
              "auto"
            ]
          },
          "labelSize": {
            "default": 16,
            "description": "Label text size in CSS px.",
            "examples": [
              16
            ],
            "type": "number",
            "minimum": 6,
            "maximum": 48
          },
          "labelWeight": {
            "description": "Font weight for this label (overrides `font.weight`).",
            "examples": [
              700
            ],
            "type": "integer",
            "minimum": 100,
            "maximum": 900
          },
          "labelColor": {
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
            "description": "Label color (default: the basemap theme's label color).",
            "examples": [
              "#1a1a1a"
            ]
          },
          "marker": {
            "type": "object",
            "properties": {
              "shape": {
                "type": "string",
                "enum": [
                  "pin",
                  "dot",
                  "ring",
                  "flag",
                  "triangle",
                  "circle",
                  "square",
                  "star",
                  "diamond"
                ],
                "description": "Marker preset. Defaults depend on the role: plain point → `pin`, route start → `ring`, route finish → `flag`.",
                "examples": [
                  "pin"
                ]
              },
              "color": {
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                "description": "Marker fill color.",
                "examples": [
                  "#e02020"
                ]
              },
              "size": {
                "type": "number",
                "minimum": 4,
                "maximum": 64,
                "description": "Marker height in CSS pixels (multiplied by `scale`). Default depends on the shape.",
                "examples": [
                  20
                ]
              },
              "strokeColor": {
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
                "description": "Outline color (default white where the shape has an outline).",
                "examples": [
                  "#ffffff"
                ]
              },
              "strokeWidth": {
                "type": "number",
                "minimum": 0,
                "maximum": 8,
                "description": "Outline width in px; 0 = none. `dot` and `pin` have a thin default outline.",
                "examples": [
                  1.5
                ]
              },
              "icon": {
                "type": "string",
                "maxLength": 200000,
                "description": "Custom icon instead of the shape: an SVG/PNG `data:` URI, or an https URL on a host the server allows (`WHEREBOX_ICON_HOSTS`). SVGs with external references or scripts are rejected.",
                "examples": [
                  "data:image/svg+xml;base64,PHN2Zy8+"
                ]
              },
              "anchor": {
                "type": "string",
                "enum": [
                  "center",
                  "bottom"
                ],
                "description": "Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).",
                "examples": [
                  "bottom"
                ]
              }
            },
            "description": "Marker style; every field is optional and falls back to the role default."
          },
          "leader": {
            "default": true,
            "description": "When no free spot is next to the marker, place the label further out with a thin leader line.",
            "examples": [
              true
            ],
            "type": "boolean"
          }
        },
        "description": "A point on the map: coordinates or a place name, with an optional label and marker."
      }
    },
    "width": {
      "default": 600,
      "description": "Image width in CSS px (the output is width × `scale` pixels).",
      "examples": [
        468
      ],
      "type": "integer",
      "minimum": 64,
      "maximum": 2048
    },
    "height": {
      "default": 400,
      "description": "Image height in CSS px, including the title band if any.",
      "examples": [
        280
      ],
      "type": "integer",
      "minimum": 64,
      "maximum": 2048
    },
    "scale": {
      "default": 1,
      "description": "Pixel ratio for high-DPI output (2 = retina).",
      "examples": [
        2
      ],
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "format": {
      "default": "png",
      "type": "string",
      "enum": [
        "png",
        "jpeg",
        "webp"
      ],
      "description": "Image format (GET can also use the path extension: /v1/map.png, .jpg, .webp).",
      "examples": [
        "png"
      ]
    },
    "quality": {
      "default": 90,
      "description": "JPEG/WebP quality.",
      "examples": [
        90
      ],
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "padding": {
      "default": 0.04,
      "description": "Space around the framed content as a fraction of the image size.",
      "examples": [
        0.04
      ],
      "type": "number",
      "minimum": 0,
      "maximum": 0.45
    },
    "projection": {
      "default": "mercator",
      "type": "string",
      "enum": [
        "mercator",
        "globe",
        "auto"
      ],
      "description": "Map projection. `mercator` is the usual flat web map. `globe` draws an orthographic globe, which keeps continent-spanning routes and high latitudes true to shape; the content must fit on one hemisphere (within 85° of the view center), and neighbor labels are not available. `auto` picks the globe when the content spans more than 50° or Mercator would stretch it more than 2.5× between its lowest and highest latitude, else Mercator.",
      "examples": [
        "globe"
      ]
    },
    "globe": {
      "default": {},
      "type": "object",
      "properties": {
        "view": {
          "default": "full",
          "description": "How much of the globe to show. `full` (default): the whole globe, centered on your content, with space around it; recognizable at a glance as a globe. `fit`: zoomed in until the content fills the image; a larger scale with more detail along the route, but only part of the globe is visible.",
          "examples": [
            "full"
          ],
          "type": "string",
          "enum": [
            "full",
            "fit"
          ]
        }
      },
      "description": "Globe options (with `projection` `globe`, or `auto` when it picks the globe)."
    },
    "basemap": {
      "default": {},
      "type": "object",
      "properties": {
        "preset": {
          "default": "locator-relief",
          "type": "string",
          "enum": [
            "locator-relief",
            "light",
            "dark",
            "none"
          ],
          "description": "Built-in basemap: shaded relief (Wikipedia locator style), light, dark, or `none`: no map at all, only a plain `background` color with your area outline, shapes, routes and points on it (the \"outline of Texas with a star\" look). No key needed.",
          "examples": [
            "locator-relief"
          ]
        },
        "styleUrl": {
          "description": "Any MapLibre style.json URL; overrides `preset`. `{key}` in the URL is replaced with `providerKey`.",
          "examples": [
            "https://api.maptiler.com/maps/streets-v2/style.json?key={key}"
          ],
          "type": "string",
          "format": "uri"
        },
        "providerKey": {
          "description": "Key for a commercial style (prefer the `X-Provider-Key` header so it stays out of URLs).",
          "examples": [
            "your-provider-key"
          ],
          "type": "string",
          "maxLength": 200
        },
        "background": {
          "description": "Background color for preset `none` (default white): any hex color, or `transparent` for a PNG/WebP with a transparent background that sits on any page. Labels, outline and attribution switch to light colors on a dark background. Only valid with preset `none`; `transparent` does not work with JPEG.",
          "examples": [
            "#000000"
          ],
          "anyOf": [
            {
              "type": "string",
              "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
            },
            {
              "type": "string",
              "const": "transparent"
            }
          ]
        }
      },
      "description": "The map underneath: a built-in preset or your own style."
    },
    "highlight": {
      "default": {},
      "type": "object",
      "properties": {
        "fade": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "How much the surroundings are washed out: 0 = not at all, 1 = fully covered.",
          "examples": [
            0.45
          ]
        },
        "fadeColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Color the surroundings fade towards.",
          "examples": [
            "#ffffff"
          ]
        },
        "outlineColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Area outline color.",
          "examples": [
            "#555555"
          ]
        },
        "outlineWidth": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Area outline width in px; 0 = none.",
          "examples": [
            1.1
          ]
        },
        "tint": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Optional color tint drawn over the area.",
          "examples": [
            "#d03030"
          ]
        },
        "tintOpacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Opacity of `tint`.",
          "examples": [
            0.15
          ]
        },
        "subdivisions": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "string",
              "const": "auto"
            },
            {
              "type": "integer",
              "minimum": 3,
              "maximum": 11
            }
          ],
          "description": "Inner admin borders: `auto` draws the next level that splits the area, a number forces that admin level, `false` hides them.",
          "examples": [
            "auto"
          ]
        },
        "subdivisionColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Color of the inner admin borders.",
          "examples": [
            "#8a8a8a"
          ]
        },
        "subdivisionWidth": {
          "type": "number",
          "minimum": 0,
          "maximum": 6,
          "description": "Width of the inner admin borders in px.",
          "examples": [
            0.6
          ]
        },
        "desaturate": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Outside the area: 0 = full color, 1 = grayscale (applied on top of `fade`).",
          "examples": [
            0.8
          ]
        },
        "blur": {
          "type": "number",
          "minimum": 0,
          "maximum": 20,
          "description": "Outside the area: blur radius in CSS px; 0 = sharp.",
          "examples": [
            1.5
          ]
        },
        "subArea": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "A name (\"Czechia\", \"Zlínský kraj\"), or an id: `iso:CZ`, `iso:CZ-72`, `osm:r51684`, `wikidata:Q213`.",
              "examples": [
                "Czechia"
              ]
            },
            {
              "type": "object",
              "properties": {
                "query": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200,
                  "description": "Name or id, as in the string form.",
                  "examples": [
                    "Nová Ves"
                  ]
                },
                "level": {
                  "description": "Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).",
                  "examples": [
                    8
                  ],
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 11
                },
                "country": {
                  "description": "Only match areas inside this ISO 3166-1 alpha-2 country.",
                  "examples": [
                    "CZ"
                  ],
                  "type": "string",
                  "minLength": 2,
                  "maxLength": 2
                }
              },
              "required": [
                "query"
              ],
              "description": "A name lookup narrowed by admin level and/or country, for ambiguous names."
            },
            {
              "type": "object",
              "properties": {
                "geojson": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "Polygon",
                        "MultiPolygon",
                        "Feature"
                      ],
                      "description": "GeoJSON type.",
                      "examples": [
                        "Polygon"
                      ]
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": {},
                  "description": "A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries."
                }
              },
              "required": [
                "geojson"
              ],
              "description": "Your own area geometry instead of a lookup."
            }
          ],
          "description": "A second, smaller area highlighted inside the framed one (e.g. a region within its country).",
          "examples": [
            "Zlínský kraj"
          ]
        },
        "subAreaColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Fill and outline color of `subArea`.",
          "examples": [
            "#d03030"
          ]
        },
        "subAreaOpacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Fill opacity of `subArea`.",
          "examples": [
            0.35
          ]
        },
        "subAreaOutlineWidth": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Outline width of `subArea` in px; 0 = none.",
          "examples": [
            1.2
          ]
        }
      },
      "description": "How the area stands out. Unset fields use the basemap preset's defaults (see the presets reference)."
    },
    "attribution": {
      "default": "bottom-right",
      "description": "Corner for the data attribution, or `none` to leave it off the image. The data licenses (OpenStreetMap ODbL, and Natural Earth/terrain credits where used) still require it: with `none` you must show the attribution next to the image yourself. The text to show is returned in the `X-Attribution` response header.",
      "examples": [
        "bottom-right"
      ],
      "type": "string",
      "enum": [
        "bottom-right",
        "bottom-left",
        "top-right",
        "top-left",
        "none"
      ]
    },
    "logo": {
      "default": "bottom-left",
      "description": "Corner for the small `wherebox.dev` mark (9.5 px text), or `none` to hide it. Hiding the logo requires a logo-removal license (see the Fair use guide); it is not enforced technically.",
      "examples": [
        "bottom-left"
      ],
      "type": "string",
      "enum": [
        "bottom-right",
        "bottom-left",
        "top-right",
        "top-left",
        "none"
      ]
    },
    "legend": {
      "type": "object",
      "properties": {
        "position": {
          "default": "right",
          "type": "string",
          "enum": [
            "right",
            "left",
            "top",
            "bottom"
          ],
          "description": "Side of the map the legend panel goes on.",
          "examples": [
            "right"
          ]
        },
        "title": {
          "description": "Heading above the legend entries.",
          "examples": [
            "Stops"
          ],
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "size": {
          "default": 13,
          "description": "Legend text size in CSS px; the numbered circles scale with it.",
          "examples": [
            13
          ],
          "type": "number",
          "minimum": 8,
          "maximum": 32
        },
        "color": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Legend text color (default: the theme label color).",
          "examples": [
            "#1a1a1a"
          ]
        },
        "background": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Legend panel background (default: white, near-black on the dark preset, or the `background` of preset `none`).",
          "examples": [
            "#ffffff"
          ]
        },
        "badgeColor": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Fill of the numbered circles (default: each point's marker color; route ends use the route color).",
          "examples": [
            "#e02020"
          ]
        },
        "badgeTextColor": {
          "default": "#ffffff",
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Number color inside the circles.",
          "examples": [
            "#ffffff"
          ]
        }
      },
      "description": "A classic map legend. With it, every labeled point (and labeled route end) is drawn as a numbered circle instead of its label, and the panel lists \"number – label\" pairs on the chosen side. The panel is inside the requested width×height; the map gets the rest."
    },
    "neighbors": {
      "type": "object",
      "properties": {
        "show": {
          "default": "name",
          "type": "string",
          "enum": [
            "name",
            "code",
            "flag",
            "flag+code",
            "flag+name"
          ],
          "description": "What to show for each neighboring country: its name, its international vehicle registration code (D, A, SK…), its flag, or a flag with code/name.",
          "examples": [
            "flag+code"
          ]
        },
        "which": {
          "default": "touching",
          "description": "`touching` = countries bordering the area; `visible` = every other country in the frame.",
          "examples": [
            "touching"
          ],
          "type": "string",
          "enum": [
            "touching",
            "visible"
          ]
        },
        "fit": {
          "default": "extend",
          "description": "When a label does not fit in the visible part of its country: `extend` grows the image on that side (the output becomes larger than width×height; see `X-Image-Width`), `shrink` reduces the label to 70 %, `drop` omits it.",
          "examples": [
            "extend"
          ],
          "type": "string",
          "enum": [
            "extend",
            "shrink",
            "drop"
          ]
        },
        "size": {
          "default": 12,
          "description": "Text size in CSS px; flags are sized to match.",
          "examples": [
            12
          ],
          "type": "number",
          "minimum": 6,
          "maximum": 32
        },
        "color": {
          "type": "string",
          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
          "description": "Text color (default: the theme's muted label color).",
          "examples": [
            "#666666"
          ]
        },
        "uppercase": {
          "default": false,
          "description": "Uppercase country names.",
          "examples": [
            true
          ],
          "type": "boolean"
        },
        "max": {
          "default": 12,
          "description": "At most this many countries are labeled (largest visible first).",
          "examples": [
            12
          ],
          "type": "integer",
          "minimum": 1,
          "maximum": 30
        }
      },
      "description": "Label the countries around the area (needs an `area`)."
    },
    "worldview": {
      "description": "Draw country borders as this country sees them (ISO 3166-1 alpha-2, e.g. `in`, `cn`, `us`, `ma`). Replaces the basemap's country and disputed borders with Natural Earth's borders for that worldview, and uses its country shapes for a highlighted country and for neighbor labels. Regions, cities and everything below country level stay OpenStreetMap. Default: the basemap's borders (OpenStreetMap, on-the-ground control).",
      "examples": [
        "in"
      ],
      "type": "string",
      "enum": [
        "ar",
        "bd",
        "br",
        "cn",
        "de",
        "eg",
        "es",
        "fr",
        "gb",
        "gr",
        "id",
        "il",
        "in",
        "it",
        "jp",
        "kr",
        "ma",
        "nl",
        "np",
        "pk",
        "pl",
        "ps",
        "pt",
        "ru",
        "sa",
        "se",
        "tr",
        "tw",
        "ua",
        "us",
        "vn"
      ]
    },
    "lang": {
      "description": "Label language (ISO 639-1). Default: local names (Deutschland, Polska), as on Wikipedia locator maps.",
      "examples": [
        "en"
      ],
      "type": "string",
      "pattern": "^[a-z]{2,3}$"
    }
  },
  "description": "Everything about one map image. Without an `area`, the map is framed on routes, shapes and points (or `bounds`)."
}