The Google beacon platform is deprecated as of December 7, 2020. The platform will shut down on April 1, 2021.

Register Beacons

After a beacon has been set up to broadcast (provisioned), you can use the Proximity Beacon API to register the beacon, associating extra information that helps your users' devices to understand where they are. The registry entry for a beacon can include the following metadata:

The Advertised ID must be a valid Eddystone-UID beacon ID (16 bytes long, consisting of a 10-byte namespace and 6-byte instance ID). The ID value must be a base64 encoding of the binary byte-stream.

You can authorize people to register new beacons with your project using the Proximity Beacon API's IAM roles.

Register beacons with the Beacon Tools app

The easiest way to register beacons is by using the Beacon Tools app, available for Android and iOS. With the Beacon Tools app, you can register beacons with the Google Beacon Registry, and create attachments for them.

Register beacons using the Proximity Beacon API

Beacons are represented by the beacons resource, and you can register them using the beacons.register method.

  • A beacon can only be registered with one Google Developers Console project at a time. Attempting to register with multiple projects will result in an error.
  • Once a beacon has been registered, its AdvertisedID field may not be updated.
  • Be sure to configure your beacons prior to registration.

This example demonstrates how to register an Eddystone beacon at a specific location.

HTTP method
POST
Request URL
https://proximitybeacon.googleapis.com/v1beta1/beacons:register
Request body
{ "advertisedId": { "type": "EDDYSTONE", "id": "Fr4Z98nSoW0hgAAAAAAAAg==" }, "status": "ACTIVE", "placeId": "ChIJTxax6NoSkFQRWPvFXI1LypQ", "latLng": { "latitude": "47.6693771", "longitude": "-122.1966037" }, "indoorLevel": { "name": "1" }, "expectedStability": "STABLE", "description": "An example beacon.", "properties": { "position": "entryway" } }
Response
If the beacon is created successfully, the response is a 200 OK status code. The response body contains a JSON representation of the beacon, including a beacon.beaconName property that can be used as the reference to manage the beacon.

Register an Eddystone-EID beacon

Provisioning an Eddystone-EID beacon involves establishing a shared secret between the beacon hardware and a service that can 'resolve' the beacon's broadcast identity to stable information. There are two approaches to registering an Eddystone-EID beacon with the Google Proximity Beacon API:

  1. Complete the key exchange between the service and the beacon directly, guaranteeing that only the service with which the beacon is registered is able to resolve the beacon's broadcast ID.
  2. Complete the key exchange between the beacon and some other device (for example, a phone used to provision the beacon), then share the secret key from the device with any service that you wish to resolve the beacon.

The first approach gives the most secure outcome since the secret key is never exposed outside the beacon or Google Proximity Beacon API. The second approach allows you to register the same beacon with multiple resolvers, but adds the risk of the beacon's key being exposed.

Registration of Eddystone-EID uses the same Request URL as registration of Eddystone-UID. The request body differs in that it should include an EphemeralIdRegistration field. If you follow approach 1. above, then you should first make an empty request to getEidparams in order to obtain the server's public key. This is provided to the beacon at provisioning time through the beacon's GATT service. For full details, see the Eddystone-EID specification on GitHub.

Next, call beacons.register. Note that the advertisedId field of your request should have type EDDYSTONE. You should construct an Eddystone-UID for the advertisedId field, used to identify the beacon uniquely for administration purposes, as an alternative to the current EID broadcast. The UID is not used for serving attachments, and is only useful to authorised beacon administrators. The parameters required under EphemeralIdRegistration vary according to whether you follow approach 1. or 2. above.

Additionally, the Google Proximity Beacon API can store the provisioning key for your beacon. This key can be used to re-provision the beacon or alter its broadcast characteristics. It plays no role in the encryption of the Eddystone-EID protocol. The key is available only to users who are authorised to alter the beacon object in the service.

Once an Eddystone-EID beacon is registered, it can be treated similarly to an Eddystone-UID beacon in that you are able to add beacon properties, attachments, and create namespace/type-based subscriptions to those attachments through Nearby.

For administrative changes to the beacon, such as altering its description or expected stability, you can refer to a beacon using the administration API using either:

  • The Eddystone-UID that you chose when you registered the beacon, ideal for when you are not physically present at the beacon.
  • The currently broadcast Eddystone-EID, ideal for when you have in hand the beacon whose properties you wish to update.

Unregister a beacon

Once a beacon has been registered, there are two options for taking a beacon offline while preventing the beacon ID from being re-registered:

  • Call beacons.deactivate to temporarily remove a beacon from service. Once deactivated, the API will not return information nor attachment data for the beacon. Call beacons.activate to return the beacon to service.
  • Call beacons.decommission to take a beacon ID offline permanently. Once a beacon has been decommissioned, you will no longer be able to use the ID it was previously registered with. You can provision the beacon with a new ID, and re-register the beacon with the new ID.

If you wish to remove a beacon from the registry permanently but allow its beacon ID to be re-registered, you can call beacons.delete.