Enterprise API v2

All Endpoints

The Enterprise API is a family of address, geocoding and place endpoints served over HTTPS, returning JSON. Every endpoint uses the same key, the same Authentication header, and the same host.

API Endpoint Answers
Search (Geocoding) GET /v2/search/beans Where exactly is this address — and how does a driver get to the door? Returns routes, waypoints, entrances, parking, notes and building policy.
Reverse Geocode GET /v2/search/geocode What address — and which unit — is at this lat/lng?
Autocomplete GET /v2/search/auto-complete What street addresses match what the user has typed so far?
Unitcomplete GET /v2/search/unit-complete Which units exist at this address, matching what the user has typed?
Address Verifier GET /v2/verify/address Is this address real and unambiguous? Returns each variation it could mean.
Classification (RBDI) GET /v2/search/rbdi Residential or business? Apartment, condo, campus, mall? High-rise or garden-style?
Address Type Identifier GET /v2/address/type Is this address residential, and is it a multi-dwelling unit? A lighter answer than RBDI.
POI Lookup GET /v2/search/poi What points of interest fall inside this bounding box?
Indoor Path GET /v2/search/path What is the walking path through a set of indoor waypoints, and in what order?
Routing & Optimization POST isp.beans.ai … Route paths, stop sequencing, and distance/time matrices. Documented separately — see Routing.

Account Setup

Register an enterprise account at https://www.beans.ai/enterprise-console. A key and secret are generated for you automatically; keep them confidential.

Some endpoints additionally require your account to be allow-listed. The Search and Reverse Geocode APIs are the notable ones — if you get an unauthorized response on those with a key that works elsewhere, that is why. Contact sales@beans.ai.

Authentication

Every endpoint on this page uses the same standard authorization header. If you use an unauthorized key, or do not provide one, you get a NOT_ALLOWED response.

Specify your key and secret in the Authorization header of all requests, 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 an optional header to track responses at your end. This is handy when your service makes asynchronous requests and you want to tie a response back to your original request — it is echoed back as trackingId.

Tracking-Id: <client request tracking identifier>

Hosts & Formats

Item Value
Host https://api.beans.ai — use this. api2.beans.ai is also accepted and still appears in some older integrations; both reach the same service.
Path prefix /enterprise/v2/. Endpoints shortened to /v2/… in the table above carry this prefix in full.
Routing host The routing endpoints live on https://isp.beans.ai and are still v1. See Routing.
Response format JSON by default. The Search API additionally accepts a format header of JSON, PROTO or GOOGLE, the last returning a shape compatible with the Google Geocoding API.

Errors & Empty Results

Situation What you get
Missing or unauthorized key NOT_ALLOWED.
Key valid, but endpoint not enabled for your account Also unauthorized. This is an allow-listing question, not a credentials one — see Account Setup.
No match for the query A successful response with the result list omitted or empty — for Search, routes is absent or []. Treat "no match" as a normal outcome, not an error.
Fields you do not recognise Responses may carry fields not documented here. Parse leniently and ignore unknown fields — they will grow over time.

Try It Live

Every endpoint on this page can be run against your own key, with editable parameters and the raw response, from the Enterprise Console under Playground. It signs the request with your account's key, so what you see there is exactly what your integration will get.

Search API v2

Base Url
GET https://api.beans.ai/enterprise/v2/search/beans
Authentication
Same for every endpoint — see Authentication.
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 CUSTOMER_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.
X-Beansai-Include-Building-Footprint Boolean. Include the building footprint polygon in pointsOfInterest.
Example Request
$ curl -X GET \
  'https://api.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 beneficial 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 delivery 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.

Reverse Geocoding API v2

Base Url
GET https://api.beans.ai/enterprise/v2/search/geocode
Authentication
Same for every endpoint — see Authentication.
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://api.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

Address Autocomplete API v2

Base Url
GET https://api.beans.ai/enterprise/v2/search/auto-complete
Authentication
Same for every endpoint — see Authentication.
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://api.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 representing a potential completion of the address. The response for the above address autocomplete sample request is below

Address Unitcomplete API v2

Base Url
GET https://api.beans.ai/enterprise/v2/search/unit-complete
Authentication
Same for every endpoint — see Authentication.
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://api.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 representing 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

Address Verifier API v2

Base Url
GET https://api.beans.ai/enterprise/v2/verify/address
Authentication
Same for every endpoint — see Authentication.
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://api.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 or more address items, each representing 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

POI Lookup API v2

Base Url
GET https://api.beans.ai/enterprise/v2/search/poi
Authentication
Same for every endpoint — see Authentication.
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://api.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 or more point of interest items, each representing a potential point of interest.

Address Classification(RBDI) API

Base Url
GET https://api.beans.ai/enterprise/v2/search/rbdi
Authentication
Same for every endpoint — see Authentication.
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://api.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

Address Type Identifier API

Base Url
GET https://api.beans.ai/enterprise/v2/address/type
Authentication
Same for every endpoint — see Authentication.
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://api.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

Indoor Path API v2

Given a set of indoor waypoints, returns the walking path between them and, optionally, the best order to visit them in. This is the same path engine the MapsWidget uses to draw its wayfinding line, exposed directly for cases where you want the geometry without rendering a map.
Base Url
GET https://api.beans.ai/enterprise/v2/search/path
Authentication
Same for every endpoint — see Authentication.
Request Parameters
Request Parameters Type? Required? Values
waypoints Semicolon separated quadruple of
Double, Double, Double, String		 Yes Quadruples of lat, lng, elevation, name. Elevation distinguishes floors, so a path can cross levels.
findBestSequence Boolean No Reorder the waypoints into the shortest route rather than visiting them as given.
preserveFirstStop Boolean No When reordering, pin the first waypoint in place.
preserveLastStop Boolean No When reordering, pin the last waypoint in place.
Example Request
$ curl -X GET \
'https://api.beans.ai/enterprise/v2/search/path?waypoints=32.8264607729915,-96.84978217271895,3.0,A;32.82701237436884,-96.84987603133914,3.0,C;32.82651059989373,-96.85022429570184,3.0,B;32.82639019340066,-96.84993787453772,3.0,D' \
-H 'Authorization: Basic a2V5OnNlY3JldA=='
Response Object
The response consists of three arrays: point, leg, and order. The response for the sample request above is below.

Routing & Optimization

Route paths, stop sequencing, and distance/time matrices are part of the Beans routing engine rather than the address stack, and they have their own full reference: Routing API v1.

Two things differ from every other endpoint on this page, which is why they are not documented inline:
  1. They are served from https://isp.beans.ai, not api.beans.ai.
  2. They are still /enterprise/v1/. That is current, not stale — the routing API simply versions independently of the address APIs.
Your enterprise key works on both hosts.

API Endpoint Answers
Route Path POST isp.beans.ai/enterprise/v1/dro/path What is the drivable path through this ordered list of stops?
Route Optimization POST isp.beans.ai/enterprise/v1/dro/sequence What is the best order to visit these stops, given a start and an end?
Distance / Time Matrix POST isp.beans.ai/enterprise/v1/dro/timedistance_matrix How far, and how long, between every pair of these points?
The routing reference also covers the stateful variants — routes, items, warehouses and assignees that persist in Beans — which have no equivalent on this page.