Performance Tips

JSON is instant, images take 3-8s

JSON responses return in under 500ms. Image rendering involves a headless browser and takes 3-8 seconds depending on location count and dimensions. Use JSON when you only need location data.

Filter by region to reduce render time

Rendering ~43,000 Starbucks markers globally is slower than rendering 3,000 in California. Use country, state, or city filters to scope results and speed up renders.

Caching

Map images are sent with Cache-Control: no-store — they're never browser- or CDN-cached, so every render reflects the latest data and parameters. Data responses (json/csv/geojson) are served from a short-lived server-side cache on repeat queries; check the X-Cached header (true/false) to see whether a data response was a cache hit.

Use smaller dimensions for thumbnails

Default image size is 1200x800. For thumbnails or previews, use 600x400 — this renders faster and produces smaller files. Maximum is 4096x4096.

Check X-Render-Time for benchmarking

Every image response includes the X-Render-Time header (e.g. "4231ms") measuring total server-side time. Use this to benchmark different parameter combinations.

# Check render time with verbose headers
curl -v -X POST https://api.brandmappr.com/api/v1/location-map \
  -H "x-api-key: bm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Starbucks","state":"CA","format":"png"}' \
  -o map.png 2>&1 | grep -i "x-render-time"

Reduce billing costs with filters

Credits scale with location count. Querying "Starbucks" nationwide (7,609 locations = 5 base credits) costs more than "Starbucks" in California (~1,000 locations = 2 base credits). See Billing & Credits for the full tier table.