Blame - docs/dyn/proximitybeacon_v1beta1.beacons.html - platform/external/python/google-api-python-client

2015-09-11 13:55:40 -0700

[diff] [blame]

329

"name": "A String", # The name of this level.

330

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

430

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

447

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

461

"a_key": "A String",

462

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

483

484

Args:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

557

pageToken: string, A pagination token obtained from a previous request to list beacons.

558

x__xgafv: string, V1 error format.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

559

Allowed values

560

1 - v1 error format

561

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

562

563

Returns:

564

An object of the form:

565

566

{ # Response that contains list beacon results and pagination help.

Sai Cheemalapati

e833b79

2017-03-24 15:06:46 -0700

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

569

"beacons": [ # The beacons that matched the search criteria.

570

{ # Details of a beacon device.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

580

"name": "A String", # The name of this level.

581

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

681

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

698

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

712

"a_key": "A String",

713

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

722

},

723

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

724

"totalCount": "A String", # Estimate of the total number of beacons matched by the query. Higher

725

# values may be less accurate.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

<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.

</pre>

</div>

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

744

<code class="details" id="register">register(body, projectId=None, x__xgafv=None)</code>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

751

752

Args:

753

body: object, The request body. (required)

754

The object takes the form of:

755

756

{ # Details of a beacon device.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

766

"name": "A String", # The name of this level.

767

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

867

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

884

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

898

"a_key": "A String",

899

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

908

}

909

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

914

x__xgafv: string, V1 error format.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

915

Allowed values

916

1 - v1 error format

917

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

918

919

Returns:

920

An object of the form:

921

922

{ # Details of a beacon device.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

932

"name": "A String", # The name of this level.

933

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

1033

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1050

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1064

"a_key": "A String",

1065

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1078

<code class="details" id="update">update(beaconName, body, projectId=None, x__xgafv=None)</code>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1090

1091

Args:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1099

body: object, The request body. (required)

1100

The object takes the form of:

1101

1102

{ # Details of a beacon device.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1112

"name": "A String", # The name of this level.

1113

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

1213

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1230

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1244

"a_key": "A String",

1245

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1254

}

1255

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1260

x__xgafv: string, V1 error format.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1261

Allowed values

1262

1 - v1 error format

1263

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1264

1265

Returns:

1266

An object of the form:

1267

1268

{ # Details of a beacon device.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1278

"name": "A String", # The name of this level.

1279

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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):

# return r - 360.0

# return r

#

# 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)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

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

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

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`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Jon Wayne Parrott

2016-05-19 10:54:38 -0700

[diff] [blame]

1379

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1396

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1410

"a_key": "A String",

1411

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

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.

Takashi Matsuo