1 <html><body> 2 <style> 3 4 body, h1, h2, h3, div, span, p, pre, a { 5 margin: 0; 6 padding: 0; 7 border: 0; 8 font-weight: inherit; 9 font-style: inherit; 10 font-size: 100%; 11 font-family: inherit; 12 vertical-align: baseline; 13 } 14 15 body { 16 font-size: 13px; 17 padding: 1em; 18 } 19 20 h1 { 21 font-size: 26px; 22 margin-bottom: 1em; 23 } 24 25 h2 { 26 font-size: 24px; 27 margin-bottom: 1em; 28 } 29 30 h3 { 31 font-size: 20px; 32 margin-bottom: 1em; 33 margin-top: 1em; 34 } 35 36 pre, code { 37 line-height: 1.5; 38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace; 39 } 40 41 pre { 42 margin-top: 0.5em; 43 } 44 45 h1, h2, h3, p { 46 font-family: Arial, sans serif; 47 } 48 49 h1, h2, h3 { 50 border-bottom: solid #CCC 1px; 51 } 52 53 .toc_element { 54 margin-top: 0.5em; 55 } 56 57 .firstline { 58 margin-left: 2 em; 59 } 60 61 .method { 62 margin-top: 1em; 63 border: solid 1px #CCC; 64 padding: 1em; 65 background: #EEE; 66 } 67 68 .details { 69 font-weight: bold; 70 font-size: 14px; 71 } 72 73 </style> 74 75 <h1><a href="proximitybeacon_v1beta1.html">Google Proximity Beacon API</a> . <a href="proximitybeacon_v1beta1.beacons.html">beacons</a></h1> 76 <h2>Instance Methods</h2> 77 <p class="toc_element"> 78 <code><a href="proximitybeacon_v1beta1.beacons.attachments.html">attachments()</a></code> 79 </p> 80 <p class="firstline">Returns the attachments Resource.</p> 81 82 <p class="toc_element"> 83 <code><a href="proximitybeacon_v1beta1.beacons.diagnostics.html">diagnostics()</a></code> 84 </p> 85 <p class="firstline">Returns the diagnostics Resource.</p> 86 87 <p class="toc_element"> 88 <code><a href="#activate">activate(beaconName, projectId=None, x__xgafv=None)</a></code></p> 89 <p class="firstline">Activates a beacon. A beacon that is active will return information</p> 90 <p class="toc_element"> 91 <code><a href="#deactivate">deactivate(beaconName, projectId=None, x__xgafv=None)</a></code></p> 92 <p class="firstline">Deactivates a beacon. Once deactivated, the API will not return</p> 93 <p class="toc_element"> 94 <code><a href="#decommission">decommission(beaconName, projectId=None, x__xgafv=None)</a></code></p> 95 <p class="firstline">Decommissions the specified beacon in the service. This beacon will no</p> 96 <p class="toc_element"> 97 <code><a href="#delete">delete(beaconName, projectId=None, x__xgafv=None)</a></code></p> 98 <p class="firstline">Deletes the specified beacon including all diagnostics data for the beacon</p> 99 <p class="toc_element"> 100 <code><a href="#get">get(beaconName, projectId=None, x__xgafv=None)</a></code></p> 101 <p class="firstline">Returns detailed information about the specified beacon.</p> 102 <p class="toc_element"> 103 <code><a href="#list">list(pageSize=None, projectId=None, q=None, syntax=None, pageToken=None, x__xgafv=None)</a></code></p> 104 <p class="firstline">Searches the beacon registry for beacons that match the given search</p> 105 <p class="toc_element"> 106 <code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p> 107 <p class="firstline">Retrieves the next page of results.</p> 108 <p class="toc_element"> 109 <code><a href="#register">register(body, projectId=None, x__xgafv=None)</a></code></p> 110 <p class="firstline">Registers a previously unregistered beacon given its `advertisedId`.</p> 111 <p class="toc_element"> 112 <code><a href="#update">update(beaconName, body, projectId=None, x__xgafv=None)</a></code></p> 113 <p class="firstline">Updates the information about the specified beacon. **Any field that you do</p> 114 <h3>Method Details</h3> 115 <div class="method"> 116 <code class="details" id="activate">activate(beaconName, projectId=None, x__xgafv=None)</code> 117 <pre>Activates a beacon. A beacon that is active will return information 118 and attachment data when queried via `beaconinfo.getforobserved`. 119 Calling this method on an already active beacon will do nothing (but 120 will return a successful response code). 121 122 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 123 from a signed-in user with **Is owner** or **Can edit** permissions in the 124 Google Developers Console project. 125 126 Args: 127 beaconName: string, Beacon that should be activated. A beacon name has the format 128 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 129 the beacon and N is a code for the beacon's type. Possible values are 130 `3` for Eddystone-UID, `4` for Eddystone-EID, `1` for iBeacon, or `5` 131 for AltBeacon. For Eddystone-EID beacons, you may use either the 132 current EID or the beacon's "stable" UID. 133 Required. (required) 134 projectId: string, The project id of the beacon to activate. If the project id is not 135 specified then the project making the request is used. The project id 136 must match the project that owns the beacon. 137 Optional. 138 x__xgafv: string, V1 error format. 139 Allowed values 140 1 - v1 error format 141 2 - v2 error format 142 143 Returns: 144 An object of the form: 145 146 { # A generic empty message that you can re-use to avoid defining duplicated 147 # empty messages in your APIs. A typical example is to use it as the request 148 # or the response type of an API method. For instance: 149 # 150 # service Foo { 151 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); 152 # } 153 # 154 # The JSON representation for `Empty` is empty JSON object `{}`. 155 }</pre> 156 </div> 157 158 <div class="method"> 159 <code class="details" id="deactivate">deactivate(beaconName, projectId=None, x__xgafv=None)</code> 160 <pre>Deactivates a beacon. Once deactivated, the API will not return 161 information nor attachment data for the beacon when queried via 162 `beaconinfo.getforobserved`. Calling this method on an already inactive 163 beacon will do nothing (but will return a successful response code). 164 165 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 166 from a signed-in user with **Is owner** or **Can edit** permissions in the 167 Google Developers Console project. 168 169 Args: 170 beaconName: string, Beacon that should be deactivated. A beacon name has the format 171 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 172 the beacon and N is a code for the beacon's type. Possible values are 173 `3` for Eddystone-UID, `4` for Eddystone-EID, `1` for iBeacon, or `5` 174 for AltBeacon. For Eddystone-EID beacons, you may use either the 175 current EID or the beacon's "stable" UID. 176 Required. (required) 177 projectId: string, The project id of the beacon to deactivate. If the project id is not 178 specified then the project making the request is used. The project id must 179 match the project that owns the beacon. 180 Optional. 181 x__xgafv: string, V1 error format. 182 Allowed values 183 1 - v1 error format 184 2 - v2 error format 185 186 Returns: 187 An object of the form: 188 189 { # A generic empty message that you can re-use to avoid defining duplicated 190 # empty messages in your APIs. A typical example is to use it as the request 191 # or the response type of an API method. For instance: 192 # 193 # service Foo { 194 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); 195 # } 196 # 197 # The JSON representation for `Empty` is empty JSON object `{}`. 198 }</pre> 199 </div> 200 201 <div class="method"> 202 <code class="details" id="decommission">decommission(beaconName, projectId=None, x__xgafv=None)</code> 203 <pre>Decommissions the specified beacon in the service. This beacon will no 204 longer be returned from `beaconinfo.getforobserved`. This operation is 205 permanent -- you will not be able to re-register a beacon with this ID 206 again. 207 208 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 209 from a signed-in user with **Is owner** or **Can edit** permissions in the 210 Google Developers Console project. 211 212 Args: 213 beaconName: string, Beacon that should be decommissioned. A beacon name has the format 214 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 215 the beacon and N is a code for the beacon's type. Possible values are 216 `3` for Eddystone-UID, `4` for Eddystone-EID, `1` for iBeacon, or `5` 217 for AltBeacon. For Eddystone-EID beacons, you may use either the 218 current EID of the beacon's "stable" UID. 219 Required. (required) 220 projectId: string, The project id of the beacon to decommission. If the project id is not 221 specified then the project making the request is used. The project id 222 must match the project that owns the beacon. 223 Optional. 224 x__xgafv: string, V1 error format. 225 Allowed values 226 1 - v1 error format 227 2 - v2 error format 228 229 Returns: 230 An object of the form: 231 232 { # A generic empty message that you can re-use to avoid defining duplicated 233 # empty messages in your APIs. A typical example is to use it as the request 234 # or the response type of an API method. For instance: 235 # 236 # service Foo { 237 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); 238 # } 239 # 240 # The JSON representation for `Empty` is empty JSON object `{}`. 241 }</pre> 242 </div> 243 244 <div class="method"> 245 <code class="details" id="delete">delete(beaconName, projectId=None, x__xgafv=None)</code> 246 <pre>Deletes the specified beacon including all diagnostics data for the beacon 247 as well as any attachments on the beacon (including those belonging to 248 other projects). This operation cannot be undone. 249 250 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 251 from a signed-in user with **Is owner** or **Can edit** permissions in the 252 Google Developers Console project. 253 254 Args: 255 beaconName: string, Beacon that should be deleted. A beacon name has the format 256 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 257 the beacon and N is a code for the beacon's type. Possible values are 258 `3` for Eddystone-UID, `4` for Eddystone-EID, `1` for iBeacon, or `5` 259 for AltBeacon. For Eddystone-EID beacons, you may use either the 260 current EID or the beacon's "stable" UID. 261 Required. (required) 262 projectId: string, The project id of the beacon to delete. If not provided, the project 263 that is making the request is used. 264 Optional. 265 x__xgafv: string, V1 error format. 266 Allowed values 267 1 - v1 error format 268 2 - v2 error format 269 270 Returns: 271 An object of the form: 272 273 { # A generic empty message that you can re-use to avoid defining duplicated 274 # empty messages in your APIs. A typical example is to use it as the request 275 # or the response type of an API method. For instance: 276 # 277 # service Foo { 278 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); 279 # } 280 # 281 # The JSON representation for `Empty` is empty JSON object `{}`. 282 }</pre> 283 </div> 284 285 <div class="method"> 286 <code class="details" id="get">get(beaconName, projectId=None, x__xgafv=None)</code> 287 <pre>Returns detailed information about the specified beacon. 288 289 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 290 from a signed-in user with **viewer**, **Is owner** or **Can edit** 291 permissions in the Google Developers Console project. 292 293 Requests may supply an Eddystone-EID beacon name in the form: 294 `beacons/4!beaconId` where the `beaconId` is the base16 ephemeral ID 295 broadcast by the beacon. The returned `Beacon` object will contain the 296 beacon's stable Eddystone-UID. Clients not authorized to resolve the 297 beacon's ephemeral Eddystone-EID broadcast will receive an error. 298 299 Args: 300 beaconName: string, Resource name of this beacon. A beacon name has the format 301 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 302 the beacon and N is a code for the beacon's type. Possible values are 303 `3` for Eddystone-UID, `4` for Eddystone-EID, `1` for iBeacon, or `5` 304 for AltBeacon. For Eddystone-EID beacons, you may use either the 305 current EID or the beacon's "stable" UID. 306 Required. (required) 307 projectId: string, The project id of the beacon to request. If the project id is not specified 308 then the project making the request is used. The project id must match the 309 project that owns the beacon. 310 Optional. 311 x__xgafv: string, V1 error format. 312 Allowed values 313 1 - v1 error format 314 2 - v2 error format 315 316 Returns: 317 An object of the form: 318 319 { # Details of a beacon device. 320 "status": "A String", # Current status of the beacon. 321 # Required. 322 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 323 # characters. 324 # Optional. 325 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 326 # Google Maps API. 327 # Optional. 328 # useful to indicate which floor of a building a beacon is located on. 329 "name": "A String", # The name of this level. 330 }, 331 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 332 # This location is given when the beacon is registered or updated. It does 333 # not necessarily indicate the actual current location of the beacon. 334 # Optional. 335 # of doubles representing degrees latitude and degrees longitude. Unless 336 # specified otherwise, this must conform to the 337 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 338 # standard</a>. Values must be within normalized ranges. 339 # 340 # Example of normalization code in Python: 341 # 342 # def NormalizeLongitude(longitude): 343 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 344 # q, r = divmod(longitude, 360.0) 345 # if r > 180.0 or (r == 180.0 and q <= -1.0): 346 # return r - 360.0 347 # return r 348 # 349 # def NormalizeLatLng(latitude, longitude): 350 # """Wraps decimal degrees latitude and longitude to 351 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 352 # r = latitude % 360.0 353 # if r <= 90.0: 354 # return r, NormalizeLongitude(longitude) 355 # elif r >= 270.0: 356 # return r - 360, NormalizeLongitude(longitude) 357 # else: 358 # return 180 - r, NormalizeLongitude(longitude + 180.0) 359 # 360 # assert 180.0 == NormalizeLongitude(180.0) 361 # assert -180.0 == NormalizeLongitude(-180.0) 362 # assert -179.0 == NormalizeLongitude(181.0) 363 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 364 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 365 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 366 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 367 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 368 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 369 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 370 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 371 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 372 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 373 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 374 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 375 }, 376 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 377 # the beacon is deployed. This is given when the beacon is registered or 378 # updated, not automatically detected in any way. 379 # Optional. 380 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 381 # (remotely resolved ephemeral ID) format. This information will not be 382 # populated in API responses. When submitting this data, the `advertised_id` 383 # field must contain an ID of type Eddystone-UID. Any other ID type will 384 # result in an error. 385 # Two ways of securely registering an Eddystone-EID beacon with the service 386 # are supported: 387 # 388 # 1. Perform an ECDH key exchange via this API, including a previous call 389 # to `GET /v1beta1/eidparams`. In this case the fields 390 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 391 # populated and `beacon_identity_key` should not be populated. This 392 # method ensures that only the two parties in the ECDH key exchange can 393 # compute the identity key, which becomes a secret between them. 394 # 2. Derive or obtain the beacon's identity key via other secure means 395 # (perhaps an ECDH key exchange between the beacon and a mobile device 396 # or any other secure method), and then submit the resulting identity key 397 # to the service. In this case `beacon_identity_key` field should be 398 # populated, and neither of `beacon_ecdh_public_key` nor 399 # `service_ecdh_public_key` fields should be. The security of this method 400 # depends on how securely the parties involved (in particular the 401 # bluetooth client) handle the identity key, and obviously on how 402 # securely the identity key was generated. 403 # 404 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 405 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 406 # ephemeral ID. "Nominal" because the beacon should randomize the 407 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 408 # for details. This value corresponds to a power-of-two scaler on the 409 # beacon's clock: when the scaler value is K, the beacon will begin 410 # broadcasting a new ephemeral ID on average every 2^K seconds. 411 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 412 # begun counting at this value immediately prior to transmitting this 413 # value to the resolving service. Significant delay in transmitting this 414 # value to the service risks registration or resolution failures. If a 415 # value is not provided, the default is zero. 416 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 417 # key exchange. When this field is populated, `beacon_ecdh_public_key` 418 # must also be populated, and `beacon_identity_key` must not be. 419 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 420 # `initial_clock_value`, and the secret key generated by the 421 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 422 # `service_ecdh_public_key`. This initial EID value will be used by the 423 # service to confirm that the key exchange process was successful. 424 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 425 # key exchange. When this field is populated, `service_ecdh_public_key` 426 # must also be populated, and `beacon_identity_key` must not be. 427 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 428 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 429 # populated. 430 }, 431 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 432 # populated when registering. It may be empty when updating a beacon 433 # record because it is ignored in updates. 434 # 435 # When registering a beacon that broadcasts Eddystone-EID, this field 436 # should contain a "stable" Eddystone-UID that identifies the beacon and 437 # links it to its attachments. The stable Eddystone-UID is only used for 438 # administering the beacon. 439 "type": "A String", # Specifies the identifier type. 440 # Required. 441 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 442 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 443 # requests, and will be so encoded (with padding) in responses. The base64 444 # encoding should be of the binary byte-stream and not any textual (such as 445 # hex) representation thereof. 446 # Required. 447 }, 448 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 449 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 450 # the beacon and N is a code for the beacon's type. Possible values are 451 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 452 # 453 # This field must be left empty when registering. After reading a beacon, 454 # clients can use the name for future operations. 455 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 456 # updated, not automatically detected in any way. 457 # Optional. 458 "properties": { # Properties of the beacon device, for example battery type or firmware 459 # version. 460 # Optional. 461 "a_key": "A String", 462 }, 463 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 464 # changing any of its configuration (e.g. broadcast frames, transmit power). 465 # This field provides a place to store and control access to that key. 466 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 467 # from users with write access to the given beacon. That is to say: If the 468 # user is authorized to write the beacon's confidential data in the service, 469 # the service considers them authorized to configure the beacon. Note 470 # that this key grants nothing on the service, only on the beacon itself. 471 }</pre> 472 </div> 473 474 <div class="method"> 475 <code class="details" id="list">list(pageSize=None, projectId=None, q=None, syntax=None, pageToken=None, x__xgafv=None)</code> 476 <pre>Searches the beacon registry for beacons that match the given search 477 criteria. Only those beacons that the client has permission to list 478 will be returned. 479 480 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 481 from a signed-in user with **viewer**, **Is owner** or **Can edit** 482 permissions in the Google Developers Console project. 483 484 Args: 485 pageSize: integer, The maximum number of records to return for this request, up to a 486 server-defined upper limit. 487 projectId: string, The project id to list beacons under. If not present then the project 488 credential that made the request is used as the project. 489 Optional. 490 q: string, Filter query string that supports the following field filters: 491 492 * **description:`"<string>"`** 493 For example: **description:"Room 3"** 494 Returns beacons whose description matches tokens in the string "Room 3" 495 (not necessarily that exact string). 496 The string must be double-quoted. 497 * **status:`<enum>`** 498 For example: **status:active** 499 Returns beacons whose status matches the given value. Values must be 500 one of the Beacon.Status enum values (case insensitive). Accepts 501 multiple filters which will be combined with OR logic. 502 * **stability:`<enum>`** 503 For example: **stability:mobile** 504 Returns beacons whose expected stability matches the given value. 505 Values must be one of the Beacon.Stability enum values (case 506 insensitive). Accepts multiple filters which will be combined with 507 OR logic. 508 * **place\_id:`"<string>"`** 509 For example: **place\_id:"ChIJVSZzVR8FdkgRXGmmm6SslKw="** 510 Returns beacons explicitly registered at the given place, expressed as 511 a Place ID obtained from [Google Places API](/places/place-id). Does not 512 match places inside the given place. Does not consider the beacon's 513 actual location (which may be different from its registered place). 514 Accepts multiple filters that will be combined with OR logic. The place 515 ID must be double-quoted. 516 * **registration\_time`[<|>|<=|>=]<integer>`** 517 For example: **registration\_time>=1433116800** 518 Returns beacons whose registration time matches the given filter. 519 Supports the operators: <, >, <=, and >=. Timestamp must be expressed as 520 an integer number of seconds since midnight January 1, 1970 UTC. Accepts 521 at most two filters that will be combined with AND logic, to support 522 "between" semantics. If more than two are supplied, the latter ones are 523 ignored. 524 * **lat:`<double> lng:<double> radius:<integer>`** 525 For example: **lat:51.1232343 lng:-1.093852 radius:1000** 526 Returns beacons whose registered location is within the given circle. 527 When any of these fields are given, all are required. Latitude and 528 longitude must be decimal degrees between -90.0 and 90.0 and between 529 -180.0 and 180.0 respectively. Radius must be an integer number of 530 meters between 10 and 1,000,000 (1000 km). 531 * **property:`"<string>=<string>"`** 532 For example: **property:"battery-type=CR2032"** 533 Returns beacons which have a property of the given name and value. 534 Supports multiple filters which will be combined with OR logic. 535 The entire name=value string must be double-quoted as one string. 536 * **attachment\_type:`"<string>"`** 537 For example: **attachment_type:"my-namespace/my-type"** 538 Returns beacons having at least one attachment of the given namespaced 539 type. Supports "any within this namespace" via the partial wildcard 540 syntax: "my-namespace/*". Supports multiple filters which will be 541 combined with OR logic. The string must be double-quoted. 542 * **indoor\_level:`"<string>"`** 543 For example: **indoor\_level:"1"** 544 Returns beacons which are located on the given indoor level. Accepts 545 multiple filters that will be combined with OR logic. 546 547 Multiple filters on the same field are combined with OR logic (except 548 registration_time which is combined with AND logic). 549 Multiple filters on different fields are combined with AND logic. 550 Filters should be separated by spaces. 551 552 As with any HTTP query string parameter, the whole filter expression must 553 be URL-encoded. 554 555 Example REST request: 556 `GET /v1beta1/beacons?q=status:active%20lat:51.123%20lng:-1.095%20radius:1000` 557 pageToken: string, A pagination token obtained from a previous request to list beacons. 558 x__xgafv: string, V1 error format. 559 Allowed values 560 1 - v1 error format 561 2 - v2 error format 562 563 Returns: 564 An object of the form: 565 566 { # Response that contains list beacon results and pagination help. 567 "nextPageToken": "A String", # An opaque pagination token that the client may provide in their next 568 # request to retrieve the next page of results. 569 "beacons": [ # The beacons that matched the search criteria. 570 { # Details of a beacon device. 571 "status": "A String", # Current status of the beacon. 572 # Required. 573 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 574 # characters. 575 # Optional. 576 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 577 # Google Maps API. 578 # Optional. 579 # useful to indicate which floor of a building a beacon is located on. 580 "name": "A String", # The name of this level. 581 }, 582 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 583 # This location is given when the beacon is registered or updated. It does 584 # not necessarily indicate the actual current location of the beacon. 585 # Optional. 586 # of doubles representing degrees latitude and degrees longitude. Unless 587 # specified otherwise, this must conform to the 588 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 589 # standard</a>. Values must be within normalized ranges. 590 # 591 # Example of normalization code in Python: 592 # 593 # def NormalizeLongitude(longitude): 594 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 595 # q, r = divmod(longitude, 360.0) 596 # if r > 180.0 or (r == 180.0 and q <= -1.0): 597 # return r - 360.0 598 # return r 599 # 600 # def NormalizeLatLng(latitude, longitude): 601 # """Wraps decimal degrees latitude and longitude to 602 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 603 # r = latitude % 360.0 604 # if r <= 90.0: 605 # return r, NormalizeLongitude(longitude) 606 # elif r >= 270.0: 607 # return r - 360, NormalizeLongitude(longitude) 608 # else: 609 # return 180 - r, NormalizeLongitude(longitude + 180.0) 610 # 611 # assert 180.0 == NormalizeLongitude(180.0) 612 # assert -180.0 == NormalizeLongitude(-180.0) 613 # assert -179.0 == NormalizeLongitude(181.0) 614 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 615 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 616 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 617 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 618 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 619 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 620 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 621 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 622 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 623 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 624 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 625 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 626 }, 627 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 628 # the beacon is deployed. This is given when the beacon is registered or 629 # updated, not automatically detected in any way. 630 # Optional. 631 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 632 # (remotely resolved ephemeral ID) format. This information will not be 633 # populated in API responses. When submitting this data, the `advertised_id` 634 # field must contain an ID of type Eddystone-UID. Any other ID type will 635 # result in an error. 636 # Two ways of securely registering an Eddystone-EID beacon with the service 637 # are supported: 638 # 639 # 1. Perform an ECDH key exchange via this API, including a previous call 640 # to `GET /v1beta1/eidparams`. In this case the fields 641 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 642 # populated and `beacon_identity_key` should not be populated. This 643 # method ensures that only the two parties in the ECDH key exchange can 644 # compute the identity key, which becomes a secret between them. 645 # 2. Derive or obtain the beacon's identity key via other secure means 646 # (perhaps an ECDH key exchange between the beacon and a mobile device 647 # or any other secure method), and then submit the resulting identity key 648 # to the service. In this case `beacon_identity_key` field should be 649 # populated, and neither of `beacon_ecdh_public_key` nor 650 # `service_ecdh_public_key` fields should be. The security of this method 651 # depends on how securely the parties involved (in particular the 652 # bluetooth client) handle the identity key, and obviously on how 653 # securely the identity key was generated. 654 # 655 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 656 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 657 # ephemeral ID. "Nominal" because the beacon should randomize the 658 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 659 # for details. This value corresponds to a power-of-two scaler on the 660 # beacon's clock: when the scaler value is K, the beacon will begin 661 # broadcasting a new ephemeral ID on average every 2^K seconds. 662 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 663 # begun counting at this value immediately prior to transmitting this 664 # value to the resolving service. Significant delay in transmitting this 665 # value to the service risks registration or resolution failures. If a 666 # value is not provided, the default is zero. 667 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 668 # key exchange. When this field is populated, `beacon_ecdh_public_key` 669 # must also be populated, and `beacon_identity_key` must not be. 670 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 671 # `initial_clock_value`, and the secret key generated by the 672 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 673 # `service_ecdh_public_key`. This initial EID value will be used by the 674 # service to confirm that the key exchange process was successful. 675 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 676 # key exchange. When this field is populated, `service_ecdh_public_key` 677 # must also be populated, and `beacon_identity_key` must not be. 678 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 679 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 680 # populated. 681 }, 682 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 683 # populated when registering. It may be empty when updating a beacon 684 # record because it is ignored in updates. 685 # 686 # When registering a beacon that broadcasts Eddystone-EID, this field 687 # should contain a "stable" Eddystone-UID that identifies the beacon and 688 # links it to its attachments. The stable Eddystone-UID is only used for 689 # administering the beacon. 690 "type": "A String", # Specifies the identifier type. 691 # Required. 692 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 693 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 694 # requests, and will be so encoded (with padding) in responses. The base64 695 # encoding should be of the binary byte-stream and not any textual (such as 696 # hex) representation thereof. 697 # Required. 698 }, 699 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 700 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 701 # the beacon and N is a code for the beacon's type. Possible values are 702 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 703 # 704 # This field must be left empty when registering. After reading a beacon, 705 # clients can use the name for future operations. 706 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 707 # updated, not automatically detected in any way. 708 # Optional. 709 "properties": { # Properties of the beacon device, for example battery type or firmware 710 # version. 711 # Optional. 712 "a_key": "A String", 713 }, 714 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 715 # changing any of its configuration (e.g. broadcast frames, transmit power). 716 # This field provides a place to store and control access to that key. 717 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 718 # from users with write access to the given beacon. That is to say: If the 719 # user is authorized to write the beacon's confidential data in the service, 720 # the service considers them authorized to configure the beacon. Note 721 # that this key grants nothing on the service, only on the beacon itself. 722 }, 723 ], 724 "totalCount": "A String", # Estimate of the total number of beacons matched by the query. Higher 725 # values may be less accurate. 726 }</pre> 727 </div> 728 729 <div class="method"> 730 <code class="details" id="list_next">list_next(previous_request, previous_response)</code> 731 <pre>Retrieves the next page of results. 732 733 Args: 734 previous_request: The request for the previous page. (required) 735 previous_response: The response from the request for the previous page. (required) 736 737 Returns: 738 A request object that you can call 'execute()' on to request the next 739 page. Returns None if there are no more items in the collection. 740 </pre> 741 </div> 742 743 <div class="method"> 744 <code class="details" id="register">register(body, projectId=None, x__xgafv=None)</code> 745 <pre>Registers a previously unregistered beacon given its `advertisedId`. 746 These IDs are unique within the system. An ID can be registered only once. 747 748 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 749 from a signed-in user with **Is owner** or **Can edit** permissions in the 750 Google Developers Console project. 751 752 Args: 753 body: object, The request body. (required) 754 The object takes the form of: 755 756 { # Details of a beacon device. 757 "status": "A String", # Current status of the beacon. 758 # Required. 759 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 760 # characters. 761 # Optional. 762 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 763 # Google Maps API. 764 # Optional. 765 # useful to indicate which floor of a building a beacon is located on. 766 "name": "A String", # The name of this level. 767 }, 768 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 769 # This location is given when the beacon is registered or updated. It does 770 # not necessarily indicate the actual current location of the beacon. 771 # Optional. 772 # of doubles representing degrees latitude and degrees longitude. Unless 773 # specified otherwise, this must conform to the 774 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 775 # standard</a>. Values must be within normalized ranges. 776 # 777 # Example of normalization code in Python: 778 # 779 # def NormalizeLongitude(longitude): 780 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 781 # q, r = divmod(longitude, 360.0) 782 # if r > 180.0 or (r == 180.0 and q <= -1.0): 783 # return r - 360.0 784 # return r 785 # 786 # def NormalizeLatLng(latitude, longitude): 787 # """Wraps decimal degrees latitude and longitude to 788 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 789 # r = latitude % 360.0 790 # if r <= 90.0: 791 # return r, NormalizeLongitude(longitude) 792 # elif r >= 270.0: 793 # return r - 360, NormalizeLongitude(longitude) 794 # else: 795 # return 180 - r, NormalizeLongitude(longitude + 180.0) 796 # 797 # assert 180.0 == NormalizeLongitude(180.0) 798 # assert -180.0 == NormalizeLongitude(-180.0) 799 # assert -179.0 == NormalizeLongitude(181.0) 800 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 801 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 802 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 803 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 804 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 805 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 806 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 807 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 808 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 809 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 810 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 811 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 812 }, 813 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 814 # the beacon is deployed. This is given when the beacon is registered or 815 # updated, not automatically detected in any way. 816 # Optional. 817 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 818 # (remotely resolved ephemeral ID) format. This information will not be 819 # populated in API responses. When submitting this data, the `advertised_id` 820 # field must contain an ID of type Eddystone-UID. Any other ID type will 821 # result in an error. 822 # Two ways of securely registering an Eddystone-EID beacon with the service 823 # are supported: 824 # 825 # 1. Perform an ECDH key exchange via this API, including a previous call 826 # to `GET /v1beta1/eidparams`. In this case the fields 827 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 828 # populated and `beacon_identity_key` should not be populated. This 829 # method ensures that only the two parties in the ECDH key exchange can 830 # compute the identity key, which becomes a secret between them. 831 # 2. Derive or obtain the beacon's identity key via other secure means 832 # (perhaps an ECDH key exchange between the beacon and a mobile device 833 # or any other secure method), and then submit the resulting identity key 834 # to the service. In this case `beacon_identity_key` field should be 835 # populated, and neither of `beacon_ecdh_public_key` nor 836 # `service_ecdh_public_key` fields should be. The security of this method 837 # depends on how securely the parties involved (in particular the 838 # bluetooth client) handle the identity key, and obviously on how 839 # securely the identity key was generated. 840 # 841 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 842 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 843 # ephemeral ID. "Nominal" because the beacon should randomize the 844 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 845 # for details. This value corresponds to a power-of-two scaler on the 846 # beacon's clock: when the scaler value is K, the beacon will begin 847 # broadcasting a new ephemeral ID on average every 2^K seconds. 848 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 849 # begun counting at this value immediately prior to transmitting this 850 # value to the resolving service. Significant delay in transmitting this 851 # value to the service risks registration or resolution failures. If a 852 # value is not provided, the default is zero. 853 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 854 # key exchange. When this field is populated, `beacon_ecdh_public_key` 855 # must also be populated, and `beacon_identity_key` must not be. 856 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 857 # `initial_clock_value`, and the secret key generated by the 858 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 859 # `service_ecdh_public_key`. This initial EID value will be used by the 860 # service to confirm that the key exchange process was successful. 861 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 862 # key exchange. When this field is populated, `service_ecdh_public_key` 863 # must also be populated, and `beacon_identity_key` must not be. 864 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 865 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 866 # populated. 867 }, 868 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 869 # populated when registering. It may be empty when updating a beacon 870 # record because it is ignored in updates. 871 # 872 # When registering a beacon that broadcasts Eddystone-EID, this field 873 # should contain a "stable" Eddystone-UID that identifies the beacon and 874 # links it to its attachments. The stable Eddystone-UID is only used for 875 # administering the beacon. 876 "type": "A String", # Specifies the identifier type. 877 # Required. 878 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 879 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 880 # requests, and will be so encoded (with padding) in responses. The base64 881 # encoding should be of the binary byte-stream and not any textual (such as 882 # hex) representation thereof. 883 # Required. 884 }, 885 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 886 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 887 # the beacon and N is a code for the beacon's type. Possible values are 888 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 889 # 890 # This field must be left empty when registering. After reading a beacon, 891 # clients can use the name for future operations. 892 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 893 # updated, not automatically detected in any way. 894 # Optional. 895 "properties": { # Properties of the beacon device, for example battery type or firmware 896 # version. 897 # Optional. 898 "a_key": "A String", 899 }, 900 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 901 # changing any of its configuration (e.g. broadcast frames, transmit power). 902 # This field provides a place to store and control access to that key. 903 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 904 # from users with write access to the given beacon. That is to say: If the 905 # user is authorized to write the beacon's confidential data in the service, 906 # the service considers them authorized to configure the beacon. Note 907 # that this key grants nothing on the service, only on the beacon itself. 908 } 909 910 projectId: string, The project id of the project the beacon will be registered to. If 911 the project id is not specified then the project making the request 912 is used. 913 Optional. 914 x__xgafv: string, V1 error format. 915 Allowed values 916 1 - v1 error format 917 2 - v2 error format 918 919 Returns: 920 An object of the form: 921 922 { # Details of a beacon device. 923 "status": "A String", # Current status of the beacon. 924 # Required. 925 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 926 # characters. 927 # Optional. 928 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 929 # Google Maps API. 930 # Optional. 931 # useful to indicate which floor of a building a beacon is located on. 932 "name": "A String", # The name of this level. 933 }, 934 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 935 # This location is given when the beacon is registered or updated. It does 936 # not necessarily indicate the actual current location of the beacon. 937 # Optional. 938 # of doubles representing degrees latitude and degrees longitude. Unless 939 # specified otherwise, this must conform to the 940 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 941 # standard</a>. Values must be within normalized ranges. 942 # 943 # Example of normalization code in Python: 944 # 945 # def NormalizeLongitude(longitude): 946 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 947 # q, r = divmod(longitude, 360.0) 948 # if r > 180.0 or (r == 180.0 and q <= -1.0): 949 # return r - 360.0 950 # return r 951 # 952 # def NormalizeLatLng(latitude, longitude): 953 # """Wraps decimal degrees latitude and longitude to 954 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 955 # r = latitude % 360.0 956 # if r <= 90.0: 957 # return r, NormalizeLongitude(longitude) 958 # elif r >= 270.0: 959 # return r - 360, NormalizeLongitude(longitude) 960 # else: 961 # return 180 - r, NormalizeLongitude(longitude + 180.0) 962 # 963 # assert 180.0 == NormalizeLongitude(180.0) 964 # assert -180.0 == NormalizeLongitude(-180.0) 965 # assert -179.0 == NormalizeLongitude(181.0) 966 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 967 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 968 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 969 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 970 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 971 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 972 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 973 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 974 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 975 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 976 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 977 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 978 }, 979 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 980 # the beacon is deployed. This is given when the beacon is registered or 981 # updated, not automatically detected in any way. 982 # Optional. 983 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 984 # (remotely resolved ephemeral ID) format. This information will not be 985 # populated in API responses. When submitting this data, the `advertised_id` 986 # field must contain an ID of type Eddystone-UID. Any other ID type will 987 # result in an error. 988 # Two ways of securely registering an Eddystone-EID beacon with the service 989 # are supported: 990 # 991 # 1. Perform an ECDH key exchange via this API, including a previous call 992 # to `GET /v1beta1/eidparams`. In this case the fields 993 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 994 # populated and `beacon_identity_key` should not be populated. This 995 # method ensures that only the two parties in the ECDH key exchange can 996 # compute the identity key, which becomes a secret between them. 997 # 2. Derive or obtain the beacon's identity key via other secure means 998 # (perhaps an ECDH key exchange between the beacon and a mobile device 999 # or any other secure method), and then submit the resulting identity key 1000 # to the service. In this case `beacon_identity_key` field should be 1001 # populated, and neither of `beacon_ecdh_public_key` nor 1002 # `service_ecdh_public_key` fields should be. The security of this method 1003 # depends on how securely the parties involved (in particular the 1004 # bluetooth client) handle the identity key, and obviously on how 1005 # securely the identity key was generated. 1006 # 1007 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 1008 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 1009 # ephemeral ID. "Nominal" because the beacon should randomize the 1010 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 1011 # for details. This value corresponds to a power-of-two scaler on the 1012 # beacon's clock: when the scaler value is K, the beacon will begin 1013 # broadcasting a new ephemeral ID on average every 2^K seconds. 1014 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 1015 # begun counting at this value immediately prior to transmitting this 1016 # value to the resolving service. Significant delay in transmitting this 1017 # value to the service risks registration or resolution failures. If a 1018 # value is not provided, the default is zero. 1019 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 1020 # key exchange. When this field is populated, `beacon_ecdh_public_key` 1021 # must also be populated, and `beacon_identity_key` must not be. 1022 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 1023 # `initial_clock_value`, and the secret key generated by the 1024 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 1025 # `service_ecdh_public_key`. This initial EID value will be used by the 1026 # service to confirm that the key exchange process was successful. 1027 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 1028 # key exchange. When this field is populated, `service_ecdh_public_key` 1029 # must also be populated, and `beacon_identity_key` must not be. 1030 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 1031 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 1032 # populated. 1033 }, 1034 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 1035 # populated when registering. It may be empty when updating a beacon 1036 # record because it is ignored in updates. 1037 # 1038 # When registering a beacon that broadcasts Eddystone-EID, this field 1039 # should contain a "stable" Eddystone-UID that identifies the beacon and 1040 # links it to its attachments. The stable Eddystone-UID is only used for 1041 # administering the beacon. 1042 "type": "A String", # Specifies the identifier type. 1043 # Required. 1044 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 1045 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 1046 # requests, and will be so encoded (with padding) in responses. The base64 1047 # encoding should be of the binary byte-stream and not any textual (such as 1048 # hex) representation thereof. 1049 # Required. 1050 }, 1051 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 1052 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 1053 # the beacon and N is a code for the beacon's type. Possible values are 1054 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 1055 # 1056 # This field must be left empty when registering. After reading a beacon, 1057 # clients can use the name for future operations. 1058 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 1059 # updated, not automatically detected in any way. 1060 # Optional. 1061 "properties": { # Properties of the beacon device, for example battery type or firmware 1062 # version. 1063 # Optional. 1064 "a_key": "A String", 1065 }, 1066 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 1067 # changing any of its configuration (e.g. broadcast frames, transmit power). 1068 # This field provides a place to store and control access to that key. 1069 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 1070 # from users with write access to the given beacon. That is to say: If the 1071 # user is authorized to write the beacon's confidential data in the service, 1072 # the service considers them authorized to configure the beacon. Note 1073 # that this key grants nothing on the service, only on the beacon itself. 1074 }</pre> 1075 </div> 1076 1077 <div class="method"> 1078 <code class="details" id="update">update(beaconName, body, projectId=None, x__xgafv=None)</code> 1079 <pre>Updates the information about the specified beacon. **Any field that you do 1080 not populate in the submitted beacon will be permanently erased**, so you 1081 should follow the "read, modify, write" pattern to avoid inadvertently 1082 destroying data. 1083 1084 Changes to the beacon status via this method will be silently ignored. 1085 To update beacon status, use the separate methods on this API for 1086 activation, deactivation, and decommissioning. 1087 Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2) 1088 from a signed-in user with **Is owner** or **Can edit** permissions in the 1089 Google Developers Console project. 1090 1091 Args: 1092 beaconName: string, Resource name of this beacon. A beacon name has the format 1093 "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 1094 the beacon and N is a code for the beacon's type. Possible values are 1095 `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 1096 1097 This field must be left empty when registering. After reading a beacon, 1098 clients can use the name for future operations. (required) 1099 body: object, The request body. (required) 1100 The object takes the form of: 1101 1102 { # Details of a beacon device. 1103 "status": "A String", # Current status of the beacon. 1104 # Required. 1105 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 1106 # characters. 1107 # Optional. 1108 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 1109 # Google Maps API. 1110 # Optional. 1111 # useful to indicate which floor of a building a beacon is located on. 1112 "name": "A String", # The name of this level. 1113 }, 1114 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 1115 # This location is given when the beacon is registered or updated. It does 1116 # not necessarily indicate the actual current location of the beacon. 1117 # Optional. 1118 # of doubles representing degrees latitude and degrees longitude. Unless 1119 # specified otherwise, this must conform to the 1120 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 1121 # standard</a>. Values must be within normalized ranges. 1122 # 1123 # Example of normalization code in Python: 1124 # 1125 # def NormalizeLongitude(longitude): 1126 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 1127 # q, r = divmod(longitude, 360.0) 1128 # if r > 180.0 or (r == 180.0 and q <= -1.0): 1129 # return r - 360.0 1130 # return r 1131 # 1132 # def NormalizeLatLng(latitude, longitude): 1133 # """Wraps decimal degrees latitude and longitude to 1134 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 1135 # r = latitude % 360.0 1136 # if r <= 90.0: 1137 # return r, NormalizeLongitude(longitude) 1138 # elif r >= 270.0: 1139 # return r - 360, NormalizeLongitude(longitude) 1140 # else: 1141 # return 180 - r, NormalizeLongitude(longitude + 180.0) 1142 # 1143 # assert 180.0 == NormalizeLongitude(180.0) 1144 # assert -180.0 == NormalizeLongitude(-180.0) 1145 # assert -179.0 == NormalizeLongitude(181.0) 1146 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 1147 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 1148 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 1149 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 1150 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 1151 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 1152 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 1153 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 1154 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 1155 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 1156 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 1157 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 1158 }, 1159 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 1160 # the beacon is deployed. This is given when the beacon is registered or 1161 # updated, not automatically detected in any way. 1162 # Optional. 1163 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 1164 # (remotely resolved ephemeral ID) format. This information will not be 1165 # populated in API responses. When submitting this data, the `advertised_id` 1166 # field must contain an ID of type Eddystone-UID. Any other ID type will 1167 # result in an error. 1168 # Two ways of securely registering an Eddystone-EID beacon with the service 1169 # are supported: 1170 # 1171 # 1. Perform an ECDH key exchange via this API, including a previous call 1172 # to `GET /v1beta1/eidparams`. In this case the fields 1173 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 1174 # populated and `beacon_identity_key` should not be populated. This 1175 # method ensures that only the two parties in the ECDH key exchange can 1176 # compute the identity key, which becomes a secret between them. 1177 # 2. Derive or obtain the beacon's identity key via other secure means 1178 # (perhaps an ECDH key exchange between the beacon and a mobile device 1179 # or any other secure method), and then submit the resulting identity key 1180 # to the service. In this case `beacon_identity_key` field should be 1181 # populated, and neither of `beacon_ecdh_public_key` nor 1182 # `service_ecdh_public_key` fields should be. The security of this method 1183 # depends on how securely the parties involved (in particular the 1184 # bluetooth client) handle the identity key, and obviously on how 1185 # securely the identity key was generated. 1186 # 1187 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 1188 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 1189 # ephemeral ID. "Nominal" because the beacon should randomize the 1190 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 1191 # for details. This value corresponds to a power-of-two scaler on the 1192 # beacon's clock: when the scaler value is K, the beacon will begin 1193 # broadcasting a new ephemeral ID on average every 2^K seconds. 1194 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 1195 # begun counting at this value immediately prior to transmitting this 1196 # value to the resolving service. Significant delay in transmitting this 1197 # value to the service risks registration or resolution failures. If a 1198 # value is not provided, the default is zero. 1199 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 1200 # key exchange. When this field is populated, `beacon_ecdh_public_key` 1201 # must also be populated, and `beacon_identity_key` must not be. 1202 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 1203 # `initial_clock_value`, and the secret key generated by the 1204 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 1205 # `service_ecdh_public_key`. This initial EID value will be used by the 1206 # service to confirm that the key exchange process was successful. 1207 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 1208 # key exchange. When this field is populated, `service_ecdh_public_key` 1209 # must also be populated, and `beacon_identity_key` must not be. 1210 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 1211 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 1212 # populated. 1213 }, 1214 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 1215 # populated when registering. It may be empty when updating a beacon 1216 # record because it is ignored in updates. 1217 # 1218 # When registering a beacon that broadcasts Eddystone-EID, this field 1219 # should contain a "stable" Eddystone-UID that identifies the beacon and 1220 # links it to its attachments. The stable Eddystone-UID is only used for 1221 # administering the beacon. 1222 "type": "A String", # Specifies the identifier type. 1223 # Required. 1224 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 1225 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 1226 # requests, and will be so encoded (with padding) in responses. The base64 1227 # encoding should be of the binary byte-stream and not any textual (such as 1228 # hex) representation thereof. 1229 # Required. 1230 }, 1231 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 1232 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 1233 # the beacon and N is a code for the beacon's type. Possible values are 1234 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 1235 # 1236 # This field must be left empty when registering. After reading a beacon, 1237 # clients can use the name for future operations. 1238 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 1239 # updated, not automatically detected in any way. 1240 # Optional. 1241 "properties": { # Properties of the beacon device, for example battery type or firmware 1242 # version. 1243 # Optional. 1244 "a_key": "A String", 1245 }, 1246 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 1247 # changing any of its configuration (e.g. broadcast frames, transmit power). 1248 # This field provides a place to store and control access to that key. 1249 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 1250 # from users with write access to the given beacon. That is to say: If the 1251 # user is authorized to write the beacon's confidential data in the service, 1252 # the service considers them authorized to configure the beacon. Note 1253 # that this key grants nothing on the service, only on the beacon itself. 1254 } 1255 1256 projectId: string, The project id of the beacon to update. If the project id is not 1257 specified then the project making the request is used. The project id 1258 must match the project that owns the beacon. 1259 Optional. 1260 x__xgafv: string, V1 error format. 1261 Allowed values 1262 1 - v1 error format 1263 2 - v2 error format 1264 1265 Returns: 1266 An object of the form: 1267 1268 { # Details of a beacon device. 1269 "status": "A String", # Current status of the beacon. 1270 # Required. 1271 "description": "A String", # Free text used to identify and describe the beacon. Maximum length 140 1272 # characters. 1273 # Optional. 1274 "indoorLevel": { # Indoor level, a human-readable string as returned by Google Maps APIs, # The indoor level information for this beacon, if known. As returned by the 1275 # Google Maps API. 1276 # Optional. 1277 # useful to indicate which floor of a building a beacon is located on. 1278 "name": "A String", # The name of this level. 1279 }, 1280 "latLng": { # An object representing a latitude/longitude pair. This is expressed as a pair # The location of the beacon, expressed as a latitude and longitude pair. 1281 # This location is given when the beacon is registered or updated. It does 1282 # not necessarily indicate the actual current location of the beacon. 1283 # Optional. 1284 # of doubles representing degrees latitude and degrees longitude. Unless 1285 # specified otherwise, this must conform to the 1286 # <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84 1287 # standard</a>. Values must be within normalized ranges. 1288 # 1289 # Example of normalization code in Python: 1290 # 1291 # def NormalizeLongitude(longitude): 1292 # """Wraps decimal degrees longitude to [-180.0, 180.0].""" 1293 # q, r = divmod(longitude, 360.0) 1294 # if r > 180.0 or (r == 180.0 and q <= -1.0): 1295 # return r - 360.0 1296 # return r 1297 # 1298 # def NormalizeLatLng(latitude, longitude): 1299 # """Wraps decimal degrees latitude and longitude to 1300 # [-90.0, 90.0] and [-180.0, 180.0], respectively.""" 1301 # r = latitude % 360.0 1302 # if r <= 90.0: 1303 # return r, NormalizeLongitude(longitude) 1304 # elif r >= 270.0: 1305 # return r - 360, NormalizeLongitude(longitude) 1306 # else: 1307 # return 180 - r, NormalizeLongitude(longitude + 180.0) 1308 # 1309 # assert 180.0 == NormalizeLongitude(180.0) 1310 # assert -180.0 == NormalizeLongitude(-180.0) 1311 # assert -179.0 == NormalizeLongitude(181.0) 1312 # assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0) 1313 # assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0) 1314 # assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0) 1315 # assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0) 1316 # assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0) 1317 # assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0) 1318 # assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0) 1319 # assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0) 1320 # assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0) 1321 # assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0) 1322 "latitude": 3.14, # The latitude in degrees. It must be in the range [-90.0, +90.0]. 1323 "longitude": 3.14, # The longitude in degrees. It must be in the range [-180.0, +180.0]. 1324 }, 1325 "placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where 1326 # the beacon is deployed. This is given when the beacon is registered or 1327 # updated, not automatically detected in any way. 1328 # Optional. 1329 "ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID 1330 # (remotely resolved ephemeral ID) format. This information will not be 1331 # populated in API responses. When submitting this data, the `advertised_id` 1332 # field must contain an ID of type Eddystone-UID. Any other ID type will 1333 # result in an error. 1334 # Two ways of securely registering an Eddystone-EID beacon with the service 1335 # are supported: 1336 # 1337 # 1. Perform an ECDH key exchange via this API, including a previous call 1338 # to `GET /v1beta1/eidparams`. In this case the fields 1339 # `beacon_ecdh_public_key` and `service_ecdh_public_key` should be 1340 # populated and `beacon_identity_key` should not be populated. This 1341 # method ensures that only the two parties in the ECDH key exchange can 1342 # compute the identity key, which becomes a secret between them. 1343 # 2. Derive or obtain the beacon's identity key via other secure means 1344 # (perhaps an ECDH key exchange between the beacon and a mobile device 1345 # or any other secure method), and then submit the resulting identity key 1346 # to the service. In this case `beacon_identity_key` field should be 1347 # populated, and neither of `beacon_ecdh_public_key` nor 1348 # `service_ecdh_public_key` fields should be. The security of this method 1349 # depends on how securely the parties involved (in particular the 1350 # bluetooth client) handle the identity key, and obviously on how 1351 # securely the identity key was generated. 1352 # 1353 # See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub. 1354 "rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's 1355 # ephemeral ID. "Nominal" because the beacon should randomize the 1356 # actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid) 1357 # for details. This value corresponds to a power-of-two scaler on the 1358 # beacon's clock: when the scaler value is K, the beacon will begin 1359 # broadcasting a new ephemeral ID on average every 2^K seconds. 1360 "initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have 1361 # begun counting at this value immediately prior to transmitting this 1362 # value to the resolving service. Significant delay in transmitting this 1363 # value to the service risks registration or resolution failures. If a 1364 # value is not provided, the default is zero. 1365 "serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman 1366 # key exchange. When this field is populated, `beacon_ecdh_public_key` 1367 # must also be populated, and `beacon_identity_key` must not be. 1368 "initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as 1369 # `initial_clock_value`, and the secret key generated by the 1370 # Diffie-Hellman key exchange using `service_ecdh_public_key` and 1371 # `service_ecdh_public_key`. This initial EID value will be used by the 1372 # service to confirm that the key exchange process was successful. 1373 "beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman 1374 # key exchange. When this field is populated, `service_ecdh_public_key` 1375 # must also be populated, and `beacon_identity_key` must not be. 1376 "beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated, 1377 # `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be 1378 # populated. 1379 }, 1380 "advertisedId": { # Defines a unique identifier of a beacon as broadcast by the device. # The identifier of a beacon as advertised by it. This field must be 1381 # populated when registering. It may be empty when updating a beacon 1382 # record because it is ignored in updates. 1383 # 1384 # When registering a beacon that broadcasts Eddystone-EID, this field 1385 # should contain a "stable" Eddystone-UID that identifies the beacon and 1386 # links it to its attachments. The stable Eddystone-UID is only used for 1387 # administering the beacon. 1388 "type": "A String", # Specifies the identifier type. 1389 # Required. 1390 "id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be 1391 # [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP 1392 # requests, and will be so encoded (with padding) in responses. The base64 1393 # encoding should be of the binary byte-stream and not any textual (such as 1394 # hex) representation thereof. 1395 # Required. 1396 }, 1397 "beaconName": "A String", # Resource name of this beacon. A beacon name has the format 1398 # "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by 1399 # the beacon and N is a code for the beacon's type. Possible values are 1400 # `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon. 1401 # 1402 # This field must be left empty when registering. After reading a beacon, 1403 # clients can use the name for future operations. 1404 "expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or 1405 # updated, not automatically detected in any way. 1406 # Optional. 1407 "properties": { # Properties of the beacon device, for example battery type or firmware 1408 # version. 1409 # Optional. 1410 "a_key": "A String", 1411 }, 1412 "provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before 1413 # changing any of its configuration (e.g. broadcast frames, transmit power). 1414 # This field provides a place to store and control access to that key. 1415 # This field is populated in responses to `GET /v1beta1/beacons/3!beaconId` 1416 # from users with write access to the given beacon. That is to say: If the 1417 # user is authorized to write the beacon's confidential data in the service, 1418 # the service considers them authorized to configure the beacon. Note 1419 # that this key grants nothing on the service, only on the beacon itself. 1420 }</pre> 1421 </div> 1422 1423 </body></html>
