What It Does
MapsWidget for Power BI is a custom visual that puts your property's real map — every building, every unit polygon, parking, amenities, in 2D or 3D — inside a Power BI report, colored by whatever column you choose.
Occupancy, rent, delinquency, work orders and turn status all live in Power BI already. What Power BI cannot show is
where they are: its map visuals plot a pin per address, so an entire 300-unit property collapses into one dot on a street.
| Question |
A standard map visual |
MapsWidget for Power BI |
| Which units are vacant? |
One pin for the whole property |
Each vacant unit shaded on its own building |
| Is the churn on one side of the property? |
Not answerable |
Visible immediately — clusters show up as blocks of colour |
| Do the top-rent units face the pool? |
Not answerable |
Amenities are on the map, next to the units |
| Which floor is the problem on? |
Not answerable |
Floor picker, per-floor unit shapes |
You bind a table of unit-level rows; the visual matches them to the Beans map of that property and colors each unit. Everything else — slicers, cross-filtering from other visuals, page filters, scheduled refresh — keeps working the way it already does.
No data preparation is required. No latitude/longitude columns, no shapefiles, no custom map registration. An address and a unit identifier are enough.
Requirements
| Item |
Requirement |
| Power BI |
Power BI Desktop (2023 release or later) or the Power BI service. Your tenant must allow custom visuals — either uploaded from a file or published to your organisational store. |
| Property coverage |
The property must be mapped by Beans, and the unit identifiers in your data must match the ones Beans holds. Ask your Beans contact to confirm coverage before you build the report. |
| Data |
One row per unit, with an address column and a unit column. Any number of additional columns. |
| Network |
The browser or Desktop client needs outbound access to www.beans.ai, api2.beans.ai and js.arcgis.com. Allow-list them if your organisation filters egress. |
Download & Install
- In Power BI Desktop, open the Visualizations pane, choose … → Import a visual from a file, and select the .pbiviz.
- Drop the MapsWidget for Power BI visual onto your report page.
- Open Format → Iframe and set Iframe URL to the map page Beans gave you — by default:
https://www.beans.ai/biv1/plugins/powerbi/iframe/powerbi.php
- Bind your fields as described below.
For a wider rollout, hand the file to your Power BI administrator to publish in your
organisational visuals store; report authors then add it without importing anything.
Binding Your Data
The visual has two field wells.
Column order in the Fields well is the contract — drag them in this order:
| Position |
Meaning |
Notes |
| 1st column |
Address |
The property address. Street, city and state is enough — Beans standardises it. Rows sharing an address are one property. |
| 2nd column |
Unit |
The unit identifier, exactly as your system writes it (A101, 2-14, …). |
| 3rd onward |
Data columns |
Anything: status, floorplan, beds, rent, days vacant, work orders, a score you calculated. Each becomes a filter and a colour option. |
A minimal binding looks like this:
Fields
1. Property Address 655 S Fair Oaks Ave, Sunnyvale, CA
2. Unit A101
3. Status Occupied
4. Floorplan A1
5. Rent 3100
Color by (default)
Status
Measures work as well as columns — drop an aggregated rent or a days-vacant measure in and it is treated as a numeric data column.
Color By
The optional
Color by (default) well decides how units are shaded when the report opens. Leave it empty and the map opens uncoloured; viewers can always pick a column themselves from the
Color By Column dropdown in the visual.
| Column type |
How units are coloured |
| Text / categorical |
A distinct colour per value, with a legend built into the filter list. Best for status, floorplan, leasing agent. |
| Numeric |
A single-hue gradient from light (low) to dark (high). Best for rent, days vacant, score. |
| Bed / bath counts |
Treated as categories rather than a gradient, since "2 beds" is a kind, not a quantity. |
Precedence is simple: the well sets the default, a viewer's own pick overrides it for their session, and if you later re-point the well the new default takes over again.
Reading the Map
| Control |
What it does |
| Filters rail |
One filter per data column, chosen to fit the data: toggles for yes/no, chips for a handful of values, a searchable checklist for many, a histogram for numeric ranges. Filtering dims the excluded units on the map in place, so you keep the property context. |
| Color By Column |
Re-colours the map, and moves that column's filter to the top with its colour legend. |
| Count / % |
Switches every count in the rail between absolute and share of the property. |
| Map / Data tabs |
The same filtered rows as a table, with the colour swatch alongside — useful for reading exact values or copying a list out. |
| Property picker |
Appears when the bound data spans several addresses. The map shows one property at a time; the picker switches between them, largest first. |
| Map buttons |
Satellite, sunlight, 3D immersive view, nearby points of interest, and a floor picker on multi-storey buildings. |
| Hover / click a unit |
Hover previews the unit's values; clicking opens a card with every bound column for that row. |
Filters & Refreshes
The visual is a normal Power BI citizen on the receiving side: slicers, page and report filters, cross-filtering from other visuals, and dataset refreshes all flow into it, and the map re-colours in place without reloading.
When new data arrives, the viewer's own settings are kept wherever they still make sense:
| Setting |
After an upstream filter change or refresh |
| Color By column |
Kept. |
| Filter selections |
Kept. Values that no longer exist in the data are dropped from the selection, and a notice explains why. |
| A filter you never narrowed |
Stays fully selected, so values that appear for the first time are included rather than silently hidden. |
| Count/%, active tab, selected property |
Kept, including across the report page being reopened in the same browser session. |
One direction only. Selecting units inside the map does not currently cross-filter the rest of the report page. Filter
into the visual with slicers; read
out of it visually or from the Data tab.
Settings
| Setting |
Where |
Meaning |
| Iframe URL |
Format → Iframe |
The Beans-hosted map page the visual embeds. Use the URL Beans provided; change it only when asked to, for example to pin a report to a specific release. |
| Color by (default) |
Fields pane |
See Color By. |
Data Handling
A few things happen to your rows on the way to the map. All of it is automatic; it is documented here so the numbers on screen are never a surprise.
| Rule |
Why |
| Rows with a blank address or blank unit are dropped |
There is nothing to place on the map. The count of dropped rows is reported when the data loads. |
| Units starting PARKING_ or STORAGE_ are dropped |
They are not residences; leaving them in distorts every count and percentage. |
| Amenity rows are dropped |
Names such as GYM, POOL, CLUBHOUSE or A-MAILROOM are recognised as amenities. They already appear on the map as amenities. |
| The address is standardised |
Beans resolves the address you send to the mapped property, so formatting differences between your system and ours do not matter. |
| Rows are grouped by address |
The map draws one property at a time; the picker switches between them. |
Limits
| Limit |
Detail |
| 30,000 rows |
Power BI's cap for the data sent to the visual. Comfortable for a portfolio of properties at unit level; filter upstream if you exceed it. |
| One property drawn at a time |
By design — unit-level detail only reads at property scale. Multiple addresses are supported through the picker. |
| Column names must be unique |
Two bound columns with the same display name collapse into one; rename one of them in the model. |
| No selection cross-filtering |
See Filters & Refreshes. |
Troubleshooting
| Symptom |
Cause |
| "Need at least two columns: address, then unit" |
Fewer than two fields are bound, or they are in the wrong order. The first must be the address, the second the unit. |
| The map draws, but no units are coloured |
The unit identifiers do not match the ones Beans holds for that property — a prefix, a leading zero, or a building letter is usually the difference. Send Beans a sample of your unit list. |
| The map lands somewhere unexpected |
The address resolved to a different property. Use the full street address including city and state. |
| Row counts are lower than your dataset |
Expected — see Data Handling. The excluded count is shown when the data loads. |
| "Some filters reset" notice |
An upstream filter removed every value a filter was narrowed to. The filter reopens fully selected rather than hiding everything. |
| Blank visual, no map |
Network egress to beans.ai or js.arcgis.com is blocked, or the Iframe URL is wrong. Check with your network team, then re-check Format → Iframe. |
| Two MapsWidget for Power BI visuals on a page share filter state |
Session settings are keyed to the bound columns and properties. Bind them differently, or ask Beans for an instance key. |
Privacy & Security
Your report data is not uploaded to Beans. Power BI hands the bound table to the embedded map page inside the browser, and the colouring, filtering and counting all happen there.
| Data |
Where it goes |
| Property address and unit identifiers |
Sent to the Beans API to look up the map of that property — the same lookup any Beans map makes. |
| Your data columns (rent, status, scores, measures…) |
Stay in the browser. They are never sent to Beans. |
| View preferences (colour column, filter picks, tab) |
Kept in the browser's session storage so a report page keeps its state. Cleared when the browser session ends. |
The visual runs the map in a sandboxed frame with no access to the rest of your report, and it holds no credentials of yours — map access is authorised by your Beans account. Nothing is written back to your dataset.
For the underlying map platform, its providers and its configuration options, see the
MapsWidget API v1.
