MapsWidget API v1

Demo Links

https://www.beans.ai/mapswidget/example-google.html
https://www.beans.ai/mapswidget/example-mapbox.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 and Google Maps JS APIs.

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

  1. 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 using URL query parameters to specify the data you want to display.
  2. Self Hosted: In the self hosted 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.

Hosted by Beans.ai

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
mapboxToken Required for Mapbox 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
†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
mapboxToken Required for Mapbox 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
‡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...
  &mapboxToken=...mapbox access token...
        
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
  &mapboxToken=...mapbox access token...
        
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...
        

Self Hosted

Mapbox Integration
Headers
        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.2.css"
  rel="stylesheet"
/>
<link
  href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.6.1/mapbox-gl.css"
  rel="stylesheet"
/>
        
End of body
        
<script type="text/javascript"
  src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.6.1/mapbox-gl.js"
></script>
<script type="text/javascript"
  src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.2.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:

(without options)
        
<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
    {},
    "...mapbox token..."
  );
</script>
        
👉 Please ensure that you specify the Beans api key secret as well as your Mapbox access token.

(with options)
        
<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"
            }
          ]
        }
      }
    ],
    {
      // [Optional] Set the location of the user to a fixed position for the navigation to work.
      userLocation: {
        lat: 37.450469700667234,
        lng: -122.16778683875827
      },

      // [Optional] Set the default maps app to open on clicking the navigate button
      platform: "APPLE"
    },
    {
      // [Optional] Set the default view to satellite.
      initialMap: "SATELLITE"
    },
    // [Required] Set your mapbox token here
    "...mapbox token..."
  );
</script>
        
👉 Please ensure that you specify the Beans api key secret as well as your Mapbox access token.

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
  5. Mapbox GL access token
Google Maps Integration
Headers
        
<link
  href="https://www.beans.ai/mapswidget/css/mapswidget-1.0.2.css"
  rel="stylesheet"
/>
        
End of body
        
<script type="text/javascript"
  src="https://www.beans.ai/mapswidget/js/mapswidget-1.0.2.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:

(without options)
        
<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
      {}
    );
  }
</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.

(with options)
        
<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] Set the default view to satellite.
        initialMap: "SATELLITE"
      }
    );
  }
</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. Address of the property
  4. Unit address. Leave empty if no unit number is required.
  5. 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
  6. Navigation options. Every field in Navigation Options is optional. You may pass
    1. UserLocation
    2. Platform