Request Parameters

Send as JSON body with Content-Type: application/json.

Core Parameters

Parameter	Type	Required	Description
`brand`	string	Yes	Brand name, stock ticker, or alias (e.g. `"Starbucks"`, `"SBUX"`, `"McDonalds"`)
`country`	string	No	ISO 3166-1 alpha-2 code (e.g. `"US"`, `"GB"`). Default: all countries
`state`	string	No	State/province code (e.g. `"CA"`, `"TX"`)
`city`	string	No	City name filter
`postcode`	string	No	Zip/postal code filter (e.g. `"07020"`, `"SW1A 1AA"`)
`radius_km`	number	No	Radius in km from city center. Requires `city` to be set
`format`	string	No	`"json"` \| `"csv"` \| `"geojson"` \| `"png"` \| `"jpeg"`. Default: `"json"`

💡

The brand parameter accepts brand names, stock tickers (e.g. SBUX, MCD, WMT), and common name variations (e.g. McDonalds, HomeDepot). See Available Brands for the full alias list.

Format options

Format	Content-Type	Description
`json`	`application/json`	Structured location data (default)
`csv`	`text/csv`	Comma-separated values with auto-download header
`geojson`	`application/geo+json`	RFC 7946 GeoJSON FeatureCollection
`png`	`image/png`	Rendered map image
`jpeg`	`image/jpeg`	Rendered map image (smaller file size)

Map Rendering Parameters

These parameters only apply when format is "png" or "jpeg".

Parameter	Type	Required	Description
`width`	number	No	Image width in pixels. Default: `1200`, max: `4096`
`height`	number	No	Image height in pixels. Default: `800`, max: `4096`
`style`	string	No	Map theme. Default: `"light"`
`marker_color`	string	No	Hex color for markers (e.g. `"#FF0000"`). Default: `"#FF0000"`
`include_legend`	boolean	No	Show brand name + count overlay. Default: `false`
`heatmap`	boolean	No	Render a density heatmap instead of pin markers. Default: `false`

Available map styles

Style	Description
`light`	Clean, warm. Default.
`dark`	Dark background
`voyager`	Detailed, CartoDB Voyager
`pitchbook`	Finance-style blues and grays
`slate`	Muted, neutral
`warm`	Earthy tones

Viewport Control

Control the map's zoom level, center point, or visible area. All optional — when omitted, the map auto-fits to show all returned locations.

Parameter	Type	Required	Description
`zoom`	number	No	Fixed zoom level (0–20). Use with `center`.
`center`	[lat, lng]	No	Map center point. Use with `zoom`. Example: `[40.7, -74.0]`
`bounds`	[[sw_lat, sw_lng], [ne_lat, ne_lng]]	No	Explicit bounding box. Example: `[[24, -125], [50, -66]]` for continental US
`padding`	number	No	Pixels of padding inside bounds. Default: `40`, max: `200`

Priority: center + zoom overrides bounds, which overrides auto-fit.

// Auto-fit (default) — zoom to show all locations
{"brand": "Starbucks", "format": "png"}
 
// Full US view
{"brand": "Starbucks", "format": "png", "bounds": [[24, -125], [50, -66]]}
 
// Zoom into NYC
{"brand": "Starbucks", "format": "png", "center": [40.7, -74.0], "zoom": 11}

Focus Mode Parameters

Focus Mode isolates a single country on the rendered map. See the dedicated Focus Mode page for details.

Parameter	Type	Required	Description
`focus_country`	string	No	ISO alpha-2 code. Masks everything outside this country
`focus_region`	string	No	`"conus"` \| `"alaska"` \| `"hawaii"`. US only. Requires `focus_country="US"`
`show_neighbors`	boolean	No	Show faint gray neighboring countries. Default: `true`

Endpoint JSON Response