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
gateCode No String
floor No String
parking No String
additionalPoints No Double;Double;String|...†
userLocation No Double,Double
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|...†
userLocation No Double,Double
platform No One of APPLE or GOOGLE
‡Pipe separated list of Semicolon separated list of address, unit, gateCode, floor, and parking
†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
  &gateCode=9111
  &floor=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
  &gateCode=9111
  &floor=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
  &gateCode=9111
  &floor=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
  &gateCode=9111
  &floor=Floor+3
  &additionalPoints=33.63427078772915,-111.86407107998963,CARWASH
  &userLocation=37.450469700667234,-122.16778683875827
  &platform=APPLE
  &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 api key:secret...",
    "2255 Showers Dr, Mountain View, CA",
    "352",
    "beans-maps-1",
    null,
    null,
    "...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 api key:secret...",
    "2255 Showers Dr, Mountain View, CA",
    "352",
    "beans-maps-1",
    {
      gateCode: "#9111",
      floor: "Floor 3",
      parking: "Street",
      poi: [
        {
          location: {
            lat: 33.63427078772915,
            lng: -111.86407107998963
          },
          name: "CARWASH"
        }
      ]
    },
    {
      userLocation: {
        lat: 37.450469700667234,
        lng: -122.16778683875827
      },
      platform: "APPLE"
    },
    "...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. Beans api “key:secret”
  2. Address of the property
  3. Unit address. Leave empty if no unit number is required.
  4. ID of the div that the widget should render within
  5. Options. Every field in Options is optional, and provides mechanisms to override different parts of the display. You may pass
    1. Gate code
    2. Floor
    3. Type of parking
    4. 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
  7. 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 api key:secret...",
      "2255 Showers Dr, Mountain View, CA",
      "352",
      "beans-maps-1"
    );
  }
</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 api key:secret...",
      "2255 Showers Dr, Mountain View, CA",
      "352",
      "beans-maps-1",
      {
        gateCode: "#9111",
        floor: "Floor 3",
        parking: "Street",
        poi: [
          {
            location: {
              lat: 33.63427078772915,
              lng: -111.86407107998963
            },
            name: "CARWASH"
          }
        ]
      },
      {
        userLocation: {
          lat: 37.450469700667234,
          lng: -122.16778683875827
        },
        platform: "APPLE"
      }
    );
  }
</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. Beans api “key:secret”
  2. Address of the property
  3. Unit address. Leave empty if no unit number is required.
  4. ID of the div that the widget should render within
  5. Options. Every field in Options is optional, and provides mechanisms to override different parts of the display. You may pass
    1. Gate code
    2. Floor
    3. Type of parking
    4. 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