Google Proximity Beacon API

Google has its own cloud service where you can:

  • register your beacons
  • attach extra metadata to them (e.g., for use with Nearby Messages API, Nearby Notifications, or Places API)
  • monitor their health (with the help of Eddystone-TLM)

This is known as Proximity Beacon API, and it also comes with a simple Beacon Dashboard.

What’s ahead (aka Table of Contents)

Register your Estimote Beacons with Google

Using Proximity Beacon API

Google’s own documentation about this method is available here:
- Register beacons using the Proximity Beacon API

There are Python scripts available that abstract some of the complexity of this process:
- Proximity Beacon API Scripts

There are also example mobile apps for managing beacons with the Proximity Beacon API:
- Android Beacon Service Demo App
- iOS Beacon Service Demo App

If you’re just trying things out, one of the easiest ways to send requests to Proximity Beacon API is via Google’s OAuth 2.0 Playground:

Step 1: Enable Google Proximity Beacon API

Go to console.developers.google.com/apis/library/proximitybeacon.googleapis.com

In the top-left corner, select the project you want to use or create a new one. Then click “Enable”.

Step 2: Generate OAuth credentials

Go to console.developers.google.com/apis/credentials

In the top-left corner, make sure you’re still on the correct project. Then:

  • click the “Create credentials” button and pick “OAuth client ID”
  • for “Application type”, select “Web application”
  • in the “Authorized redirect URIs”, type “https://developers.google.com/oauthplayground”
  • save, and copy the “client ID” you’ll get in a popup

If this is your first time using OAuth with Google APIs, you may have to go to “OAuth consent screen” tab first, and fill in “Product name shown to users”. For now, you can make it “Beacon API Test”, or something like that.

Step 3: Set up OAuth Playground

Go to developers.google.com/oauthplayground

Click the gear icon in the top-right corner and:

  • change “OAuth flow” to “Client-side”
  • tick the “Use your own OAuth credentials” checkbox
  • paste the client ID you got in the previous step

Then, on the left side, in the “Input your own scopes” text field, type:
https://www.googleapis.com/auth/userlocation.beacon.registry

Click “Authorize APIs”. You’ll be redirected to an OAuth authorization screen, and then back to the playground.

Step 4: Register a beacon

For “HTTP Method”, pick “POST”. For “Request URI”, type:
https://proximitybeacon.googleapis.com/v1beta1/beacons:register

Then click “Enter request body” and paste this:

{
  "advertisedId": {
    "type": "EDDYSTONE",
    "id": "<read below>"
  },
  "status": "ACTIVE"
}

For a full list of available properties, consult the Proximity Beacon API reference of the “beacon” resource:
https://developers.google.com/beacons/proximity/reference/rest/v1beta1/beacons

The id field must be a base64-encoded string of the binary identifier your beacon broadcasts, which is slightly tricky to obtain. Here’s an example Ruby code to convert Eddystone-UID namespace + instance into an id that the Proximity Beacon API should accept:

require 'base64'
namespace = 'edd1ebeac04e5defa017'
instance = '1a15b246a719'
puts Base64.strict_encode64([namespace + instance].pack('H*'))

The output for this example code is: 7dHr6sBOXe+gFxoVskanGQ==, and that’s what you would use for the id in the request body.

Finally, click “Send the request”. The response in this example was:

HTTP/1.1 200 OK
...
{
  "status": "ACTIVE",
  "advertisedId": {
    "type": "EDDYSTONE",
    "id": "7dHr6sBOXe+gFxoVskanGQ=="
  },
  "beaconName": "beacons/3!edd1ebeac04e5defa0171a15b246a719"
}

You should now see the beacon on the Beacon Dashboard, and be able to manage some of its configuration (e.g., add attachments or Nearby Notifications) somewhat easier than via an API (-:

Using Beacon Tools [Location Beacons only]

You can also use Google’s Beacon Tools app, available on iOS and Android. However, Beacon Tools requires Eddystone Configuration Service to be enabled on your Estimote Beacon, and ECS is currently supported by Location Beacons only. Learn more about how to enable it in the Eddystone Configuration Service section.