Image Response

When format is "png" or "jpeg", the response body is the raw image binary. The response is not JSON.

Response headers

Header	Type	Description
`Content-Type`	string	`image/png` or `image/jpeg`
`X-Location-Count`	number	Number of locations plotted
`X-Brand`	string	Brand name queried
`X-Region`	string	Region filter applied
`X-Render-Time`	string	Render duration (e.g. `"4231ms"`)
`X-Cached`	boolean	Whether the image was served from cache
`Cache-Control`	string	`public, max-age=86400`
`X-Credits-Charged`	number	Credits deducted for this request
`X-Credits-Remaining`	number	Credits remaining on your key
`X-Credits-Low`	boolean	Present and `true` when balance drops below 50

Handling image responses

The response body is binary data, not JSON. Handle it according to your platform:

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_key"
  },
  body: JSON.stringify({
    brand: "Starbucks",
    format: "png",
    country: "US",
    style: "light"
  })
});
 
// Browser: convert to blob URL
const blob = await res.blob();
const url = URL.createObjectURL(blob);
 
// Node.js: write to file
const buffer = Buffer.from(await res.arrayBuffer());
fs.writeFileSync("map.png", buffer);

💡

Images are cached for 24 hours (max-age=86400). The X-Cached header tells you whether you received a cached copy. Identical requests within the cache window cost 0 credits after the first call.

Rendering options

See Parameters for the full list. Key options for image output:

width / height — up to 4096×4096 pixels
style — six themes: light, dark, voyager, pitchbook, slate, warm
marker_color — any hex color
heatmap — density heatmap instead of individual pins
include_legend — brand name and location count overlay
focus_country — isolate a single country (see Focus Mode)

JSON Response Focus Mode