Enterprise API v2

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

Other headers

Parameter	Values
format	JSON, PROTO, or GOOGLE. GOOGLE return the response in the format same as the Google Geocoding API.
X-Beansai-Include-Notes-And-Markers	Boolean. Include notes and markers in the response.
X-Beansai-Include-Points-Of-Interest	Boolean. Include points of interest.
X-Beansai-Include-Generated-Route	Boolean. Include indoor generated path.

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 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
pointsOfInterest	Array	No	PointOfInterest object
trackingId	String	No	Client provided optional tracking id

PointOfInterest Object

Each PointOfInterest object represents a contextual object around the Routes. For example, building footprints, facilities.

PointOfInterest Object	Type	Required?	Description
type	String	Yes	One of FACILITIES, UNIT, BUILDING, ENTRANCE, STAIR, ELEVATOR, or PARKING.
name	String	No	Any descriptive name given to this point of interest
footprint.point	Array	No	Array of LatLng objects describing the polygon for point of interest

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 (note: this is of different type from the top level PointOfInterest)
origin	LatLng 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).
location	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.
shape.point	Array	No	Array of LatLng objects describing the polygon for this route point.
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.parkingInstruction	String	No	Specifies the best parking type associated with this address. One of DESIGNATED_PARKING, PUBLIC_PARKING, NO_PARKING
entranceData.bestModesOfTransport	Array	No	An array of strings that specifies the bets possible delivery modes of transport to this address. Possible values are CAR, MOTORCYCLE, BIKE, BIKE_SCOOTER, FOOT
entranceData.easeOfParking	Integer	No	Specifies an integer value for ease of parking for that address and/or unit. values will be between 1 and 5 (1 being most accessible and 5 being most difficult to find parking)
entranceData.easeOfDelivery	Boolean	No	Specifies an integer value for ease of delivery for that address and/or unit. values will be between 1 and 5 (1 being easy and 5 being most difficult)
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

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, FRONT_DESK, DROP_OFF, 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.

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.

Base Url

GET https://api.beans.ai/enterprise/v2/search/geocode

Authentication

The Beans Reverse Geocoding 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==

Request Parameters

Request Parameters	Type?	Required?	Values
latlng	String	Yes	comma separated latitude, longitude values (WGS84)
elevation	Double	No	Elevation data (Z-Axis). height in meters
distance	Integer	No	maximum distance in meters to specify search radius (Default: 20)
maxResults	Integer	No	max address results to return (ordered by closest distance first)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/search/geocode?latlng=41.875373,-87.6279018&distance=20' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of one more civic location addresses (see Unit object) along with unit level information if available. Response will be an ordered list with the closest matching address to distance (lat, lng) and followed by elevation (z-axis) match if available.

Unit Object

Unit consists of address info with secondary unit information along with additional data which is described in UnitData object

Unit Object	Type	Required?	Description
address	String	Yes	Address info for the specific unit. P.S: this could be different that the society address
unit	String	Yes	Secondary Unit designation and number. e.g. Apt 101
building	String	Yes	Building number or label if available
location	LatLng Object	Yes	Accurate location info of the unit
distance	Double	Yes	Specifies the distance from the request latlng in meters
unitData	UnitData Object	Yes	Additional info of the unit

UnitData Object

UnitData consists of additional useful about the unit including floor and the access to the unit (elevator, stair, parking) etc

UnitData Object	Type	Required?	Description
floor	String	No	Floor of the unit if applicable
hasElevator	Boolean	No	indicates if the building has an elevator
hasStair	Boolean	No	indicates if the building has stairs
hasParking	Boolean	No	indicates if the building has parking

The response for the above address autocomplete sample request is below

Base Url

GET https://api.beans.ai/enterprise/v2/search/auto-complete

Authentication

The Beans Address Verifier 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==

Request Parameters

Request Parameters	Type?	Required?	Values
address	String	Yes	Part of street address that needs completing
center	String	No	lat,lng (for example, 37.40694497143785,-122.108284)
searchRadius	Integer	No	Distance from center in meters (for example, 10000 meters)
searchCount	Integer	No	Number of results to return, defaults to 15
summarize	Boolean	No	Restricts the response to only return the address, defaults to false
addComponents	Boolean	No	Adds address components to ther response, defaults to false
country	String	No	ISO3-Country code (Default: USA)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/search/auto-complete?address=299+West+W&addComponents=true' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of one more autocomplete items, each repesenting a potential completion of the address. The response for the above address autocomplete sample request is below

Base Url

GET https://api.beans.ai/enterprise/v2/search/unit-complete

Authentication

The Beans Address Unitcomplete 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==

Request Parameters

Request Parameters	Type?	Required?	Values
address	String	Yes	Full street address (line 1, city, state zip)
unit	String	Yes	Part of unit address that needs completing
country	String	No	ISO3-Country code (Default: USA)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/search/unit-complete?address=299+West+Washington+Ave%20+Sunnyvale%20+CA&unit=31' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of one more unitcomplete items, each repesenting a potential variation of the address. Each unitcomplete item further contains a list of units that match the specified unit prefix. The response for the above address unitcomplete sample request is below

Base Url

POST https://api.beans.ai/enterprise/v2/search/feedback

Authentication

The Beans Feedback 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==

Request Body

Request Object	Type?	Required?	Values
address	String	Yes	Full street address (line 1, city, state zip)
unit	String	No	Unit number of address (line 2)
geo	Double,Double	No	Latitude,Longitude pair of the end user's current location
action	String	No	Either of DELIVERY or PICKUP or DROPOFF
actionAt	Long	No	Epoch timestamp of when the action was performed
notes	String	No	General notes from drivers or other personnel
precision	Integer	No	Accuracy (in meters)

Example Request

$ curl -X POST \
'https://api2.beans.ai/enterprise/v2/search/feedback/XRf4aGQA3TYEVRjzdz2wOYLzd-moymlOzPqn_3cyWqj' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

The response for a feedback request is a standard http response code.

Base Url

GET https://api.beans.ai/enterprise/v2/verify/address

Authentication

The Beans Address Verifier 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==

Request Parameters

Request Parameters	Type?	Required?	Values
address	String	Yes	Full street address (line 1, city, state zip)
unit	String	No	Unit number of address (line 2)
country	String	No	ISO3-Country code (Default: USA)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/verify/address?address=299+West+Washington+Ave%20+Sunnyvale%20+CA&unit=' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of one more address items, each repesenting a potential variation of the address. If only one item with zero or one unit is returned, then the address is not ambiguous. The response for the above Address verifier sample request is below

Base Url

GET https://api.beans.ai/enterprise/v2/search/poi

Authentication

The Beans POI Lookup 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==

Request Parameters

Request Parameters	Type?	Required?	Values
topLeft	Double,Double	Yes	Latitude,Longitude pair of the top left (NW) corner of the area to be searched
bottomRight	Double,Double	Yes	Latitude,Longitude pair of the bottom right (SE) corner of the area to be searched

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/search/poi?topLeft=37.412859,-122.086259&bottomRight=37.347142,-121.99' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of one more point of interest items, each repesenting a potential point of interest.

Base Url

GET https://api.beans.ai/enterprise/v2/search/rbdi

Authentication

The Beans Address Verifier 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==

Request Parameters

Request Parameters	Type?	Required?	Values
address	String	Yes	Full street address (line 1, city, state zip)
unit	String	No	Unit number of address (line 2)
country	String	No	ISO3-Country code (Default: USA)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/search/rbdi?address=299+West+Washington+Ave%20+Sunnyvale%20+CA&unit=' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of an address and its primary, secondary and an optional tertiary classification. Primary classification indicates whether the provided address is Residential, Business or mixed. Secondary classification indicates MDU-Apartments, Condos, Mobile homes, colleges, shopping malls, hospitals, etc. Tertiary classification indicates high-rise, mid-rise, garden-style etc. The response for the above Address classification sample request is below

Base Url

GET https://api.beans.ai/enterprise/v2/address/type

Authentication

The Beans Address Type Identifier 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==

Request Parameters

Request Parameters	Type?	Required?	Values
address	String	Yes	Full street address (line 1, city, state zip)
country	String	No	ISO3-Country code (Default: USA)

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/address/type?address=299+West+Washington+Ave%20+Sunnyvale%20+CA&country=USA' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will indicate the type of the request address, primarily if its residential and if its a MDU. The response for the above Address Type sample request is below

Base Url

GET https://api.beans.ai/enterprise/v2/published/{contractID}

Authentication

The Beans Published Data 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==

Request Parameters

Request Parameters	Type?	Required?	Values
updatedAfter	String	No	Date in yyyy-MM-dd format to get the data published after a specific date

Example Request

$ curl -X GET \
'https://api2.beans.ai/enterprise/v2/published/{data.client:yyyy:n}' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='

Response Object

Response will consist of an array of data objects published for the specified contract.

Enterprise API v2

Search

Reverse Geocode

Address Autocomplete

Address Unitcomplete

Feedback

Address Verifier

POI Lookup

Address Classification (RBDI)

Address Type Identifier

Published Data

Search API v2

Request

Base Url

Authentication

Query Parameters

Other headers

Example Request

Response

Response Object

PointOfInterest Object

Route Object

Fragment Object

Point Object

Point Object Types

Location Object

LatLng Object

Data Object

Variable JSON Data Objects

EntranceInstruction Object

EntranceTime Object

Example Response without Policy

Example Response with Policy

Reverse Geocoding API v2

Request

Base Url

Authentication

Request Parameters

Example Request

Response

Response Object

Unit Object

UnitData Object

Address Autocomplete API v2

Request

Base Url

Authentication

Request Parameters

Example Request

Response

Response Object

Address Unitcomplete API v2

Request

Base Url

Authentication

Request Parameters

Example Request

Response

Response Object

Feedback API v2

Request

Base Url

Authentication

Request Body

Example Request

Response

Response Object

Address Verifier API v2

Request

Base Url

Authentication

Request Parameters

Example Request

Response

Response Object

POI Lookup API v2

Request

Base Url

Authentication

Request Parameters