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 18,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.

Leverage browser caching

Image responses include Cache-Control: public, max-age=86400. Identical requests within 24 hours will be served from your browser/CDN cache. Check the X-Cached header to confirm.

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.