Focus Map

Focus Map renders a single country as a projection-correct filled vector shape — no basemap. The country is drawn with a configurable fill and outline, and the brand's locations are plotted on top. Useful for clean, branded maps and infographic exports.

Projection selection is automatic: the US uses Albers (geoAlbersUsa) with Alaska and Hawaii in proper insets; any other country uses a fitted equal-area conic. Set conus: true to render the US contiguous lower-48 only. Set focus_country: "auto" to render every country the brand has locations in as a single multi-country map.

💡

Focus Map applies to image responses only (format: "png" or "jpeg"). It is enabled by setting focus_country.

Parameters

Parameter	Type	Default	Description
`focus_country`	string	—	ISO 3166-1 alpha-2 code (e.g. `"US"`, `"AT"`, `"JP"`) for a single-country shape, or `"auto"` for a multi-country map covering every country the brand has locations in.
`fill_color`	string	`#E5E7EB`	Hex fill color for the country shape
`outline_color`	string	`#9CA3AF`	Hex color for the country outline
`outline_width`	number	`1.5`	Outline width in pixels (0–20)
`background`	string	`"white"`	`"white"` or `"transparent"` (transparent is PNG-only — see below)
`conus`	boolean	`false`	When `focus_country` is `"US"`, renders the contiguous lower-48 only (drops Alaska, Hawaii, and territories from the shape and any markers projecting off-canvas). Ignored for non-US `focus_country`.
`mainland_only`	boolean	`false`	Generic version of `conus` for any country with overseas territories (France with Polynesia/Réunion, Norway with Svalbard, Denmark with Greenland, etc.). Filters the country to the polygon containing the bulk of the brand's markers — preventing far-flung territories from shrinking the mainland to a corner. For `focus_country: "US"`, behaves identically to `conus: true`.
`regions`	boolean	`false`	Draws internal admin-1 boundaries (states/provinces) inside the focus country. Requires Natural Earth 10m admin-1 data hosted on the tiles proxy; skips silently if the data file is absent.

Example request

{
  "brand": "Starbucks",
  "format": "png",
  "focus_country": "AT",
  "fill_color": "#E5E7EB",
  "outline_color": "#9CA3AF",
  "outline_width": 1.5,
  "background": "white"
}

Renders a map of Austria as a light-gray shape with the brand's locations marked on top.

Transparent background

Set background: "transparent" to render the country shape and markers on a transparent canvas — to drop onto any background or slide. Transparent output is PNG-only; JPEG has no alpha channel, so a transparent request on jpeg falls back to white.

Combining with other parameters

Focus Map works with the other image parameters — marker_color, marker_radius, width, height, include_legend:

{
  "brand": "McDonald's",
  "format": "png",
  "country": "DE",
  "focus_country": "DE",
  "fill_color": "#F3F4F6",
  "outline_color": "#6B7280",
  "marker_color": "#DA291C",
  "marker_radius": 6,
  "width": 1600,
  "height": 1000,
  "include_legend": true
}

This renders a 1600×1000 map of McDonald's locations in Germany as a light-gray shape with red markers and a legend overlay.

Auto multi-country mode

Use focus_country: "auto" when you don't know (or don't want to specify) the brand's geographic footprint:

{
  "brand": "Starbucks",
  "format": "png",
  "focus_country": "auto",
  "width": 1200,
  "height": 700,
  "fill_color": "#F0FDF4",
  "outline_color": "#15803D",
  "marker_color": "#16A34A"
}

The renderer derives the list of countries from the rendered markers, fetches each country's admin-0 geometry, drops empty non-contiguous regions per-country (a US brand with no Alaska locations gets a CONUS-shaped US, no Alaska blob), and projects all kept features with geoNaturalEarth1 fitted to the canvas.

Differences from single-country focus mode:

Projection is always geoNaturalEarth1 (not Albers or per-country conic).
conus and regions have no effect (they are US-Albers-specific).
Country shape precision uses Natural Earth 110m boundaries, which are simplified — the per-polygon "contains a marker" filter is bbox-only (not strict point-in-polygon) to tolerate the simplification.

Image Response Available Brands