Enterprise API v2

Search API Reference

Request

Base Url
GET https://api.beans.ai/enterprise/v2/search/beans
Authentication
The Beans Search API uses a standard authorization header to authenticate client requests. You must sign in and create an enterprise account here to get your key before you access the API. If you use an unauthorized key or do not provide one, you will get a NOT_ALLOWED response.
Once you have your key and secret available, you are required to specify them in the Authorization header of all your requests, as below, where a2V5OnNlY3JldA== is the base64 encoding of the string "key:secret". For more information, see wiki:Basic access authentication

Authorization: Basic a2V5OnNlY3JldA==

You may also pass another optional header to track responses at your end. This is handy when your service makes asynchronous requests to the API and you want to tie the response back to your original request.

Tracking-Id: <client request tracking identifer>
Query Parameters
Parameter Required? Values
address Yes Full street address (line 1, city, state zip)
unit No Unit number of address (line 2)
origin No Latitude,Longitude pair of the end user's current location
mode No Either of DRIVER_DELIVERS or COSTUMER_OUTSIDE or EMS
Example Request
$ curl -X GET \
  'https://api2.beans.ai/enterprise/v2/search/beans?address=2255%20Showers%20Dr,%20Mountain%20View,%20CA&unit=352' \
  -H 'Authorization: Basic a2V5OnNlY3JldA=='

Response

Response Object
The response for a search request is a list of routes, with the first route as the primary route, and others following if any alternatives exist. It also contains a Beans generated query id for audit purposes, and the optional tracking id that may have been provided by the client in the request headers.

When there are no matches, the field routes would either be omitted or be an empty list.

There may be some extra fields in the objects below that are not documented. We advise that your response parsers ignore such fields.

Response Object Type Required? Description
routes Array No Route object
queryId String Yes Beans generated query id
trackingId String No Client provided optional tracking id
Route Object
Each route consists of a sequence of ordered fragments, one for each part of the route. It also consists of other the points of interest along the route, such as parking meters, society entrances, and other visual indicators that may be benefical to the end user.
Route Object Type Required? Description
fragments Array Yes Fragment Object
pointsOfInterest Array No Point Object
origin Location Object Yes Specifies the origin of the route. This is the first point to which an end user must navigate to before moving to locations provided in the fragments objects.
destination Location Object Yes Specifies the terminal point of the route. This is the location at which the delivey is most likely to take place. For the mode DRIVER_DELIVERS, for instance, this will often be the exact unit location. However, when we know from the building policy, for example, that the delivery must be to the doorman, the destination may be the location of the reception. For the mode CUSTOMER_OUTSIDE, the destination is often a location on the street where the driver can safely pull over without getting a traffic ticket. For the mode EMS, this will always be the exact unit location, if available. However, when exact unit location is not available, the destination will indicate the nearest known location to the unit.
Fragment Object
Each fragment consists of an origin and a destination, each of which is an important waypoint when navigating. The fragment also captures whether the path from the origin to destination is drivable or only accessible on foot.
Fragment Object Type Required? Description
origin Point Object Yes Specifies the starting waypoint of the fragment
destination Point Object Yes Specifies the terminal waypoint of the fragment
type String Yes One of DRIVING, WALKING, or UNKNOWN.
Point Object
A point object is a semantic waypoint that specifies a checkpoint for the end user. It primarily consists of three parts -- the location of the waypoint, its type, and occasionally a payload which provides more detailed information about the waypoint.
Point Object Type Required? Description
location LatLng Object Yes Specifies the coordinates of the waypoint.
type String Yes Specifies the semantic type of the waypoint. Although the API returns a vanilla string, the waypoints can be further grouped semantically. Our current set of waypoints is described below.
data Data Object Yes Consists of a payload that gives more descriptive data for the waypoint.
Point Object Types
Entrances Description
ENTRANCE The primary entrance of a building.
Elevators and Stairs Description
ELEVATOR An elevator inside the building.
STAIR A staircase inside the building.
Parkings Description
PARKING A parking spot close to the entrance.
Terminals Description
UNIT The destination unit for the queried address, if the delivery terminates at the unit.
LOBBY One of the lobbies of the building, and often the one with a doorman, security, or the leasing agent.
LOCKER One of the available food or storage lockers in the building.
STOP_POINT A point outside the building where the driver can pull over safely without getting a ticket. A stop point is only returned if the request mode is CUSTOMER_OUTSIDE.
Location Object
A location object captures both the coordinates of a given location as well as its legal address.
Location Object Type Required? Description
address String No Full street address (line 1, city, state zip).
unit String No Unit number of address (line 2).
type LatLng Object Yes Specifies the coordinates of the location.
LatLng Object
A latlng object captures the coordinates of a given location.
LatLng Object Type Required? Description
latitude double Yes Latitude of the location to maximum precision.
longitude double Yes Longitude of the location to maximum precision.
Data Object
Each route point has more details attached to in terms of a data object. It captures string descriptions, security codes, and other descriptors.
Data Object Type Required? Description
text String Yes Text description of the route point.
code String No The access code, if required and available for this way point.
floor Integer No The floor of the waypoint, if known and not zero.
unitData
entranceData
stopPointData
Variable JSON Object No Consists of a payload that gives more variable instructions which be different for different waypoints. Currently, we support payloads for parkings, entrances, and terminal waypoints.
Variable JSON Data Objects
A data object is the payload associated with a given point object.
Entrances Type Required? Description
entranceData.realm String No Specifies the physical space this entrance will lead to. One of BUILDING, COMMUNITY, GARAGE, ELEVATOR, STAIR, OFFICE, WAREHOUSE, LOADING_DOCK, PARKING, or UNKNOWN_REALM
entranceData.modalities Array No An array of strings that specifies the mode through which one is expected to go through the entrance; takes values from DRIVING, WALKING, BIKING, or FLYING
entranceData.instructions Array No EntranceInstruction Object
entranceData.entranceTimes Array No EntranceTime Object
entranceData.accessToUnit Boolean No Specifies if the personnel will be allowed to go to the unit. If set to true, there may be additional fragments on the route that take the personnel to the elevator and then the unit.
entranceData.notes String No Freeform notes specific to this entrance.
Parkings Type Required? Description
stopPointData.type String No Type of the parking. One of NO_PARKING, NO_STOP, PARKING_AVAILABLE, PARKING_CAR, PARKING_GARAGE, PARKING_METERED, PARKING_METERED_CAR, PARKING_METERED_MOTORCYCLE, PARKING_MOTORCYCLE, PARKING_PRIVATE, PARKING_PUBLIC, PARKING_TRUCK, RESERVED_PARKING, STOP_CAR, STOP_TRUCK, or UNKNOWN_STOP_POINT
Terminals Type Required? Description
unitData.uiData.buildingShape.point Array No Array of LatLng objects describing the polygon for building that contains the unit.
unitData.uiData.floor Integer No The floor number of the unit.
EntranceInstruction Object
Each entrance instruction consists of a type.
EntranceInstruction Object Type Required? Description
type String Yes The type of this instruction. One of BUZZER, SECURITY_CODE, WALK_IN, KNOCK_ON_DOOR, CALL_CUSTOMER_LET_IN, OPEN_PARKING, SCAN_GATE, or UNKNOWN_INSTRUCTION.
EntranceTime Object
Each entrance may consist of effective time windows. We pick the best one for you based on the request time.
EntranceTime Object Type Required? Description
dayOfWeek String No The day of week when this entrance time is applicable.
start String No Time of day in HH:mm format in the local timezone that specifies when this entrance opens. If missing, the entrance is accessible 24/7.
end String No Time of day in HH:mm format in the local timezone that specifies when this entrance closes. If missing, the entrance is accessible 24/7.
Example Response without Policy
Policies are seldom applicable for properties in garden-style settings, such as suburban apartment complexes. Such responses, therefore, consist of a more predictable sequence of steps the personnel needs to take to complete the job.
{
  "routes": [
    {
      "fragments": [
        {
          "origin": {
            "location": {
              "latitude": 37.40688964634161,
              "longitude": -122.10762834057806
            },
            "type": "PARKING",
            "data": {
              "text": "PARKING",
              "stopPointData": {
                "type": "PARKING_PRIVATE"
              }
            }
          },
          "destination": {
            "location": {
              "latitude": 37.40685703829996,
              "longitude": -122.1080146240955
            },
            "type": "ENTRANCE",
            "data": {
              "text": "ENS",
              "entranceData": {
                "realm": "BUILDING",
                "modalities": [
                  "WALKING"
                ],
                "label": "side"
              }
            }
          },
          "type": "WALKING"
        },
        {
          "origin": {
            "location": {
              "latitude": 37.40685703829996,
              "longitude": -122.1080146240955
            },
            "type": "ENTRANCE",
            "data": {
              "text": "ENS",
              "entranceData": {
                "realm": "BUILDING",
                "modalities": [
                  "WALKING"
                ],
                "label": "side"
              }
            }
          },
          "destination": {
            "location": {
              "latitude": 37.40689034284607,
              "longitude": -122.1081139235705
            },
            "type": "UNIT",
            "data": {
              "text": "352",
              "unitData": {
                "unit": "352",
                "uiData": {
                  "buildingShape": {
                    "point": [
                      {
                        "latitude": 37.407216109939625,
                        "longitude": -122.10878561226696
                      },
                      {
                        "latitude": 37.40678904474598,
                        "longitude": -122.10809168220868
                      },
                      {
                        "latitude": 37.407239237176,
                        "longitude": -122.10758147238448
                      },
                      {
                        "latitude": 37.40775021962394,
                        "longitude": -122.10829399140448
                      },
                      {
                        "latitude": 37.40729965291945,
                        "longitude": -122.10875999999917
                      },
                      {
                        "latitude": 37.40727432644777,
                        "longitude": -122.1087256588803
                      }
                    ]
                  },
                  "mapCenter": {
                    "latitude": 37.40689034284607,
                    "longitude": -122.1081139235705
                  },
                  "address": "2255 Showers Dr, Mountain View, CA",
                  "unit": "352",
                  "floor": 3
                },
                "isBeans": true,
                "hasElevator": true,
                "hasStair": true,
                "hasGate": true,
                "numberOfUnits": 132,
                "numberOfBuildings": 1,
                "society": "Parc Crossings",
                "hasParking": true
              },
              "floor": 3
            }
          },
          "type": "WALKING"
        }
      ],
      "origin": {
        "latitude": 37.40688964634161,
        "longitude": -122.10762834057806
      },
      "destination": {
        "address": "2255 Showers Dr, 94040",
        "unit": "352",
        "location": {
          "latitude": 37.40689034284607,
          "longitude": -122.1081139235705
        }
      },
      "navigateTo": {
        "latitude": 37.40688964634161,
        "longitude": -122.10762834057806
      }
    }
  ],
  "queryId": "bkP4nQ-EkNrqYYxqpGgD-3HA_pbfYVgtnrBPlIVr0_GJye8uW6etmiqwHPUsQMm1UIACgnQSM1YT1w0UuAUjsw9itaYwQekxW9Czb0WL-aLJNz-O2mDZLEEK_g2EQhLb3FX9Lw"
}
Example Response with Policy
Policies are often applicable for properties in downtowns, such as offices or high-rise buildings. Such responses, therefore, are more nimble and change based on the policy. For example, if the personnel are not allowed to go beyond the front desk, a route may end at the front desk and the location of the unit may never be required.
{
    "routes": [
        {
            "fragments": [
                {
                    "origin": {
                        "location": {
                            "latitude": 41.87227824031148,
                            "longitude": -87.63107645526804
                        },
                        "type": "ENTRANCE",
                        "data": {
                            "text": "ENP",
                            "entranceData": {
                                "realm": "PARKING",
                                "modalities": [
                                    "DRIVING"
                                ]
                            }
                        }
                    },
                    "destination": {
                        "location": {
                            "latitude": 41.87256861579449,
                            "longitude": -87.6307038743054
                        },
                        "type": "PARKING",
                        "data": {
                            "text": "PARKING",
                            "stopPointData": {
                                "type": "PARKING_PRIVATE"
                            }
                        }
                    },
                    "type": "DRIVING"
                },
                {
                    "origin": {
                        "location": {
                            "latitude": 41.87256861579449,
                            "longitude": -87.6307038743054
                        },
                        "type": "PARKING",
                        "data": {
                            "text": "PARKING",
                            "stopPointData": {
                                "type": "PARKING_PRIVATE"
                            }
                        }
                    },
                    "destination": {
                        "location": {
                            "latitude": 41.87246657700007,
                            "longitude": -87.63076739099995
                        },
                        "type": "ENTRANCE",
                        "data": {
                            "text": "E",
                            "entranceData": {
                                "streetName": "730 S Clark St, 60605",
                                "entranceTimes": [
                                    {
                                        "dayOfWeek": "TUESDAY",
                                        "entranceTime": {
                                          "start": "07:00",
                                          "end": "18:00"
                                        }
                                    }
                                ],
                                "realm": "BUILDING",
                                "modalities": [
                                    "WALKING"
                                ],
                                "instructions": [
                                    {
                                        "type": "FRONT_DESK"
                                    }
                                ],
                                "accessToUnit": true,
                                "notes": "Entrance is only accessible to staff after hours. Doors will be locked."
                            }
                        }
                    },
                    "type": "WALKING"
                },
                {
                    "origin": {
                        "location": {
                            "latitude": 41.87246657700007,
                            "longitude": -87.63076739099995
                        },
                        "type": "ENTRANCE",
                        "data": {
                            "text": "E",
                            "entranceData": {
                                "streetName": "730 S Clark St, 60605",
                                "entranceTimes": [
                                    {
                                        "dayOfWeek": "TUESDAY",
                                        "entranceTime": {
                                          "start": "07:00",
                                          "end": "18:00"
                                        }
                                    }
                                ],
                                "realm": "BUILDING",
                                "modalities": [
                                    "WALKING"
                                ],
                                "instructions": [
                                    {
                                        "type": "FRONT_DESK"
                                    }
                                ],
                                "accessToUnit": true,
                                "notes": "Entrance is only accessible to staff after hours. Doors will be locked."
                            }
                        }
                    },
                    "destination": {
                        "location": {
                            "latitude": 41.872518843101155,
                            "longitude": -87.63097595345396
                        },
                        "type": "ELEVATOR",
                        "data": {
                            "text": "EL"
                        }
                    },
                    "type": "WALKING"
                },
                {
                    "origin": {
                        "location": {
                            "latitude": 41.872518843101155,
                            "longitude": -87.63097595345396
                        },
                        "type": "ELEVATOR",
                        "data": {
                            "text": "EL"
                        }
                    },
                    "destination": {
                        "location": {
                            "latitude": 41.87250934147018,
                            "longitude": -87.63094023431529
                        },
                        "type": "UNIT",
                        "data": {
                            "text": "2306",
                            "unitData": {
                                "unit": "2306",
                                "uiData": {
                                    "buildingShape": {
                                        "point": [
                                            {
                                                "latitude": 41.872760614905275,
                                                "longitude": -87.63108806462138
                                            },
                                            {
                                                "latitude": 41.87276810459427,
                                                "longitude": -87.63077491671889
                                            },
                                            {
                                                "latitude": 41.87230752024264,
                                                "longitude": -87.63076032040361
                                            },
                                            {
                                                "latitude": 41.872295536653546,
                                                "longitude": -87.63094069895986
                                            },
                                            {
                                                "latitude": 41.872295536653546,
                                                "longitude": -87.63094204006437
                                            },
                                            {
                                                "latitude": 41.872293040072165,
                                                "longitude": -87.63095679221395
                                            },
                                            {
                                                "latitude": 41.87228205511309,
                                                "longitude": -87.63095545110944
                                            },
                                            {
                                                "latitude": 41.87228055716397,
                                                "longitude": -87.63100909528974
                                            },
                                            {
                                                "latitude": 41.872273566734286,
                                                "longitude": -87.63101043639425
                                            },
                                            {
                                                "latitude": 41.87226557767086,
                                                "longitude": -87.63107615051511
                                            }
                                        ]
                                    },
                                    "mapCenter": {
                                        "latitude": 41.87250934147018,
                                        "longitude": -87.63094023431529
                                    },
                                    "address": "730 S Clark St, Chicago, IL",
                                    "unit": "2306",
                                    "floor": 23
                                },
                                "isBeans": true,
                                "hasElevator": true,
                                "hasStair": true,
                                "hasGate": true,
                                "accuracy": "ACCURACY_MATCH_BUILDING_PARTIAL_UNIT",
                                "numberOfUnits": 298,
                                "numberOfBuildings": 1,
                                "hasParking": true
                            },
                            "floor": 23
                        }
                    },
                    "type": "WALKING"
                }
            ],
            "origin": {
                "latitude": 41.87227824031148,
                "longitude": -87.63107645526804
            },
            "destination": {
                "address": "730 S Clark St, 60605",
                "location": {
                    "latitude": 41.87250934147018,
                    "longitude": -87.63094023431529
                }
            },
            "navigateTo": {
                "latitude": 41.87227824031148,
                "longitude": -87.63107645526804
            }
        }
    ],
    "queryId": "XRf4aGQA3TYEVRjzdz2wOYLzd-moymlOzPqn_3cyWqjLYzRp2j66UXCuKrBob_MR6oaZXAjDzBk1nMz0iF8oJZmJD1hdNV1Bm_rBEaJgWMHo870icbK6Z2X7YSu-d5rnC9sgNQ"
}