You can use the Proximity Beacon API to register beacons in the cloud, associate data with registered beacons as attachments, and maintain beacon registration data. This guide walks you through creating a Google Developers Console project, activating the Proximity Beacon API, and obtaining the appropriate credentials.
Every request your application sends to the Proximity Beacon API must be either
authorized using OAuth 2.0, or authenticated with an API key. Requests which
can modify beacon data or return administrative beacon data must be
authorized using OAuth 2.0.
Requests for public data (for example calls to methods like
beaconinfo.getforobserved
)
do not require authorization, but must still be authenticated by using an
API key.
Before using the Proximity Beacon API, it is helpful to understand the basics of RESTful web services and JSON representations.
Get a Google Account
To use the Google Proximity Beacon API, you need a Google Account. If you already have an account, then you're all set. You may also want to create a separate Google Account for testing purposes.
Request an OAuth 2.0 Client ID
Requests which can modify beacon data, or return administrative beacon data, must be authorized using OAuth 2.0. Follow these steps to request an OAuth 2.0 client ID for the Google Proximity Beacon API.
- Go to the Google Developers Console.
- Select a project, or create a new one. If you are using the Nearby Messages API, be sure to use the same Google Developers Console project that the Nearby Messages API is registered under.
- Click Continue to enable the Google Proximity Beacon API.
- Click Go to credentials.
- Click New credentials, then select OAuth Client ID.
- Under Application type, select the appropriate choice for your app (Web application, Android, iOS, etc.). Select Web application to get credentials you can use with the OAuth 2.0 Playground.
- You will be prompted for further information based on the Application type you chose. Fill in the appropriate fields.
Click Create to get your new OAuth 2.0 Client ID. The ID appears as a string of characters that looks something like this:
780816631155-gbvyo1o7r2pn95qc4ei9d61io4uh48hl.apps.googleusercontent.com
Request a browser API key
Requests for public data (for example calls to methods like
beaconinfo.getforobserved
)
do not require authorization, but must still be authenticated by using an API
key. Follow these steps to request a browser API key for the Google Proximity Beacon API.
- Go to the Google Developers Console.
- Select a project, or create a new one. If you are using the Nearby Messages API, be sure to use the same Google Developers Console project that the Nearby Messages API is registered under.
- Click Continue to enable the Google Proximity Beacon API.
- Click Go to credentials.
- Click New credentials, then select API Key.
- Under Create a new key select Browser key.
- Enter a name for the key.
- Under Accept request from these HTTP referrers (web sites), enter the base URL of the site from which requests will originate. You can skip this step if the key will only be used for testing.
- Click Create. Your new API key will appear in the list of API keys for your project.
Try the REST API in the OAuth Playground
The OAuth Playground is the easiest way to familiarize yourself with the Google Proximity Beacon API by submitting HTTP requests and observing the responses.
- If you have not done so already, follow these instructions to create a new Web application client ID.
- Go to the OAuth 2.0 Playground.
- Click the gear icon to open the configuration options and make the following
changes:
- Set OAuth flow to Client-side.
- Check Use your own OAuth credentials.
- Paste in your OAuth client ID.
- Close the configuration options.
- Under Step 1 Select & authorize APIs, paste the scope for the
Proximity Beacon API into the field labeled Input your own scopes:
https://www.googleapis.com/auth/userlocation.beacon.registry
- Click Authorize APIs.
- Click Allow when prompted.
- Under Step 2 Configure request to API, paste the following URI into the
Request URI field:
https://proximitybeacon.googleapis.com/v1beta1/beacons
- Set HTTP Method to GET.
- Click Send the request.
The response body should show a status of
200 OK
, and look similar to this:HTTP/1.1 200 OK Alternate-protocol: 443:quic,p=1 Content-length: 1799 X-xss-protection: 1; mode=block Content-location: https://proximitybeacon.googleapis.com/v1beta1/beacons?q=status:active X-content-type-options: nosniff Transfer-encoding: chunked Vary: Origin, X-Origin, Referer Server: ESF -content-encoding: gzip Cache-control: private Date: Fri, 04 Sep 2015 17:04:22 GMT X-frame-options: SAMEORIGIN Alt-svc: quic=":443"; p="1"; ma=604800 Content-type: application/json; charset=UTF-8 { "beacons": \[ { "status": "ACTIVE", "description": "Dot Beacon, reporting for duty!", "indoorLevel": { "name": "1" }, "latLng": { "latitude": 47.669377099999998, "longitude": -122.1966037 }, "placeId": "ChIJTxax6NoSkFQRWPvFXI1LypQ", "advertisedId": { "type": "EDDYSTONE", "id": "hZ3uYXQBwm2IsAAAAAAAyA==" }, "beaconName": "beacons/0123abcd4567efgh890", "expectedStability": "STABLE", "properties": { "type": "Radius Dot beacon", "location": "Entryway" } } \], "nextPageToken": "Civ55cv//f/9zN7NnMrGzZ7LnJ6bysbJnsmZzJ3Oz8/Pz8/Pz8/Pz8/PzP/+EAMh5L1umSgzmnQxBQHmb3DvF+sxZZVNTdNeID05AgACADQaAABQAFoLCdMiAswr49SsEAE", "totalCount": "3" }
Visit the Proximity Beacon API reference to learn more about how to make various types of requests.
Make an authenticated request
You can make calls against beaconinfo.getforobserved
to return public data associated with your beacons. You can do this using the
REST client
of your choice.
- If you don't have a browser API key, see Get Started with the Proximity Beacon REST API to find out how to obtain credentials for authorization and authentication.
Open the REST client of your choice, and make a POST request using the following URL and request body (use the API key you created in the first step). Be sure to set your REST client to use the
application/json
content type for the request body.https://proximitybeacon.googleapis.com/v1beta1/beaconinfo:getforobserved?key=API_KEY { "observations": \[ { "advertisedId": { "type": "EDDYSTONE", "id": "YOUR-BEACON-ID" } } \], "namespacedTypes": \[ "*" \], }
The response body should show a status of
200 OK
, and look similar to this:HTTP/1.1 200 OK Alternate-protocol: 443:quic,p=1 Content-length: 534 X-xss-protection: 1; mode=block X-content-type-options: nosniff Transfer-encoding: chunked Vary: Origin, X-Origin, Referer Server: ESF -content-encoding: gzip Cache-control: private Date: Fri, 04 Sep 2015 17:54:18 GMT X-frame-options: SAMEORIGIN Alt-svc: quic=":443"; p="1"; ma=604800 Content-type: application/json; charset=UTF-8 { "beacons": \[ { "attachments": \[ { "data": "QmFuYW5hczoyCg==", "namespacedType": "psyched-silicon-89888/string" }, { "data": "VVMtS0lSLTZUSEItMS0xMTVH", "namespacedType": "psyched-silicon-89888/string" } \], "advertisedId": { "type": "EDDYSTONE", "id": "hZ3uYYZBwm2IsAAAAAAAyA==" }, "description": "Dot Beacon, reporting for duty!", "beaconName": "beacons/0123abcd4567efgh890" } \] }
Next steps
To learn more about the REST API, see these pages: