About Blockfit
Method, formulas and limits
Blockfit is built for one user: the vacancy programme of a business improvement district (BID), which works to fill empty main-street storefronts. It is a reverse recommender for storefronts: given an empty unit, it asks which kind of shop should open on the block and which brand to court, then writes the email from the BID to the unit's landlord. Plain code does the maths; an agent decides what to look at and writes the email.
The Gap
Demand is how strongly the block's taste points at a concept, measured with Qloo. It is a rank: where the concept's lift sits among all the concepts this block's taste points at, so a block never shows a wall of 100s, and the lift itself (2.4x a typical venue) is always printed beside it. A weak lift cannot score high just by ranking first. Supply is how many strong venues of that concept already sit inside the radius, also from Qloo's place data. Both run from 0 to 100.
- share_block(t)
- = sum of affinity of taste-similar venues with tag t / sum of affinity of all of them
- share_base(t)
- = the same on a baseline built from typical venues across the metro
- lift(t)
- = (share_block + 0.01) / (share_base + 0.01)
- demand(C)
- = percentile of lift(C) among the block's candidate concepts, times strength(lift)
- strength(lift)
- = min(1, ln(lift) / ln(1.8)), so lift 1.0 gives 0 and lift 1.8 or more gives 1
- supplyLoad(C)
- = sum over existing venues of (0.4 + 0.6 x popularity)
- saturation(C)
- = 100 x (1 - exp(-supplyLoad / s0)), with s0 = 3 x (radius / 800)
- gap(C)
- = demand x (1 - saturation / 100)
| Verdict | Rule |
|---|---|
| Unserved | demand at least 55 and saturation at most 40 |
| Contested | demand at least 55, saturation up to 75 |
| Saturated | demand at least 55, saturation above 75 |
| Latent | demand from 35 to 55 (or saturated, when saturation is above 75) |
| Lower fit | demand below 35 |
Confidence is high with at least 40 census venues and 100 taste-similar venues, medium with 15 and 50, and low otherwise. Low confidence is said first, in the interface and in the memo.
How Qloo powers it
Without Qloo the demand half of the Gap disappears, and so does Block DNA, brand fit and the proof in the email. What is left is a venue count. Every report has a Without Qloo switch that shows exactly that, from the report's own data.
| Interface element | Qloo capability | Call |
|---|---|---|
| Census and supply | Place insights, point and radius | /v2/insights (place) |
| Demand and the Gap | Taste similarity from seed signals | /v2/insights (place, signals) |
| Audience lens | Demographic signals | signal.demographics.* |
| Tenant targets | Cross-category: places to brands | /v2/insights (brand) |
| Block DNA | Cross-category: places to artists, podcasts, shows | /v2/insights (artist, podcast, tv_show) |
The Evidence list on every report shows the exact calls, with parameters, status, time and result counts.
The agent and the memo
A tool-using model decides which Qloo-backed tools to call and groups candidate tags into concepts. Before it keeps a gap it tries to prove it wrong, cheapest attempt first: the concept will not fit the unit, the demand is just general popularity, or a strong venue of the same kind sits just outside the radius. The first attempt that works drops the gap, and every attempt is written to the report. The tools do all the maths, so results are repeatable and cacheable. If the agent fails or runs out of budget, the server runs the default plan itself and a result still appears.
The memo is checked before it is shown: every id must exist in the report, every number must match the evidence, every name must be in the evidence list, and there are no links or forecast words. One failed check triggers one retry, and then a plain summary built from the board.
Limits, stated plainly
- Taste fit is a proxy for fit, not a sales forecast. Nothing here predicts revenue, rent or footfall.
- The numbers depend on how much Qloo knows about a block. Thin coverage is flagged and lowers confidence.
- A concept can be missing for good reasons: zoning, lease costs, a hostile street. Walk the block.
- Scores compare by position within one analysis, not across blocks or across audience lenses.
Privacy and data
No accounts and no personal data. A session cookie, derived on the server from a keyed hash of your network address, meters the demo budget. IP addresses appear only as salted hashes in rate-limit keys that expire within two days. Share pages ask search engines not to index them. Reports contain the addresses people type and are visible to anyone with the link for 120 days, so please do not enter private addresses. A typed address is also kept in a lookup cache for up to a year. When the live geocoder is on, it is sent to OpenStreetMap's Nominatim service and, if that fails, to Photon (komoot); the offline demo sends it nowhere. Map tiles are loaded by your browser straight from OpenStreetMap. Qloo receives entity ids and coarse coordinates only. Qloo data is cached privately on the server and never published.
Licence and credits
Blockfit is open source under the MIT licence. Taste data and insights: Qloo. Maps: Leaflet with OpenStreetMap tiles, © OpenStreetMap contributors. Geocoding: Nominatim. Fonts: Ultra (Apache Licence 2.0) and Public Sans (SIL Open Font Licence). Third-party licences: full notices.