Code Examples

Get locations as JSON

const res = await fetch("https://api.brandmappr.com/api/v1/location-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "bm_live_your_api_key_here"
  },
  body: JSON.stringify({
    brand: "Starbucks",
    country: "US"
  })
});
 
const data = await res.json();
console.log(`Found ${data.count} locations`);

Render a map image

const res = await fetch("https://api.brandmappr.com/api/v1/location-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "bm_live_your_api_key_here"
  },
  body: JSON.stringify({
    brand: "McDonald's",
    country: "US",
    state: "CA",
    format: "png",
    style: "light",
    marker_color: "#DA291C",
    focus_country: "US"
  })
});
 
const blob = await res.blob();
const url = URL.createObjectURL(blob);
document.getElementById("map").src = url;
 
// Check remaining credits
const creditsLow = res.headers.get("X-Credits-Low");
if (creditsLow === "true") {
  console.warn("Credits running low");
}

Focus Map (single country as a shape)

const res = await fetch("https://api.brandmappr.com/api/v1/location-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BRANDMAP_API_KEY
  },
  body: JSON.stringify({
    brand: "Starbucks",
    format: "png",
    focus_country: "US",
    fill_color: "#E5E7EB",
    outline_color: "#9CA3AF",
    outline_width: 1.5,
    background: "transparent",
    marker_color: "#00704A",
    marker_radius: 6,
    width: 1600,
    height: 1000
  })
});

Multi-company map (tickers)

curl -X POST https://api.brandmappr.com/api/v1/location-map \
  -H "x-api-key: bm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["SBUX", "MCD"],
    "country": "US",
    "format": "png",
    "marker_colors": ["#00704A", "#DA291C"],
    "marker_radius": 5,
    "include_legend": true
  }' \
  --output multi.png

Dark theme heatmap

curl -X POST https://api.brandmappr.com/api/v1/location-map \
  -H "x-api-key: bm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Dollar General",
    "format": "png",
    "heatmap": true,
    "style": "dark",
    "width": 1920,
    "height": 1080
  }' \
  --output heatmap.png

Inspect response headers

# Check render time, credits charged, and caching status
curl -v -X POST https://api.brandmappr.com/api/v1/location-map \
  -H "x-api-key: bm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Starbucks","state":"CA","format":"png","style":"slate","marker_color":"#00704A"}' \
  -o map.png 2>&1 | grep -E "^< X-"
 
# Example output:
# < X-Location-Count: 3182
# < X-Brand: Starbucks
# < X-Region: CA, US
# < X-Credits-Charged: 4
# < X-Credits-Remaining: 996
# < X-Render-Time: 4231ms
# < X-Cached: false

Filter by city and radius

# All Target stores within 50km of Chicago
res = requests.post(
    "https://api.brandmappr.com/api/v1/location-map",
    headers={"Content-Type": "application/json", "x-api-key": key},
    json={
        "brand": "Target",
        "country": "US",
        "city": "Chicago",
        "radius_km": 50
    }
)
 
data = res.json()
for loc in data["locations"]:
    print(f"{loc['name']} — {loc['address']}")

Performance Tips MCP Server