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"). *Not required when tickers is set |
tickers | string[] | No | Array of up to 5 stock tickers (e.g. ["SBUX","MCD"]). Renders one image with each company in a distinct marker color. Requires format "png" or "jpeg". Used instead of brand when set |
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". Single-brand only |
marker_colors | string[] | No | Array of hex colors overriding the auto palette on multi-company (tickers) maps |
marker_radius | number | No | Marker dot radius in pixels. Default: 5, range: 1–50 |
include_legend | boolean | No | Render a legend overlay. Single-brand: brand name + count. Multi-company (tickers): color→company. 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 Map Parameters
Setting focus_country renders that single country as a filled vector shape with no basemap underneath. Image responses only (format "png" or "jpeg"). See the dedicated Focus Map page for details.
| Parameter | Type | Required | Description |
|---|---|---|---|
focus_country | string | No | ISO 3166-1 alpha-2 code (e.g. "US") for a single-country shape, or "auto" to render every country the brand has locations in as a single multi-country map. |
fill_color | string | No | Hex fill color for the country shape. Default: "#E5E7EB" |
outline_color | string | No | Hex color for the country outline. Default: "#9CA3AF" |
outline_width | number | No | Outline width in pixels. Default: 1.5, range: 0–20 |
background | string | No | "white" | "transparent". Default: "white". "transparent" is PNG-only; jpeg falls back to white |
conus | boolean | No | US lower-48 only. When focus_country is "US", drops Alaska/Hawaii from the shape and any markers projecting off-canvas. Ignored for non-US focus_country. Default: false |
mainland_only | boolean | No | Generic mainland-only filter that works on any country with overseas territories (France, Norway, Denmark, etc.). Keeps the polygon containing the bulk of the brand's markers — drops far-flung territories that would otherwise wreck framing. For focus_country: "US", equivalent to conus: true. Default: false |
regions | boolean | No | Draw 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 absent. Default: false |
Data Quality Parameters
Control the precision vs recall trade-off on data-format responses (json, csv, geojson). All optional; defaults bias toward recall. See Data Coverage for the full model.
| Parameter | Type | Required | Description |
|---|---|---|---|
quality | string | No | Named confidence profile: "verified" (≥ 0.8), "balanced" (≥ 0.6), "recall" (no floor). Recommended default for analytical use is "balanced". |
min_confidence | number | No | Explicit confidence floor in [0, 1]. Wins over quality when both are set. |
storefront_type | string | No | Filter to one type: "full_retail" | "small_format" | "pickup" | "studio" | "other". Useful when a brand operates a mix (e.g. standard IKEA stores vs IKEA Planning Studios). |
include_provenance | boolean | No | When true, JSON/GeoJSON responses gain per-row source_types, confidence, storefront_type, alias_sources, and last_verified fields. CSV always omits these. Default: false |