Skip to main content

Title & subtitle

Add up to two lines of text at the top of the map: a bold primary title and a smaller subtitle beneath it. The text gets its own band at the top, and the map is drawn below it, so the title doesn't cover the area you're mapping.

Examples​

Title and subtitle together

https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,IN:80,BR:60,RU:120&theme=dark&title=GDP%20per%20capita&subtitle=World%20Bank%202023
World choropleth with title 'GDP per capita' and subtitle 'World Bank 2023'

Title only

https://api.maproll.io/map.svg?scope=world&data=US:1&theme=light&title=Just%20a%20title
World map with title only, no subtitle row

Title, subtitle, and logo stacked

https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,DE:95&theme=dark&title=GDP%20per%20capita&subtitle=World%20Bank%202023&logo=true
World map with title, subtitle, logo, and attribution all visible

Parameters​

ParamTypeDefaultAllowedNotes
titlestring—Up to 120 characters in a JSON bodyRendered bold, centered, near the top of the map.
subtitlestring—Up to 160 characters in a JSON bodyRendered smaller and lighter, directly below the title. Without a title, it takes the title's line.

The character limits are enforced on POST /render/map, which rejects a longer string with 400. The URL endpoint does not enforce them — a 300-character title= renders, and simply runs off both edges of the image, because the text is drawn on a single line with no wrapping. Treat the limits above as the practical maximum in both cases.

Notes​

  • Both parameters are optional. Omitting both produces a clean map with no text at the top.
  • subtitle without title is drawn on the title's line, in the smaller subtitle style.
  • With bbox, the map is cropped to your rectangle, but land outside it can still show in the band behind the title. The area inside the bbox always sits below the title.
  • Text is centered horizontally in all cases. Left/right alignment is not currently configurable.
  • Title and subtitle reserve a band at the top of the canvas. When height is omitted, the image grows taller by that band and the map keeps its size. When you set height, the map is scaled down to fit below the band.
  • Spaces must be URL-encoded as %20 (or + in query strings). Special characters should be percent-encoded.
  • Theme-aware colors are used for the text, so the title remains legible on both light and dark backgrounds.