Data Coverage

Where BrandMappr's location data comes from, and what's in and out of scope.

Sources

Four sources contribute rows. Each is licensed for commercial reuse and credited in the X-Attribution response header.

Reconciliation

Rows from all four sources are joined per brand and region, deduplicated within a 100m bbox tolerance, and assigned a confidence score that reflects source agreement and a sparse-region noise penalty. When the same physical store appears in multiple sources, contributing source IDs are preserved on the reconciled row (see alias_sources).

The reconciliation runs as a pipeline against a recent snapshot of each source, producing a deterministic Parquet output that's then loaded into the production database. The order in which sources contribute to a brand is per-brand and per-region — there is no single "primary" source globally.

Scope

The v1 data product covers consumer-facing storefronts and POIs only. Corporate footprint is out of scope.

Multi-company maps requested via stock ticker (a corporate identifier) return the company's storefront locations, not its corporate sites. A corporate-footprint product line is planned but separate.

Coverage strength by category

Coverage is uneven across categories. Roughly:

• Strong — fast food, coffee, gas stations, mass-market retail chains (clothing, electronics, home improvement), pharmacies in developed markets.
• Moderate — banks, hotels, supermarkets, specialty retail, telecom retail.
• Weaker — regional and local-only chains, niche specialty retail, professional services with storefronts.
• Sparse or absent — categories with little public street presence (B2B services, finance back office, manufacturing) and any non-storefront business type.

Coverage is also stronger in developed markets than in emerging markets, reflecting the underlying source data.

Confidence floor

Every reconciled row carries a confidence score on [0,1] reflecting source agreement. Data formats (json, csv, geojson) serve only rows scoring confidence ≥ 0.6 and exclude OpenStreetMap-origin rows. Rendered map images (png, jpeg) draw markers from all sources, including OSM. The floor is fixed — there is no request parameter to change it.

Storefront type

Filter to a specific kind of consumer-facing location with the storefront_type parameter. Values: full_retail | small_format | pickup | studio | other. Useful when a brand operates a mix — for example, separating standard IKEA stores from IKEA Planning Studios.

Provenance fields

When include_provenance: true, JSON and GeoJSON responses gain five extra fields per row. CSV always omits these (CSV stays at the fixed 11-field shape for compatibility).

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

Rows that haven't yet been touched by the multi-source pipeline return null for every provenance field.

Response headers

Every response carries two attribution headers:

• X-Attribution — All four contributing sources, alphabetical: All The Places, Foursquare, Overture, OpenStreetMap contributors. Returned on every response regardless of which sources actually contributed, for license compliance. Full license notices: /ATTRIBUTION.txt (opens in a new tab).
• X-Data-Sources — Comma-separated list of sources that actually contributed rows to the current response, alphabetical.

Source policy per format

Data formats (json, csv, geojson) and ad-hoc dataset downloads contain rows sourced from Overture, Foursquare Open Source Places, and All The Places only — OpenStreetMap-origin rows are excluded from raw-data deliverables and appear only in rendered map images (png, jpeg), which carry OpenStreetMap attribution. Data formats also apply a fixed confidence ≥ 0.6 floor.

A response-level completeness signal (coverage_confidence — "is this result set complete relative to ground truth?") is planned. It depends on a curated ground-truth reference set that's still being built and will return null until the metric is wired.

Refresh cadence

The reconciled dataset is refreshed on a regular cadence by a multi-stage pipeline. Per-source freshness varies: ATP runs weekly (highest), Overture and Foursquare update monthly, OSM is pulled on the same monthly schedule. Aliases (ticker mappings, name variants, CJK transliterations) are recomputed on the same cadence.

Every row carries a last_updated value reflecting its most recent reconciled refresh. Post-multi-source, last_verified distinguishes "when this row was last cross-checked against a source" from "when its fields were last touched."

Known limits

• Verified data locations: ~2.0M (confidence ≥ 0.6, OSM excluded) across ~6,600 brands with sellable data / 242 countries. 156,500+ brands are mapped in total; the full reconciled pool is ~6.9M rows; the OSM-origin remainder is used for map images only, not sold as data.
• Mainland China and South Korea undercount in all data products: both countries restrict map-data export, so every contributing open source is thin there. Brands with large CN/KR footprints (KFC China ~11.6K stores, 7-Eleven South Korea ~14K stores) read well below officially reported global counts. US/CA/EU/JP/TW/TH majors track official figures closely.
• Japan: convenience-store coverage depends on official store-locator harvesting. 7-Eleven Japan's full fleet (~21,500 stores) is delivered in data products, harvested directly from the chain's official store locator. Convenience chains not yet harvested may still carry part of their Japanese density only in OpenStreetMap — those rows appear on rendered images (with attribution) but are excluded from data deliverables under the licensing policy above.
• Long tail: the deeper into per-brand rank-order, the more coverage relies on OSM alone — and OSM-only brands are image-only (OSM rows are excluded from data products by licensing policy).
• No retroactive backfill: brands or regions added to source feeds appear in the next refresh, not retroactively in historical responses.
• Closure detection is lagging: a permanently closed store may persist in source feeds for several refresh cycles before falling out.
• Pin precision varies by source: Overture and FSQ provide resolved centroids; OSM nodes are mapper-precision; ATP locations follow whatever the retailer publishes. The 100m reconciliation tolerance reflects this.

Related

• response-json — full per-row field reference
• parameters — all request parameters in one place
• brands — brand search, aliases, and top brands by count