MapsWidget API v1

Demo Links

Google
https://www.beans.ai/mapswidget/example-google.html
https://www.beans.ai/mapswidget/example-google-with-multiple.html
https://www.beans.ai/mapswidget/example-google-inline.html
https://www.beans.ai/mapswidget/example-google-with-markers.html

Mapbox
https://www.beans.ai/mapswidget/example-mapbox.html
https://www.beans.ai/mapswidget/example-mapbox-with-multiple.html
https://www.beans.ai/mapswidget/example-mapbox-inline.html
https://www.beans.ai/mapswidget/example-mapbox-with-markers.html

ESRI
https://www.beans.ai/mapswidget/example-esri.html
https://www.beans.ai/mapswidget/example-esri-with-multiple.html
https://www.beans.ai/mapswidget/example-esri-inline.html
https://www.beans.ai/mapswidget/example-esri-with-markers.html

Account Setup

Please register an enterprise account on https://www.beans.ai/enterprise-console. When creating an account, you may use the invite code sent to you in a separate email.

Once you have created an account, a Beans API key and secret is automatically generated for you. Please keep these credentials confidentially and you will need to use them in the integration specification below.

Integration Overview

The Beans.ai Web Widget works seamlessly across Mapbox, Google Maps, and ESRI JS APIs.

There are two primary ways to integrate the Beans.ai Web Widget.

  1. Library
    In the library implementation, you will code and host the web pages necessary to render the widget. This is ideal for an integration where the widget lies within your website and is embedded in an existing page. The widget allows far more customization than the Beans.ai hosted iFrame/ Web View integration.
  2. Hosted by Beans.ai
    In the Beans.ai hosted implementation, you will simply link to the widget hosted on the Beans.ai website and embed it either within your website in iframe, or as an external link from your website, or within your mobile app as a Web View using URL query parameters to specify the data you want to display.

Configuration

Mapbox Integration
Headers
        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.3.css"
  rel="stylesheet"
/>
<link
  href="https://api.tiles.mapbox.com/mapbox-gl-js/v2.9.1/mapbox-gl.css"
  rel="stylesheet"
/>
        
End of body
        
<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.3.js"
></script>
        
Container
        
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
        
👉 Please ensure that the container div has a predefined height and width. If the size is calculated on the fly, that may lead to incorrect rendering.

Initializing
The following is an example of the code that must be added to the body right after the two js files above:

Basic Rendering
        
<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>
        
👉 Please ensure that you specify the Beans api key secret.

Customizations
        
<script type="text/javascript">
  var be = new BeansMap();
  be.render(
    "beans-maps-1",
    "...beans api key:secret...",
    [
      {
        address: "1200 Dale Ave, Mountain View, CA",
        unit: "43",
        options: {
          links: {
            // [Optional] Set display to true to show the distance bar at the top. Default false.
            display: true
          },
          tiles: {
            // [Optional] Set display to false to hide the address and tiles card. Default true.
            display: true,
            keybox: {
              // [Optional] Set the text to show on the tiles.
              text: "#9112",

              // [Optional] Set the icon for the tile. See
              // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
              // for size and format.
              iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
            },
            entrance: {
              text: "#9111"
            },
            elevation: {
              text: "Floor 3"
            },
            parking: {
              text: "Street"
            }
          },
          markers: {
            // [Optional] Set display to false to hide all the markers. Default true.
            display: true,
            keybox: {
              // [Optional] Set display to true to show the marker if all the markers are hidden
              // [Optional] Set display to false to hide the marker if all the markers are visible
              display: true,

              // [Optional] Set the text to show on the markers.
              text: "#9112"
            },
            entrance: {
              text: "#9111",

              // [Optional] Set the icon for the marker. See
              // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
              // for size and format.
              iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
            },
            elevation: {
              text: "Floor 3"
            },
            parking: {
              text: "Street"
            }
          },
          poi: [
            {
              // [Required] Set the POI location.
              location: {
                lat: 33.63427078772915,
                lng: -111.86407107998963
              },

              // [Required] Set the POI type.
              name: "CARWASH",

              // [Optional] Set the icon for the POI. See
              // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
              // for size and format.
              iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
            },
            {
              // [Optional] Set display to false to hide specific POIs that are a part of the Beans data set.
              display: false,

              // [Required] Set the POI type.
              name: "TRASH"
            },
            {
              display: false,
              name: "ALL"
            }
          ]
        }
      },
      // Callback Options
      {}
    ],
    {
      // [Optional] Set the location of the user to a fixed position for the navigation to work.
      userLocation: {
        lat: 37.450469700667234,
        lng: -122.16778683875827
      },
      // [Optional] Alteratenely, set the user location to pick the current live location the user.
      // userLocation: "LIVE",

      // [Optional] Set the default maps app to open on clicking the navigate button.
      platform: "APPLE",

      // [Optional] Hide the navigate button
      hideNavigateButton: true,

      // [Optional] Hide the "my location" button.
      hideMyLocationButton: true
    },
    {
      // [Optional] Set the default view to satellite.
      initialMap: "SATELLITE",

      // [Optional] Set a customized mapbox style.
      mapStyle: "mapbox://styles/mapbox/streets-v11",

      // [Optional] Hides the floor selector.
      hideFloorSelector: true,

      // [Optional] Hides the toggle satellite view button.
      hideSatelliteButton: true,

      // [Optional] Show unit outline.
      showUnitShape: true,

      // [Optional] Show building outline.
      showBuildingShape: true,

      // [Optional] Show directions in the card.
      showDirections: true,

      // [Optional] Show navigation path.
      showPath: true,

      // [Optional] Set the order of the path.
      path: [
        "PARKING",
        "ENTRANCE",
        "ELEVATOR",
        "UNIT"
      ]
    }
  );
</script>
        
👉 Please ensure that you specify the Beans api key secret.

BeansMap.prototype.render takes the following parameters, in order:
  1. ID of the div that the widget should render within
  2. Beans api “key:secret”
  3. Array of Display objects, where each Display object consists of:
    1. Street address.
    2. Unit address. Leave empty if no unit number is required.
    3. Options. Every field in Options is optional, and provides mechanisms to override different parts of the display. You may pass
      1. Tiles
      2. Markers
      3. Additional points of interest, which must have the name from the following strings: SWIMMINGPOOL, CARWASH, TENNIS, LAUNDRY, OFFICE, CLUBHOUSE, BBQ, MAILROOM, PACKAGELOCKER, CYCLESTORAGE, GYM
  4. Navigation options. Every field in Navigation Options is optional. You may pass
    1. UserLocation
    2. Platform
    3. hideNavigateButton
  5. Display options. Every field in Display Options is optional. You may pass
    1. InitialMap
    2. ShowDirections
    3. ShowUnitShape
    4. ShowBuildingShape
    5. ShowPath
    6. Path
Google Maps Integration
Headers
        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.3.css"
  rel="stylesheet"
/>
        
End of body
        
<script type="text/javascript"
  src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.3.js"
></script>
<script async defer
  src="https://maps.googleapis.com/maps/api/js?key=...&callback=initMap"
></script>
        
👉 Please ensure that you specify as your Google Maps API key when adding the Google Maps library to your code. Container
        
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
        
Initializing
The following is an example of the code that must be added to the body right after the two js files above:

Basic Rendering
        
<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>
        
👉 Please ensure that you specify the Beans api key secret in the arguments to the render method. 👉 Please ensure that your calls to the Beans widget are wrapped inside Google Maps’ callback function.

Customizations
        
<script type="text/javascript">
  function initMap() {
    var be = new BeansMap();
    be.render(
      "beans-maps-1",
      "...beans api key:secret...",
      [
        {
          address: "1200 Dale Ave, Mountain View, CA",
          unit: "43",
          options: {
            links: {
              // [Optional] Set display to true to show the distance bar at the top. Default false.
              display: true
            },
            tiles: {
              // [Optional] Set display to false to hide the address and tiles card. Default true.
              display: true,
              keybox: {
                // [Optional] Set the text to show on the tiles.
                text: "#9112",

                // [Optional] Set the icon for the tile. See
                // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
                // for size and format.
                iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
              },
              entrance: {
                text: "#9111"
              },
              elevation: {
                text: "Floor 3"
              },
              parking: {
                text: "Street"
              }
            },
            markers: {
              // [Optional] Set display to false to hide all the markers. Default true.
              display: true,
              keybox: {
                // [Optional] Set display to true to show the marker if all the markers are hidden
                // [Optional] Set display to false to hide the marker if all the markers are visible
                display: true,

                // [Optional] Set the text to show on the markers.
                text: "#9112"
              },
              entrance: {
                text: "#9111",

                // [Optional] Set the icon for the marker. See
                // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
                // for size and format.
                iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
              },
              elevation: {
                text: "Floor 3"
              },
              parking: {
                text: "Street"
              }
            },
            poi: [
              {
                // [Required] Set the POI location.
                location: {
                  lat: 33.63427078772915,
                  lng: -111.86407107998963
                },

                // [Required] Set the POI type.
                name: "CARWASH",

                // [Optional] Set the icon for the POI. See
                // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
                // for size and format.
                iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
              },
              {
                // [Optional] Set display to false to hide specific POIs that are a part of the Beans data set.
                display: false,

                // [Required] Set the POI type.
                name: "TRASH"
              },
              {
                display: false,
                name: "ALL"
              }
            ]
          }
        }
      ],
      {
        // [Optional] Set the location of the user to a fixed position for the navigation to work.
        userLocation: "LIVE",

        // [Optional] Set the default maps app to open on clicking the navigate button
        platform: "APPLE",

        // [Optional] Hide the navigate button
        hideNavigateButton: true,

        // [Optional] Hide the "my location" button.
        hideMyLocationButton: true
      },
      {
        // [Optional] Set the default view to satellite.
        initialMap: "SATELLITE",

        // [Optional] Set a customized Google style.
        mapStyle: [
          {
            "elementType": "labels",
            "stylers": [
              {
                "visibility": "off"
              }
            ]
          },
          {
            "featureType": "administrative.land_parcel",
            "stylers": [
              {
                "visibility": "off"
              }
            ]
          },
          {
            "featureType": "administrative.neighborhood",
            "stylers": [
              {
                "visibility": "off"
              }
            ]
          }
        ],

        // [Optional] Hides the floor selector.
        hideFloorSelector: true,

        // [Optional] Hides the toggle satellite view button.
        hideSatelliteButton: true,

        // [Optional] Show unit outline.
        showUnitShape: true,

        // [Optional] Show building outline.
        showBuildingShape: true,

        // [Optional] Show directions in the card.
        showDirections: true,

        // [Optional] Show navigation path.
        showPath: true,

        // [Optional] Set the order of the path.
        path: [
          "PARKING",
          "ENTRANCE",
          "ELEVATOR",
          "UNIT"
        ]
      },
      // Callback Options
      {}
    );
  }
</script>
        
👉Please ensure that you specify the Beans api key secret in the arguments to the render method. 👉Please ensure that your calls to the Beans widget are wrapped inside Google Maps’ callback function.

BeansMap.prototype.render takes the following parameters, in order:
  1. ID of the div that the widget should render within
  2. Beans api “key:secret”
  3. Array of Display objects, where each Display object consists of:
    1. Street address.
    2. Unit address. Leave empty if no unit number is required.
    3. Options. Every field in Options is optional, and provides mechanisms to override different parts of the display. You may pass
      1. Tiles
      2. Markers
      3. Additional points of interest, which must have the name from the following strings: SWIMMINGPOOL, CARWASH, TENNIS, LAUNDRY, OFFICE, CLUBHOUSE, BBQ, MAILROOM, PACKAGELOCKER, CYCLESTORAGE, GYM
  4. Navigation options. Every field in Navigation Options is optional. You may pass
    1. UserLocation
    2. Platform
    3. hideNavigateButton
  5. Display options. Every field in Display Options is optional. You may pass
    1. InitialMap
    2. ShowDirections
    3. ShowUnitShape
    4. ShowBuildingShape
    5. ShowPath
    6. Path
ESRI Integration
Headers
      
<link
href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.3.css"
rel="stylesheet"
/>
<link
href="https://js.arcgis.com/4.23/esri/themes/light/main.css"
rel="stylesheet"
/>
      
End of body
      
<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.3.js"
></script>
      
Container
      
<div id="beans-maps-1" style="width: 50vw; height: 60vh;"></div>
      
👉 Please ensure that the container div has a predefined height and width. If the size is calculated on the fly, that may lead to incorrect rendering.

Initializing
The following is an example of the code that must be added to the body right after the two js files above:

Basic Rendering
      
<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>
      
👉 Please ensure that you specify the Beans api key secret.

Customizations
      
<script type="text/javascript">
var be = new BeansMap();
be.render(
  "beans-maps-1",
  "...beans api key:secret...",
  [
    {
      address: "1200 Dale Ave, Mountain View, CA",
      unit: "43",
      options: {
        links: {
          // [Optional] Set display to true to show the distance bar at the top. Default false.
          display: true
        },
        tiles: {
          // [Optional] Set display to false to hide the address and tiles card. Default true.
          display: true,
          keybox: {
            // [Optional] Set the text to show on the tiles.
            text: "#9112",

            // [Optional] Set the icon for the tile. See
            // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
            // for size and format.
            iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
          },
          entrance: {
            text: "#9111"
          },
          elevation: {
            text: "Floor 3"
          },
          parking: {
            text: "Street"
          }
        },
        markers: {
          // [Optional] Set display to false to hide all the markers. Default true.
          display: true,
          keybox: {
            // [Optional] Set display to true to show the marker if all the markers are hidden
            // [Optional] Set display to false to hide the marker if all the markers are visible
            display: true,

            // [Optional] Set the text to show on the markers.
            text: "#9112"
          },
          entrance: {
            text: "#9111",

            // [Optional] Set the icon for the marker. See
            // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
            // for size and format.
            iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
          },
          elevation: {
            text: "Floor 3"
          },
          parking: {
            text: "Street"
          }
        },
        poi: [
          {
            // [Required] Set the POI location.
            location: {
              lat: 33.63427078772915,
              lng: -111.86407107998963
            },

            // [Required] Set the POI type.
            name: "CARWASH",

            // [Optional] Set the icon for the POI. See
            // https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/parking_0.png
            // for size and format.
            iconUrl: "https://storage.googleapis.com/beans-mobile-resources/marker-note-icons/..."
          },
          {
            // [Optional] Set display to false to hide specific POIs that are a part of the Beans data set.
            display: false,

            // [Required] Set the POI type.
            name: "TRASH"
          },
          {
            display: false,
            name: "ALL"
          }
        ]
      }
    },
    // Callback Options
    {}
  ],
  {
    // [Optional] Set the location of the user to a fixed position for the navigation to work.
    userLocation: {
      lat: 37.450469700667234,
      lng: -122.16778683875827
    },
    // [Optional] Alteratenely, set the user location to pick the current live location the user.
    // userLocation: "LIVE",

    // [Optional] Set the default maps app to open on clicking the navigate button.
    platform: "APPLE",

    // [Optional] Hide the navigate button
    hideNavigateButton: true,

    // [Optional] Hide the "my location" button.
    hideMyLocationButton: true
  },
  {
    // [Optional] Set the default view to satellite.
    initialMap: "SATELLITE",

    // [Optional] Set a customized mapbox style.
    mapStyle: "mapbox://styles/mapbox/streets-v11",

    // [Optional] Hides the floor selector.
    hideFloorSelector: true,

    // [Optional] Hides the toggle satellite view button.
    hideSatelliteButton: true,

    // [Optional] Show unit outline.
    showUnitShape: true,

    // [Optional] Show building outline.
    showBuildingShape: true,

    // [Optional] Show directions in the card.
    showDirections: true,

    // [Optional] Show navigation path.
    showPath: true,

    // [Optional] Set the order of the path.
    path: [
      "PARKING",
      "ENTRANCE",
      "ELEVATOR",
      "UNIT"
    ]
  }
);
</script>
      
👉 Please ensure that you specify the Beans api key secret.

BeansMap.prototype.render takes the following parameters, in order:
  1. ID of the div that the widget should render within
  2. Beans api “key:secret”
  3. Array of Display objects, where each Display object consists of:
    1. Street address.
    2. Unit address. Leave empty if no unit number is required.
    3. Options. Every field in Options is optional, and provides mechanisms to override different parts of the display. You may pass
      1. Tiles
      2. Markers
      3. Additional points of interest, which must have the name from the following strings: SWIMMINGPOOL, CARWASH, TENNIS, LAUNDRY, OFFICE, CLUBHOUSE, BBQ, MAILROOM, PACKAGELOCKER, CYCLESTORAGE, GYM
  4. Navigation options. Every field in Navigation Options is optional. You may pass
    1. UserLocation
    2. Platform
    3. hideNavigateButton
  5. Display options. Every field in Display Options is optional. You may pass
    1. InitialMap
    2. ShowDirections
    3. ShowUnitShape
    4. ShowBuildingShape
    5. ShowPath
    6. Path
Base Url
Mapbox Integration
https://www.beans.ai/mapswidget/mapbox.html
https://www.beans.ai/mapswidget/mapbox-with-nav.html
Google Integration
https://www.beans.ai/mapswidget/google.html
https://www.beans.ai/mapswidget/google-with-nav.html
Query parameters
Single Result
Parameter Name Required Type
apiKeySecret yes String:String
address Yes String
unit No String
entrance.text No String
elevation.text No String
parking.text No String
card No Boolean
links No Boolean
markers No String,String,...
additionalPoints No Double;Double;String|...†
userLocation No LIVE|Double,Double
initialMap No One of STREET or SATTELITE
platform No One of APPLE or GOOGLE
showDirections No Boolean
showUnitShape No Boolean
showBuildingShape No Boolean
showPath No Boolean
path No String,String...
†Pipe separated list of Semicolon separated triple of lat, lng, and PointType where PointType is one of SWIMMINGPOOL, CARWASH, TENNIS, LAUNDRY, OFFICE, CLUBHOUSE, BBQ, MAILROOM, PACKAGELOCKER, CYCLESTORAGE, GYM

Multiple Results
Parameter Name Required Type
apiKeySecret yes String:String
addressPoints Yes String;String;String;String;String|...‡
additionalPoints No Double;Double;String|...†
card No Boolean
links No Boolean
markers No String,String,...
userLocation No LIVE|Double,Double
initialMap No One of STREET or SATTELITE
platform No One of APPLE or GOOGLE
showDirections No Boolean
showUnitShape No Boolean
showBuildingShape No Boolean
showPath No Boolean
path No String,String...
‡Pipe separated list of Semicolon separated list of address, unit, entrance.text, elevation.text, and parking.text
†Pipe separated list of Semicolon separated triple of lat, lng, and PointType where PointType is one of SWIMMINGPOOL, CARWASH, TENNIS, LAUNDRY, OFFICE, CLUBHOUSE, BBQ, MAILROOM, PACKAGELOCKER, CYCLESTORAGE, GYM
Example
Mapbox
      
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...
      
Mapbox with Nav
      
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
      
Google
      
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...
      
Google with Nav
      
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...