Filter locations to a region

Server-side filters narrow the result set before it hits the wire. Cheaper than fetching everything and filtering client-side, and the credit charge scales with what you actually get back.

By country

ISO-3166 alpha-2 codes:

curl -X POST https://api.brandmappr.com/api/v1/location-map \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"brand":"Starbucks","country":"GB"}'

By state (US)

State codes are USPS two-letter:

-d '{"brand":"Starbucks","country":"US","state":"CA"}'

State filtering outside the US works for any country whose OSM data has addr:state populated, but coverage varies — start with country-level for non-US queries.

By city

-d '{"brand":"Starbucks","country":"US","city":"Seattle"}'

City names match against addr:city. They're case-insensitive and exact — "New York" matches, "NYC" doesn't. If you don't get expected results, check the directory entry for spelling.

By postcode

-d '{"brand":"Starbucks","country":"US","postcode":"98101"}'

By radius from a city

-d '{"brand":"Starbucks","city":"Seattle","country":"US","radius_km":10}'

Radius applies on top of the city center. Useful for "every Starbucks within 10km of downtown."

By bounding box (image responses)

For map renders, bounds controls the viewport without pre-filtering the result set:

-d '{"brand":"Starbucks","format":"png","bounds":[40.7,-74.0,40.8,-73.9]}'

bounds is [south, west, north, east]. Locations outside the box are still in the response data — they're just not on the rendered image.

Filter precedence

Filters AND together. Country + state + city all set means "all three match." There's no OR mode; for unions, run separate queries and merge.

Quick reference