Guides Reference Samples Support

Collection: beacons

Resource: Beacon

Details of a beacon device.

JSON representation 
{
  "beaconName": string,
  "advertisedId": {
    object(AdvertisedId)
  },
  "status": enum(Status),
  "placeId": string,
  "latLng": {
    object(LatLng)
  },
  "indoorLevel": {
    object(IndoorLevel)
  },
  "expectedStability": enum(Stability),
  "description": string,
  "properties": {
    string: string,
    ...
  },
  "ephemeralIdRegistration": {
    object(EphemeralIdRegistration)
  },
  "provisioningKey": string,
}
Fields
beaconName

string

Resource name of this beacon. A beacon name has the format "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by the beacon and N is a code for the beacon's type. Possible values are 3 for Eddystone, 1 for iBeacon, or 5 for AltBeacon.

This field must be left empty when registering. After reading a beacon, clients can use the name for future operations.
advertisedId

object(AdvertisedId)

The identifier of a beacon as advertised by it. This field must be populated when registering. It may be empty when updating a beacon record because it is ignored in updates.

When registering a beacon that broadcasts Eddystone-EID, this field should contain a "stable" Eddystone-UID that identifies the beacon and links it to its attachments. The stable Eddystone-UID is only used for administering the beacon.
status

enum(Status)

Current status of the beacon. Required.

placeId

string

The Google Places API Place ID of the place where the beacon is deployed. This is given when the beacon is registered or updated, not automatically detected in any way. Optional.

latLng

object(LatLng)

The location of the beacon, expressed as a latitude and longitude pair. This location is given when the beacon is registered or updated. It does not necessarily indicate the actual current location of the beacon. Optional.

indoorLevel

object(IndoorLevel)

The indoor level information for this beacon, if known. As returned by the Google Maps API. Optional.

expectedStability

enum(Stability)

Expected location stability. This is set when the beacon is registered or updated, not automatically detected in any way. Optional.

description

string

Free text used to identify and describe the beacon. Maximum length 140 characters. Optional.

properties

map (key: string, value: string)

Properties of the beacon device, for example battery type or firmware version. Optional.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
ephemeralIdRegistration

object(EphemeralIdRegistration)

Write-only registration parameters for beacons using Eddystone-EID (remotely resolved ephemeral ID) format. This information will not be populated in API responses. When submitting this data, the advertisedId field must contain an ID of type Eddystone-UID. Any other ID type will result in an error.

provisioningKey

string (bytes format)

Some beacons may require a user to provide an authorization key before changing any of its configuration (e.g. broadcast frames, transmit power). This field provides a place to store and control access to that key. This field is populated in responses to GET /v1beta1/beacons/3!beaconId from users with write access to the given beacon. That is to say: If the user is authorized to write the beacon's confidential data in the service, the service considers them authorized to configure the beacon. Note that this key grants nothing on the service, only on the beacon itself.

A base64-encoded string.

Status

Current status of the beacon.

Enums
STATUS_UNSPECIFIED Do not use this value.
ACTIVE The "normal" in-use state of a beacon.
DECOMMISSIONED Beacon should no longer be used for any purpose. This is irreversible.
INACTIVE The beacon should not be visible to mobile devices. This is reversible.

LatLng

An object representing a latitude/longitude pair. This is expressed as a pair of doubles representing degrees latitude and degrees longitude. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges.

Example of normalization code in Python:

def NormalizeLongitude(longitude):
  """Wraps decimal degrees longitude to [-180.0, 180.0]."""
  q, r = divmod(longitude, 360.0)
  if r > 180.0 or (r == 180.0 and q <= -1.0):
    return r - 360.0
  return r

def NormalizeLatLng(latitude, longitude):
  """Wraps decimal degrees latitude and longitude to
  [-90.0, 90.0] and [-180.0, 180.0], respectively."""
  r = latitude % 360.0
  if r <= 90.0:
    return r, NormalizeLongitude(longitude)
  elif r >= 270.0:
    return r - 360, NormalizeLongitude(longitude)
  else:
    return 180 - r, NormalizeLongitude(longitude + 180.0)

assert 180.0 == NormalizeLongitude(180.0)
assert -180.0 == NormalizeLongitude(-180.0)
assert -179.0 == NormalizeLongitude(181.0)
assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)
assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)
assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)
assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)
assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)
assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)
assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)
assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)
assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)
assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)
JSON representation 
{
  "latitude": number,
  "longitude": number,
}
Fields
latitude

number

The latitude in degrees. It must be in the range [-90.0, +90.0].

longitude

number

The longitude in degrees. It must be in the range [-180.0, +180.0].

IndoorLevel

Indoor level, a human-readable string as returned by Google Maps APIs, useful to indicate which floor of a building a beacon is located on.

JSON representation 
{
  "name": string,
}
Fields
name

string

The name of this level.

Stability

Expresses the expectation of a beacon's location stability.

Enums
STABILITY_UNSPECIFIED Do not use this value.
STABLE Not expected to move, for example a store's front door.
PORTABLE Usually stable but may move rarely, usually within a single place, for example a store display.
MOBILE Moves frequently, for example a personal item or food truck.
ROVING Moves continuously in service, for example a bus or train.

EphemeralIdRegistration

Write-only registration parameters for beacons using Eddystone-EID format. Two ways of securely registering an Eddystone-EID beacon with the service are supported:

  1. Perform an ECDH key exchange via this API, including a previous call to GET /v1beta1/eidparams. In this case the fields beaconEcdhPublicKey and serviceEcdhPublicKey should be populated and beaconIdentityKey should not be populated. This method ensures that only the two parties in the ECDH key exchange can compute the identity key, which becomes a secret between them.
  2. Derive or obtain the beacon's identity key via other secure means (perhaps an ECDH key exchange between the beacon and a mobile device or any other secure method), and then submit the resulting identity key to the service. In this case beaconIdentityKey field should be populated, and neither of beaconEcdhPublicKey nor serviceEcdhPublicKey fields should be. The security of this method depends on how securely the parties involved (in particular the bluetooth client) handle the identity key, and obviously on how securely the identity key was generated.

See the Eddystone specification at GitHub.

JSON representation 
{
  "beaconEcdhPublicKey": string,
  "serviceEcdhPublicKey": string,
  "beaconIdentityKey": string,
  "rotationPeriodExponent": number,
  "initialClockValue": string,
  "initialEid": string,
}
Fields
beaconEcdhPublicKey

string (bytes format)

The beacon's public key used for the Elliptic curve Diffie-Hellman key exchange. When this field is populated, serviceEcdhPublicKey must also be populated, and beaconIdentityKey must not be.

A base64-encoded string.
serviceEcdhPublicKey

string (bytes format)

The service's public key used for the Elliptic curve Diffie-Hellman key exchange. When this field is populated, beaconEcdhPublicKey must also be populated, and beaconIdentityKey must not be.

A base64-encoded string.
beaconIdentityKey

string (bytes format)

The private key of the beacon. If this field is populated, beaconEcdhPublicKey and serviceEcdhPublicKey must not be populated.

A base64-encoded string.
rotationPeriodExponent

number (uint32 format)

Indicates the nominal period between each rotation of the beacon's ephemeral ID. "Nominal" because the beacon should randomize the actual interval. See the spec at github for details. This value corresponds to a power-of-two scaler on the beacon's clock: when the scaler value is K, the beacon will begin broadcasting a new ephemeral ID on average every 2^K seconds.

initialClockValue

string

The initial clock value of the beacon. The beacon's clock must have begun counting at this value immediately prior to transmitting this value to the resolving service. Significant delay in transmitting this value to the service risks registration or resolution failures. If a value is not provided, the default is zero.

initialEid

string (bytes format)

An initial ephemeral ID calculated using the clock value submitted as initialClockValue, and the secret key generated by the Diffie-Hellman key exchange using serviceEcdhPublicKey and serviceEcdhPublicKey. This initial EID value will be used by the service to confirm that the key exchange process was successful.

A base64-encoded string.

Methods

activate

 Activates a beacon.

deactivate

 Deactivates a beacon.

decommission

 Decommissions the specified beacon in the service.

delete

 Deletes the specified beacon including all diagnostics data for the beacon as well as any attachments on the beacon (including those belonging to other projects).

get

 Returns detailed information about the specified beacon.

list

 Searches the beacon registry for beacons that match the given search criteria.

register

 Registers a previously unregistered beacon given its advertisedId.

update

 Updates the information about the specified beacon.