Code Examples

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 Mode with heatmap

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",
    focus_region: "conus",
    heatmap: true,
    style: "dark",
    width: 1920,
    height: 1080
  })
});

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",
    "focus_country": "US",
    "focus_region": "conus",
    "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 TipsMCP Server