Enterprise API v1

Status & Versions

This page documents the v1 address endpoints. They remain available for existing integrations, but v1 is not where new work should start — Enterprise API v2 covers the same ground plus reverse geocoding, address verification, classification, POI lookup and indoor paths.

API Endpoint Status
Search POST /v1/search/beans Deprecated. Migrate to Search API v2, which is a GET with query parameters rather than a POST body.
Address Complete POST /v1/search/auto-complete Supported. You may continue to use it. The v2 equivalent is Autocomplete.
Unit Complete POST /v1/search/unit-complete Supported. You may continue to use it. The v2 equivalent is Unitcomplete.

The Search API v1 is deprecated. We strongly advise you to use the Search API v2. You may continue to use the Address Complete API v1 and Unit Complete API v1.

👉 The routing, account and list endpoints that also live under /enterprise/v1/ are a different family and are documented separately — see Routing API v1.

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. The same credentials work on v1 and v2.

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==

Search API v1

Base Url
POST https://api.beans.ai/enterprise/v1/search/beans
Authentication
Same for every endpoint — see Authentication.
Request Body
You must send the address and the unit that you are searching for as members of a JSON object in the body.
Request Object Type Required? Description
address String Yes Full street address (line 1, city, state zip).
unit String No Unit number of address (line 2).
Example Request
$ curl -X POST \
  'https://api.beans.ai/enterprise/v1/search/beans' \
  --data '{"address": "2255 Showers Dr, Mountain View, CA 94040", "unit": "352"}' \
  -H 'Authorization: Basic a2V5OnNlY3JldA==' \
  -H 'Content-Type: application/json'

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

Example Search Response

Address Complete API v1

Base Url
POST https://api.beans.ai/enterprise/v1/search/auto-complete
Authentication
Same for every endpoint — see Authentication.
Request Body
You must send the prefix of the address and the current position as members of a JSON object in the body.
Request Object Type Required? Description
address String Yes Prefix of the street address.
center LatLng Object Yes Current position that helps bias address complete results.
searchRadius Double No The maximum radius to restrict address complete results.
LatLng Object
A latlng object specifies 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.
Response Object
The response for an address complete request is a list of beans, each representing a potential address for the given prefix.
Response Object Type Required? Description
beans Array No Address Complete Beans object
Address Complete Beans Object
Each address complete bean specifies one street address that matches the given prefix, along with some other attributes that may help ease further processing.
Address Complete Beans Object Type Required? Description
address String Yes Full street address (line 1, city, state zip).
society String No The name of the society or business, if known.
placeId String No A unique Id associated with the address.
found String No Boolean that specifies if the Beans Search API and Unit Complete is likely to result a positive hit.
Example Address Complete Response

Unit Complete API v1

Base Url
POST https://api.beans.ai/enterprise/v1/search/unit-complete
Authentication
Same for every endpoint — see Authentication.
Request Body
You must send the address and the unit that you are searching for as members of a JSON object in the body.
Request Object Type Required? Description
address String Yes Full street address (line 1, city, state zip).
unit String Yes Prefix of the unit number.
Response Object
The response for a unit complete request is a list of beans, each representing a potential unit for the given address.
Response Object Type Required? Description
beans Array No Unit Complete Beans object
Unit Complete Beans Object
Each unit complete bean has just one string value that is the textual descriptor of the unit.
Unit Complete Beans Object Type Required? Description
unit String Yes Textual descriptor of the unit.
Example Unit Complete Response