MapsWidget API v1

Account Setup

Integration Overview

1. Library.
   You code and host the web page that renders the widget. This is the right choice when the widget lives inside your own site and is embedded in an existing page, and it allows far more customization than the hosted iframe.
2. Hosted by Beans.ai.
   You link to the widget hosted on beans.ai — embedded in your site as an iframe, opened as an external link, or shown inside your mobile app as a WebView — using URL query parameters to specify what to display.

Companion Products

Setup

      
<link
href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.4.css"
rel="stylesheet"
/>
<link
href="https://js.arcgis.com/4.23/esri/themes/light/main.css"
rel="stylesheet"
/>
      

      
<script type="text/javascript"
src="https://js.arcgis.com/4.23/"
></script>
<script type="text/javascript"
src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.4.js"
></script>
      

      
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
      

      
<script type="text/javascript">
var be = new BeansMap();
be.render(
  "beans-maps-1",
  "...beans api key:secret...",
  [
    {
      address: "3815 N 16th St, Phoenix, AZ",
      unit: "251"
    }
  ],
  // Nav Options,
  {},
  // Display Options
  {},
  // Callback Options
  {}
);
</script>
      

      
<link
href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.4.css"
rel="stylesheet"
/>
      

      
<script type="text/javascript"
src="https://www.beans.ai/mapswidget/js/banvas.js"
></script>
<script type="text/javascript"
src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.4.js"
></script>
      

      
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
      

      
<script type="text/javascript">
var be = new BeansMap();
be.render(
  "beans-maps-1",
  "...beans api key:secret...",
  [
    {
      address: "3815 N 16th St, Phoenix, AZ",
      unit: "251"
    }
  ],
  // Nav Options,
  {},
  // Display Options
  {},
  // Callback Options
  {}
);
</script>
      

        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.4.css"
  rel="stylesheet"
/>
        

        
<script type="text/javascript"
  src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.4.js"
></script>
<script async defer
  src="https://maps.googleapis.com/maps/api/js?key=...&callback=initMap"
></script>
        

        
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
        

        
<script type="text/javascript">
  function initMap() {
    var be = new BeansMap();
    be.render(
      "beans-maps-1",
      "...beans api key:secret...",
      [
        {
          address: "3815 N 16th St, Phoenix, AZ",
          unit: "251"
        }
      ],
      // Nav Options,
      {},
      // Display Options
      {},
      // Callback Options
      {}
    );
  }
</script>
        

        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.4.css"
  rel="stylesheet"
/>
<link
  href="https://api.tiles.mapbox.com/mapbox-gl-js/v2.9.1/mapbox-gl.css"
  rel="stylesheet"
/>
        

        
<script type="text/javascript"
  src="https://api.tiles.mapbox.com/mapbox-gl-js/v2.9.1/mapbox-gl.js"
></script>
<script type="text/javascript"
  src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.4.js"
></script>
        

        
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
        

        
<script type="text/javascript">
  var be = new BeansMap();
  be.render(
    "beans-maps-1",
    "...beans api key:secret...",
    [
      {
        address: "3815 N 16th St, Phoenix, AZ",
        unit: "251"
      }
    ],
    // Nav Options,
    {},
    // Display Options
    {},
    // Callback Options
    {}
  );
</script>
        

      
https://www.beans.ai/mapswidget/mapbox.html
?addressOptions=Wwp7CiAgICAgICAgICBhZGRyZXNzOiAiMzEwMCBXIExha2UgU3QsIE1pbm5lYXBvbGlzLCBNTiIsCiAgICAgICAgICB1bml0OiAiMzM0IgogICAgICAgIH0KXQ==
&navOptions=ewogICAgICAgIHBsYXRmb3JtOiAiQVBQTEUiLAogICAgICAgIHVzZXJMb2NhdGlvbjogewogICAgICAgICAgbGF0OiAzNC4xNzc5LAogICAgICAgICAgbG5nOiAtMTEyLjUzMzMKICAgICAgICB9CiAgICAgIH0=
&displayOptions=ewogICAgICAgIGluaXRpYWxNYXA6ICJTVFJFRVQiLAogICAgICAgIHNob3dVbml0U2hhcGU6IHRydWUsCiAgICAgICAgc2hvd1BhdGg6IHRydWUsCiAgICAgICAgcGF0aDogWwogICAgICAgICAgJ0VOVFJBTkNFJywKICAgICAgICAgICdFTEVWQVRPUicsCiAgICAgICAgICAnVU5JVCcKICAgICAgICBdLAogICAgICAgIHNob3dEaXJlY3Rpb25zOiB0cnVlLAogICAgICAgIGluaXRpYWxQb3NpdGlvbjogewogICAgICAgICAgYWRkcmVzczogIjMxMDAgVyBMYWtlIFN0LCBNaW5uZWFwb2xpcywgTU4iCiAgICAgICAgfQogICAgICB9
&apiKeySecret=...beans api key:secret...
      

      
https://www.beans.ai/mapswidget/mapbox.html
?address=1200+Dale+Ave,+Mountain+View,+CA+94043
&unit=43
&entrance.text=9111
&elevation.text=Floor+3
&additionalPoints=33.63427078772915,-111.86407107998963,CARWASH
&apiKeySecret=...beans api key:secret...
      

      
https://www.beans.ai/mapswidget/mapbox-with-nav.html
?address=1200+Dale+Ave,+Mountain+View,+CA+94043
&unit=43
&entrance.text=9111
&elevation.text=Floor+3
&additionalPoints=33.63427078772915,-111.86407107998963,CARWASH
&apiKeySecret=...beans api key:secret...
&userLocation=37.450469700667234,-122.16778683875827
&platform=APPLE
      

      
https://www.beans.ai/mapswidget/google.html
?address=1200+Dale+Ave,+Mountain+View,+CA+94043
&unit=43
&entrance.text=9111
&elevation.text=Floor+3
&additionalPoints=33.63427078772915,-111.86407107998963,CARWASH
&apiKeySecret=...beans api key:secret...
      

      
https://www.beans.ai/mapswidget/google-with-nav.html
?address=1200+Dale+Ave,+Mountain+View,+CA+94043
&unit=43
&entrance.text=9111
&elevation.text=Floor+3
&additionalPoints=33.63427078772915,-111.86407107998963,CARWASH
&userLocation=37.450469700667234,-122.16778683875827
&platform=GOOGLE
&apiKeySecret=...beans api key:secret...
      

Demo Links

How To Read This

render() Signature

var be = new BeansMap();
be.render(
  containerDivId,     // String — id of the div to render into (must have a fixed width/height)
  apiKeySecret,       // String — "key:secret" from the Beans enterprise console
  addresses,          // Array  — one entry per unit / address to display
  navOptions,         // Object — user location + navigate button
  displayOptions,     // Object — everything about how the map looks and behaves
  callbackOptions,    // Object — event hooks back into your page
  clientOptions       // Object — add-on selection (parking, storage)
);

Address Object

[
  {
    address: "1200 Dale Ave, Mountain View, CA",
    unit: "43",
    options: { /* ... */ }
  },
  {
    address: "1200 Dale Ave, Mountain View, CA",
    unit: "44",
    options: { /* ... */ }
  }
]

Per-Unit Options

onClickData

onClickData: {
  name: "L101",
  floorplan: "A1",
  bed: 1,
  bath: 1,
  sqft: 1024,
  floor: 1,
  rent: 3200,
  availability: "Available Now",
  floorplanImg: "https://.../plan-a1.jpg",
  images: [
    {url: "https://.../photo-1.jpg"},
    {url: "https://.../photo-2.jpg"}
  ],
  tourLink: "https://.../3d-tour",
  scheduleLink: "https://.../schedule",
  link: "https://.../apply?unit=L101",
  ctaLabel: "Apply Now"
}

onPreviewData

onPreviewData: [
  { icon: "bed",          value: "3 Bed / 2 Bath / 1500 sq. ft." },
  { icon: "price",        value: "$3,200 / mo" },
  { icon: "availability", value: "Available Now" }
]

markers

markers: {
  // Hide everything...
  display: false,

  // ...except the entrance, relabeled and re-iconed.
  entrance: {
    display: true,
    text: "#9111",
    iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/...",
    zIndex: 1200
  }
}

poi

poi: [
  {
    location: { lat: 33.63427, lng: -111.86407 },
    name: "CARWASH",
    iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
  },
  { name: "TRASH", display: false }
]

navOptions

displayOptions — Base Map & Camera

displayOptions — Buttons & Chrome

displayOptions — Cards

displayOptions — Unit List & Filters

displayOptions — Shapes

displayOptions — Numbers & Markers

displayOptions — Floors

displayOptions — Wayfinding Path

displayOptions — Immersive Layers

displayOptions — Amenities & Nearby

displayOptions — Map Reel®

displayOptions — Add-Ons

displayOptions — Rendering & Lifecycle

Shape Objects

unitShape:              { fillColor: '#ffffff', fillOpacity: 0.7, strokeWeight: 0.25,
                          strokeOpacity: 1, strokeColor: '#000000',
                          fillColorOnShadowMode: '#cdeefd', fillOpacityOnShadowMode: 1.0 }
selectedUnitShape:      { fillColor: '#cc088e', fillOpacity: 1.0, strokeWeight: 1.0,
                          strokeOpacity: 1.0, strokeColor: '#ffffff' }
selectableUnitShape:    { fillColor: '#24453E', fillOpacity: 1.0, strokeWeight: 1.0,
                          strokeOpacity: 1.0, strokeColor: '#ffffff' }
neighborShape:          { fillColor: '#ffffff', fillOpacity: 0.2, strokeWeight: 1.0,
                          strokeOpacity: 1.0, strokeColor: '#000000' }
parkingShape:           { fillColor: '#c5c5c5', fillOpacity: 1.0, strokeWeight: 1,
                          strokeOpacity: 1.0, strokeColor: '#ffffff' }
selectableParkingShape: { fillColor: '#0cb1a1', fillOpacity: 1.0, strokeWeight: 1.0,
                          strokeOpacity: 1.0, strokeColor: '#ffffff' }

// Mode overlays — merged on top of the resolved unit shape while active
shadowModeUnitShape:    { fillOpacity: 1.0 }
satelliteModeUnitShape: { fillOpacity: 1.0 }
immersiveModeUnitShape: { fillOpacity: 0.9 }

numbersConfig

showNumbers: true,
numbersConfig: {
  backgroundColor: '#FFFFFF',
  border: '1px solid black',
  size: '10px',
  yOffset: 5,
  minZoom: 19,
  convert: (s) => s ? s.replaceAll('-', '') : '',
  getMinZoom: (s) => s ? 18 : 0
}

filters

filters: {
  bed: {
    name: "Bedrooms",
    values: [
      {type: "all",   name: "Any"},
      {type: "range", value1: "1", value2: "2", name: "1BR"},
      {type: "min",   value1: "3", name: "3BR+"}
    ]
  },
  status: {
    name: "Status",
    values: [
      {type: "all",    name: "Any"},
      {type: "string", value: "Open for Sale", name: "Open for Sale"}
    ]
  }
}

poiOptions

poiOptions: [
  { type: "FOOD",     label: "Restaurants", value: "restaurant",
    icon: "https://www.beans.ai/m/assets/food_0.png" },
  { type: "HOSPITAL", label: "Hospitals",   value: "hospital",
    icon: "https://www.beans.ai/m/assets/hospital_0.png" },
  { type: "SCHOOL",   label: "Schools",     value: "school",
    icon: "https://www.beans.ai/m/assets/school_0.png" },
  { type: "COLLEGE",  label: "Colleges",    value: "university",
    icon: "https://www.beans.ai/m/assets/school_0.png" }
]

communityAmenities

1. A "Community amenities" chip row inside the unit card, plus a "See what's nearby" CTA.
2. Amenity chips in the bottom facilities dock that pan the camera to the amenity and open its card.
3. A rich hover card on amenity map pins, with photos and a "Click for photos & details" link.

communityAmenities: [
  {
    key: "SWIMMINGPOOL",
    name: "Swimming Pool",
    aliases: ["SWIMMINGPOOL", "POOL"],
    iconUrl: "https://www.beans.ai/m/assets/swimmingpool_0.png",
    color: "#98E3DF",
    description: "Resort-style pool with sundeck lounge seating.",
    photos: ["https://.../pool-1.jpg", "https://.../pool-2.jpg"]
  },
  {
    key: "GYM",
    name: "Fitness Center",
    aliases: ["GYM", "FITNESS"],
    iconUrl: "https://www.beans.ai/m/assets/gym_0.png",
    description: "24-hour fitness center with cardio and strength equipment.",
    photos: ["https://.../gym-1.jpg"]
  }
]

pricing

<script src="https://www.beans.ai/mapswidget/propertymanager/plugins/fees/fees-calculator.js"></script>
<link href="https://www.beans.ai/mapswidget/propertymanager/plugins/fees/fees-calculator.css" rel="stylesheet"/>

pricing: {
  petRent: {
    title: "Pet Rent",
    category: "Pets",
    options: ["No Pet", "1 Pet", "2 Pets"],
    cost:    [0, 50, 100]
  },
  garageRental: {
    title: "Garage Rental",
    category: "Parking",
    options: ["No", "Yes"],
    cost:    [0, 200]
  }
}

callbackOptions

{
  type: 'unit' | 'poi',
  unitData: { ix, aug }                // when type === 'unit'
          | { rawStrOrName, poi },     // when type === 'poi'
  location: { lat, lng },
  distance: 42.7                     // metres
}

// Callback Options
{
  onSelect: (data) => { console.log('selected', data); },
  onUnitClick: (ix, entry, marker, e) => {
    if (entry.unit === 'PENTHOUSE') {
      openMyOwnModal(entry);
      return false;   // suppress the built-in card
    }
  },
  onPOIClick: (name, poi, marker, e) => { console.log(name); },
  onFloorSelect: (floor, label) => {},
  onSatelliteClick: (type) => {},
  onMylocationClick: (isFound, pos) => {},
  onProximityChange: (dest, prev, meters) => {}
}

clientOptions — Add-Ons

// Category colors + legend, passed via displayOptions.
displayOptions.selectableParkingShape = {
  byNamePrefix: {
    "Garage Small": { text: "$155.00", fillColor: "#D08341", fillOpacity: 1 },
    "Premier":      { text: "$125.00", fillColor: "#C14634", fillOpacity: 1 },
    "Standard":     { text: "$105.00", fillColor: "#69A65B", fillOpacity: 1 }
  }
};

// One add-on, keyed by beansId (or the namespaced form described above).
elementConfig[beansId] = {
  id: 469582,
  type: "Premier",
  hoverLine: [
    { key: "Category",     value: "Premier" },
    { key: "Number",       value: "P - 65" },
    { key: "Monthly Rent", value: "$55.00" }
  ],
  line: [
    { key: "Category",     value: "Premier" },
    { key: "Number",       value: "P - 65" },
    { key: "Monthly Rent", value: "$55.00" }
  ],
  isEditable: false,
  isAvailable: true,
  isSelectable: true,
  obj: { /* returned to you in onSelect */ }
};

// Client Options — the seventh argument to render()
{
  aircom: {
    type: "parking",
    elementConfig: elementConfig,
    onSelect:   (obj, cfg) => { /* persist the assignment */ },
    onUnselect: (obj, cfg) => { /* release the old spot */ },
    onCancel:   ()         => { /* tenant backed out */ }
  }
}

Worked Example

<script type="text/javascript">
var be = new BeansMap();
be.render(
  "beans-maps-1",
  "...beans api key:secret...",

  // ── Addresses ─────────────────────────────────────────────────
  [
    {
      address: "1200 Dale Ave, Mountain View, CA",
      unit: "43",
      options: {
        markers: { display: false },
        onPreviewData: [
          { icon: "bed",          value: "3 Bed / 2 Bath / 1500 sq. ft." },
          { icon: "price",        value: "$3,200 / mo" },
          { icon: "availability", value: "Available Now" }
        ],
        onClickData: {
          name: "43", floorplan: "A1",
          bed: 3, bath: 2, sqft: 1500, floor: 2,
          rent: 3200, availability: "Available Now",
          floorplanImg: "https://.../plan-a1.jpg",
          images: [{url: "https://.../photo-1.jpg"}],
          tourLink: "https://.../tour",
          scheduleLink: "https://.../schedule",
          link: "https://.../apply?unit=43"
        }
      }
    }
  ],

  // ── Nav Options ───────────────────────────────────────────────
  {
    userLocation: "LIVE",
    platform: "APPLE",
    hideNavigateButton: true
  },

  // ── Display Options ───────────────────────────────────────────
  {
    initialMap: "STREET",
    camera: { tilt: 64.8, heading: 269,
              position: { x: -122.09, y: 37.40, z: 122.45 } },

    showUnitShape: true,
    showUnitList: true,
    modernBeansCard: true,
    modernButtons: true,
    outsideButtons: true,
    modernFilters: true,

    showImmersive: true,
    showImmersiveOnLoad: true,
    showCompass: true,
    showPOIButton: true,
    showSeparateFacilitiesCard: true,

    selectableUnitShape: { fillColor: '#24453E', strokeWeight: 0.5 },
    selectedUnitShape:   { fillColor: '#cc078e', strokeWeight: 0.5 },

    communityAmenities: [
      { key: "SWIMMINGPOOL", name: "Swimming Pool",
        aliases: ["SWIMMINGPOOL", "POOL"],
        iconUrl: "https://www.beans.ai/m/assets/swimmingpool_0.png",
        description: "Resort-style pool with sundeck lounge seating.",
        photos: ["https://.../pool-1.jpg"] }
    ]
  },

  // ── Callback Options ──────────────────────────────────────────
  {
    onSelect: (data) => { console.log('unit selected', data); },
    onFloorSelect: (floor, label) => {},
    onPOIClick: (name, poi, marker, e) => {}
  }
);
</script>

Support Chat Widget

<script type="text/javascript" src="https://www.beans.ai/js/chat-widget.js"></script>

<div id="widget-container"></div>

<script>
  var customButtonClickHandler = () => {
    // Called when the button is clicked — trigger the display of the chat iframe here.
    alert('Please perform the necessary action');
  };

  const config = {
    // Your account id. Ask your account manager if you do not know it.
    accountBuid: '...',

    // The user talking to support. The Beans team will give you a deterministic assigneeCode format.
    assigneeCode: 'client100064237',

    // The div the button is created in.
    buttonRoot: '#widget-container',

    // Custom class name for the button.
    buttonClass: '',

    // Text written on the button.
    buttonText: '💬 Custom Chat',

    // Custom class name for the counter badge.
    badgeClass: '',

    // Custom click handler — you control when and how the iframe opens.
    onButtonClick: customButtonClickHandler,

    onInit: function(instance) {
      console.log('Widget initialized successfully');
    },

    onError: function(error) {
      console.log('Widget error: ' + error);
    }
  };

  BeansChatWidget.init(config)
</script>

https://chat.beans.ai/?assigneeCode=client100064237&disableLeftPanel=true#/channels/100064237

Indoor Path API