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)
  • monitor their health (with the help of Eddystone-TLM)

This is known as Google 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

Info: It used to be possible to do the registration via Google’s Beacon Tools apps. That app is no longer available in the iOS App Store, and doesn’t seem to be actively maintained on Android. For the time being, we recommend using the method shown below.

Google’s own documentation is available here:

There are Python scripts available that abstract some of the complexity of this process:

There are also example mobile apps for managing beacons with the Proximity Beacon API:

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 Google’s Beacon Dashboard.