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)

373

#

374

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

375

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

376

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

377

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

378

},

Sai Cheemalapati

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

[diff] [blame^]

379

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

380

# the beacon is deployed. This is given when the beacon is registered or

381

# updated, not automatically detected in any way.

382

# Optional.

383

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

384

# (remotely resolved ephemeral ID) format. This information will not be

385

# populated in API responses. When submitting this data, the `advertised_id`

386

# field must contain an ID of type Eddystone-UID. Any other ID type will

387

# result in an error.

388

# Two ways of securely registering an Eddystone-EID beacon with the service

389

# are supported:

390

#

391

# 1. Perform an ECDH key exchange via this API, including a previous call

392

# to `GET /v1beta1/eidparams`. In this case the fields

393

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

394

# populated and `beacon_identity_key` should not be populated. This

395

# method ensures that only the two parties in the ECDH key exchange can

396

# compute the identity key, which becomes a secret between them.

397

# 2. Derive or obtain the beacon's identity key via other secure means

398

# (perhaps an ECDH key exchange between the beacon and a mobile device

399

# or any other secure method), and then submit the resulting identity key

400

# to the service. In this case `beacon_identity_key` field should be

401

# populated, and neither of `beacon_ecdh_public_key` nor

402

# `service_ecdh_public_key` fields should be. The security of this method

403

# depends on how securely the parties involved (in particular the

404

# bluetooth client) handle the identity key, and obviously on how

405

# securely the identity key was generated.

406

#

407

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

408

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

409

# ephemeral ID. "Nominal" because the beacon should randomize the

410

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

411

# for details. This value corresponds to a power-of-two scaler on the

412

# beacon's clock: when the scaler value is K, the beacon will begin

413

# broadcasting a new ephemeral ID on average every 2^K seconds.

414

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

415

# begun counting at this value immediately prior to transmitting this

416

# value to the resolving service. Significant delay in transmitting this

417

# value to the service risks registration or resolution failures. If a

418

# value is not provided, the default is zero.

419

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

420

# key exchange. When this field is populated, `service_ecdh_public_key`

421

# must also be populated, and `beacon_identity_key` must not be.

422

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

423

# `initial_clock_value`, and the secret key generated by the

424

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

425

# `service_ecdh_public_key`. This initial EID value will be used by the

426

# service to confirm that the key exchange process was successful.

427

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

428

# key exchange. When this field is populated, `beacon_ecdh_public_key`

429

# must also be populated, and `beacon_identity_key` must not be.

430

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

431

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

432

# populated.

Jon Wayne Parrott

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

[diff] [blame]

433

},

Sai Cheemalapati

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

[diff] [blame^]

434

"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

435

# populated when registering. It may be empty when updating a beacon

436

# record because it is ignored in updates.

437

#

438

# When registering a beacon that broadcasts Eddystone-EID, this field

439

# should contain a "stable" Eddystone-UID that identifies the beacon and

440

# links it to its attachments. The stable Eddystone-UID is only used for

441

# administering the beacon.

442

"type": "A String", # Specifies the identifier type.

443

# Required.

444

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

445

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

446

# requests, and will be so encoded (with padding) in responses. The base64

447

# encoding should be of the binary byte-stream and not any textual (such as

448

# hex) representation thereof.

449

# Required.

Takashi Matsuo

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

[diff] [blame]

450

},

Sai Cheemalapati

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

[diff] [blame^]

451

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

452

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

453

# the beacon and N is a code for the beacon's type. Possible values are

454

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

455

#

456

# This field must be left empty when registering. After reading a beacon,

457

# clients can use the name for future operations.

458

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

459

# updated, not automatically detected in any way.

460

# Optional.

461

"properties": { # Properties of the beacon device, for example battery type or firmware

462

# version.

463

# Optional.

Takashi Matsuo

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

[diff] [blame]

464

"a_key": "A String",

465

},

Sai Cheemalapati

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

[diff] [blame^]

466

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

467

# changing any of its configuration (e.g. broadcast frames, transmit power).

468

# This field provides a place to store and control access to that key.

469

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

470

# from users with write access to the given beacon. That is to say: If the

471

# user is authorized to write the beacon's confidential data in the service,

472

# the service considers them authorized to configure the beacon. Note

473

# 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^]

478

<code class="details" id="list">list(pageSize=None, projectId=None, q=None, syntax=None, pageToken=None, x__xgafv=None)</code>

479

<pre>Searches the beacon registry for beacons that match the given search

480

criteria. Only those beacons that the client has permission to list

481

will be returned.

482

483

Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2)

484

from a signed-in user with **viewer**, **Is owner** or **Can edit**

485

permissions in the Google Developers Console project.

Takashi Matsuo

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

[diff] [blame]

486

487

Args:

Sai Cheemalapati

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

[diff] [blame^]

488

pageSize: integer, The maximum number of records to return for this request, up to a

489

server-defined upper limit.

490

projectId: string, The project id to list beacons under. If not present then the project

491

credential that made the request is used as the project.

492

Optional.

493

q: string, Filter query string that supports the following field filters:

494

495

* **description:`"<string>"`**

496

For example: **description:"Room 3"**

497

Returns beacons whose description matches tokens in the string "Room 3"

498

(not necessarily that exact string).

499

The string must be double-quoted.

500

* **status:`<enum>`**

501

For example: **status:active**

502

Returns beacons whose status matches the given value. Values must be

503

one of the Beacon.Status enum values (case insensitive). Accepts

504

multiple filters which will be combined with OR logic.

505

* **stability:`<enum>`**

506

For example: **stability:mobile**

507

Returns beacons whose expected stability matches the given value.

508

Values must be one of the Beacon.Stability enum values (case

509

insensitive). Accepts multiple filters which will be combined with

510

OR logic.

511

* **place\_id:`"<string>"`**

512

For example: **place\_id:"ChIJVSZzVR8FdkgRXGmmm6SslKw="**

513

Returns beacons explicitly registered at the given place, expressed as

514

a Place ID obtained from [Google Places API](/places/place-id). Does not

515

match places inside the given place. Does not consider the beacon's

516

actual location (which may be different from its registered place).

517

Accepts multiple filters that will be combined with OR logic. The place

518

ID must be double-quoted.

519

* **registration\_time`[<|>|<=|>=]<integer>`**

520

For example: **registration\_time>=1433116800**

521

Returns beacons whose registration time matches the given filter.

522

Supports the operators: <, >, <=, and >=. Timestamp must be expressed as

523

an integer number of seconds since midnight January 1, 1970 UTC. Accepts

524

at most two filters that will be combined with AND logic, to support

525

"between" semantics. If more than two are supplied, the latter ones are

526

ignored.

527

* **lat:`<double> lng:<double> radius:<integer>`**

528

For example: **lat:51.1232343 lng:-1.093852 radius:1000**

529

Returns beacons whose registered location is within the given circle.

530

When any of these fields are given, all are required. Latitude and

531

longitude must be decimal degrees between -90.0 and 90.0 and between

532

-180.0 and 180.0 respectively. Radius must be an integer number of

533

meters between 10 and 1,000,000 (1000 km).

534

* **property:`"<string>=<string>"`**

535

For example: **property:"battery-type=CR2032"**

536

Returns beacons which have a property of the given name and value.

537

Supports multiple filters which will be combined with OR logic.

538

The entire name=value string must be double-quoted as one string.

539

* **attachment\_type:`"<string>"`**

540

For example: **attachment_type:"my-namespace/my-type"**

541

Returns beacons having at least one attachment of the given namespaced

542

type. Supports "any within this namespace" via the partial wildcard

543

syntax: "my-namespace/*". Supports multiple filters which will be

544

combined with OR logic. The string must be double-quoted.

545

* **indoor\_level:`"<string>"`**

546

For example: **indoor\_level:"1"**

547

Returns beacons which are located on the given indoor level. Accepts

548

multiple filters that will be combined with OR logic.

549

550

Multiple filters on the same field are combined with OR logic (except

551

registration_time which is combined with AND logic).

552

Multiple filters on different fields are combined with AND logic.

553

Filters should be separated by spaces.

554

555

As with any HTTP query string parameter, the whole filter expression must

556

be URL-encoded.

557

558

Example REST request:

559

`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]

560

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

561

x__xgafv: string, V1 error format.

Sai Cheemalapati

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

[diff] [blame^]

562

Allowed values

563

1 - v1 error format

564

2 - v2 error format

Takashi Matsuo

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

[diff] [blame]

565

566

Returns:

567

An object of the form:

568

569

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

570

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

571

{ # Details of a beacon device.

Sai Cheemalapati

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

[diff] [blame^]

572

"status": "A String", # Current status of the beacon.

573

# Required.

574

"description": "A String", # Free text used to identify and describe the beacon. Maximum length 140

575

# characters.

576

# Optional.

577

"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

578

# Google Maps API.

579

# Optional.

580

# useful to indicate which floor of a building a beacon is located on.

Takashi Matsuo

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

[diff] [blame]

581

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

582

},

Sai Cheemalapati

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

[diff] [blame^]

583

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

584

# This location is given when the beacon is registered or updated. It does

585

# not necessarily indicate the actual current location of the beacon.

586

# Optional.

587

# of doubles representing degrees latitude and degrees longitude. Unless

588

# specified otherwise, this must conform to the

589

# <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

590

# standard</a>. Values must be within normalized ranges.

591

#

592

# Example of normalization code in Python:

593

#

594

# def NormalizeLongitude(longitude):

595

# """Wraps decimal degrees longitude to [-180.0, 180.0]."""

596

# q, r = divmod(longitude, 360.0)

597

# if r > 180.0 or (r == 180.0 and q <= -1.0):

# return r - 360.0

# return r

#

# def NormalizeLatLng(latitude, longitude):

602

# """Wraps decimal degrees latitude and longitude to

603

# [-90.0, 90.0] and [-180.0, 180.0], respectively."""

604

# r = latitude % 360.0

605

# if r <= 90.0:

606

# return r, NormalizeLongitude(longitude)

607

# elif r >= 270.0:

608

# return r - 360, NormalizeLongitude(longitude)

609

# else:

610

# return 180 - r, NormalizeLongitude(longitude + 180.0)

611

#

612

# assert 180.0 == NormalizeLongitude(180.0)

613

# assert -180.0 == NormalizeLongitude(-180.0)

614

# assert -179.0 == NormalizeLongitude(181.0)

615

# assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)

616

# assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)

617

# assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)

618

# assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)

619

# assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)

620

# assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)

621

# assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)

622

# assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)

623

# assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)

624

# assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)

625

#

626

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

627

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

628

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

629

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

630

},

Sai Cheemalapati

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

[diff] [blame^]

631

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

632

# the beacon is deployed. This is given when the beacon is registered or

633

# updated, not automatically detected in any way.

634

# Optional.

635

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

636

# (remotely resolved ephemeral ID) format. This information will not be

637

# populated in API responses. When submitting this data, the `advertised_id`

638

# field must contain an ID of type Eddystone-UID. Any other ID type will

639

# result in an error.

640

# Two ways of securely registering an Eddystone-EID beacon with the service

641

# are supported:

642

#

643

# 1. Perform an ECDH key exchange via this API, including a previous call

644

# to `GET /v1beta1/eidparams`. In this case the fields

645

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

646

# populated and `beacon_identity_key` should not be populated. This

647

# method ensures that only the two parties in the ECDH key exchange can

648

# compute the identity key, which becomes a secret between them.

649

# 2. Derive or obtain the beacon's identity key via other secure means

650

# (perhaps an ECDH key exchange between the beacon and a mobile device

651

# or any other secure method), and then submit the resulting identity key

652

# to the service. In this case `beacon_identity_key` field should be

653

# populated, and neither of `beacon_ecdh_public_key` nor

654

# `service_ecdh_public_key` fields should be. The security of this method

655

# depends on how securely the parties involved (in particular the

656

# bluetooth client) handle the identity key, and obviously on how

657

# securely the identity key was generated.

658

#

659

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

660

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

661

# ephemeral ID. "Nominal" because the beacon should randomize the

662

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

663

# for details. This value corresponds to a power-of-two scaler on the

664

# beacon's clock: when the scaler value is K, the beacon will begin

665

# broadcasting a new ephemeral ID on average every 2^K seconds.

666

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

667

# begun counting at this value immediately prior to transmitting this

668

# value to the resolving service. Significant delay in transmitting this

669

# value to the service risks registration or resolution failures. If a

670

# value is not provided, the default is zero.

671

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

672

# key exchange. When this field is populated, `service_ecdh_public_key`

673

# must also be populated, and `beacon_identity_key` must not be.

674

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

675

# `initial_clock_value`, and the secret key generated by the

676

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

677

# `service_ecdh_public_key`. This initial EID value will be used by the

678

# service to confirm that the key exchange process was successful.

679

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

680

# key exchange. When this field is populated, `beacon_ecdh_public_key`

681

# must also be populated, and `beacon_identity_key` must not be.

682

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

683

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

684

# populated.

Jon Wayne Parrott

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

[diff] [blame]

685

},

Sai Cheemalapati

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

[diff] [blame^]

686

"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

687

# populated when registering. It may be empty when updating a beacon

688

# record because it is ignored in updates.

689

#

690

# When registering a beacon that broadcasts Eddystone-EID, this field

691

# should contain a "stable" Eddystone-UID that identifies the beacon and

692

# links it to its attachments. The stable Eddystone-UID is only used for

693

# administering the beacon.

694

"type": "A String", # Specifies the identifier type.

695

# Required.

696

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

697

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

698

# requests, and will be so encoded (with padding) in responses. The base64

699

# encoding should be of the binary byte-stream and not any textual (such as

700

# hex) representation thereof.

701

# Required.

Takashi Matsuo

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

[diff] [blame]

702

},

Sai Cheemalapati

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

[diff] [blame^]

703

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

704

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

705

# the beacon and N is a code for the beacon's type. Possible values are

706

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

707

#

708

# This field must be left empty when registering. After reading a beacon,

709

# clients can use the name for future operations.

710

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

711

# updated, not automatically detected in any way.

712

# Optional.

713

"properties": { # Properties of the beacon device, for example battery type or firmware

714

# version.

715

# Optional.

Takashi Matsuo

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

[diff] [blame]

716

"a_key": "A String",

717

},

Sai Cheemalapati

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

[diff] [blame^]

718

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

719

# changing any of its configuration (e.g. broadcast frames, transmit power).

720

# This field provides a place to store and control access to that key.

721

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

722

# from users with write access to the given beacon. That is to say: If the

723

# user is authorized to write the beacon's confidential data in the service,

724

# the service considers them authorized to configure the beacon. Note

725

# that this key grants nothing on the service, only on the beacon itself.

Takashi Matsuo

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

[diff] [blame]

726

},

727

],

Sai Cheemalapati

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

[diff] [blame^]

728

"nextPageToken": "A String", # An opaque pagination token that the client may provide in their next

729

# request to retrieve the next page of results.

730

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

731

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

737

<pre>Retrieves the next page of results.

738

739

Args:

740

previous_request: The request for the previous page. (required)

741

previous_response: The response from the request for the previous page. (required)

742

743

Returns:

744

A request object that you can call 'execute()' on to request the next

745

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]

750

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

Sai Cheemalapati

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

[diff] [blame^]

751

<pre>Registers a previously unregistered beacon given its `advertisedId`.

752

These IDs are unique within the system. An ID can be registered only once.

753

754

Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2)

755

from a signed-in user with **Is owner** or **Can edit** permissions in the

756

Google Developers Console project.

Takashi Matsuo

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

[diff] [blame]

757

758

Args:

759

body: object, The request body. (required)

760

The object takes the form of:

761

762

{ # Details of a beacon device.

Sai Cheemalapati

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

[diff] [blame^]

763

"status": "A String", # Current status of the beacon.

764

# Required.

765

"description": "A String", # Free text used to identify and describe the beacon. Maximum length 140

766

# characters.

767

# Optional.

768

"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

769

# Google Maps API.

770

# Optional.

771

# useful to indicate which floor of a building a beacon is located on.

Takashi Matsuo

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

[diff] [blame]

772

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

773

},

Sai Cheemalapati

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

[diff] [blame^]

774

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

775

# This location is given when the beacon is registered or updated. It does

776

# not necessarily indicate the actual current location of the beacon.

777

# Optional.

778

# of doubles representing degrees latitude and degrees longitude. Unless

779

# specified otherwise, this must conform to the

780

# <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

781

# standard</a>. Values must be within normalized ranges.

782

#

783

# Example of normalization code in Python:

784

#

785

# def NormalizeLongitude(longitude):

786

# """Wraps decimal degrees longitude to [-180.0, 180.0]."""

787

# q, r = divmod(longitude, 360.0)

788

# if r > 180.0 or (r == 180.0 and q <= -1.0):

# return r - 360.0

# return r

#

# def NormalizeLatLng(latitude, longitude):

793

# """Wraps decimal degrees latitude and longitude to

794

# [-90.0, 90.0] and [-180.0, 180.0], respectively."""

795

# r = latitude % 360.0

796

# if r <= 90.0:

797

# return r, NormalizeLongitude(longitude)

798

# elif r >= 270.0:

799

# return r - 360, NormalizeLongitude(longitude)

800

# else:

801

# return 180 - r, NormalizeLongitude(longitude + 180.0)

802

#

803

# assert 180.0 == NormalizeLongitude(180.0)

804

# assert -180.0 == NormalizeLongitude(-180.0)

805

# assert -179.0 == NormalizeLongitude(181.0)

806

# assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)

807

# assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)

808

# assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)

809

# assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)

810

# assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)

811

# assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)

812

# assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)

813

# assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)

814

# assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)

815

# assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)

816

#

817

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

818

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

819

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

820

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

821

},

Sai Cheemalapati

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

[diff] [blame^]

822

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

823

# the beacon is deployed. This is given when the beacon is registered or

824

# updated, not automatically detected in any way.

825

# Optional.

826

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

827

# (remotely resolved ephemeral ID) format. This information will not be

828

# populated in API responses. When submitting this data, the `advertised_id`

829

# field must contain an ID of type Eddystone-UID. Any other ID type will

830

# result in an error.

831

# Two ways of securely registering an Eddystone-EID beacon with the service

832

# are supported:

833

#

834

# 1. Perform an ECDH key exchange via this API, including a previous call

835

# to `GET /v1beta1/eidparams`. In this case the fields

836

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

837

# populated and `beacon_identity_key` should not be populated. This

838

# method ensures that only the two parties in the ECDH key exchange can

839

# compute the identity key, which becomes a secret between them.

840

# 2. Derive or obtain the beacon's identity key via other secure means

841

# (perhaps an ECDH key exchange between the beacon and a mobile device

842

# or any other secure method), and then submit the resulting identity key

843

# to the service. In this case `beacon_identity_key` field should be

844

# populated, and neither of `beacon_ecdh_public_key` nor

845

# `service_ecdh_public_key` fields should be. The security of this method

846

# depends on how securely the parties involved (in particular the

847

# bluetooth client) handle the identity key, and obviously on how

848

# securely the identity key was generated.

849

#

850

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

851

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

852

# ephemeral ID. "Nominal" because the beacon should randomize the

853

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

854

# for details. This value corresponds to a power-of-two scaler on the

855

# beacon's clock: when the scaler value is K, the beacon will begin

856

# broadcasting a new ephemeral ID on average every 2^K seconds.

857

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

858

# begun counting at this value immediately prior to transmitting this

859

# value to the resolving service. Significant delay in transmitting this

860

# value to the service risks registration or resolution failures. If a

861

# value is not provided, the default is zero.

862

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

863

# key exchange. When this field is populated, `service_ecdh_public_key`

864

# must also be populated, and `beacon_identity_key` must not be.

865

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

866

# `initial_clock_value`, and the secret key generated by the

867

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

868

# `service_ecdh_public_key`. This initial EID value will be used by the

869

# service to confirm that the key exchange process was successful.

870

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

871

# key exchange. When this field is populated, `beacon_ecdh_public_key`

872

# must also be populated, and `beacon_identity_key` must not be.

873

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

874

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

875

# populated.

Jon Wayne Parrott

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

[diff] [blame]

876

},

Sai Cheemalapati

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

[diff] [blame^]

877

"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

878

# populated when registering. It may be empty when updating a beacon

879

# record because it is ignored in updates.

880

#

881

# When registering a beacon that broadcasts Eddystone-EID, this field

882

# should contain a "stable" Eddystone-UID that identifies the beacon and

883

# links it to its attachments. The stable Eddystone-UID is only used for

884

# administering the beacon.

885

"type": "A String", # Specifies the identifier type.

886

# Required.

887

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

888

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

889

# requests, and will be so encoded (with padding) in responses. The base64

890

# encoding should be of the binary byte-stream and not any textual (such as

891

# hex) representation thereof.

892

# Required.

Takashi Matsuo

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

[diff] [blame]

893

},

Sai Cheemalapati

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

[diff] [blame^]

894

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

895

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

896

# the beacon and N is a code for the beacon's type. Possible values are

897

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

898

#

899

# This field must be left empty when registering. After reading a beacon,

900

# clients can use the name for future operations.

901

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

902

# updated, not automatically detected in any way.

903

# Optional.

904

"properties": { # Properties of the beacon device, for example battery type or firmware

905

# version.

906

# Optional.

Takashi Matsuo

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

[diff] [blame]

907

"a_key": "A String",

908

},

Sai Cheemalapati

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

[diff] [blame^]

909

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

910

# changing any of its configuration (e.g. broadcast frames, transmit power).

911

# This field provides a place to store and control access to that key.

912

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

913

# from users with write access to the given beacon. That is to say: If the

914

# user is authorized to write the beacon's confidential data in the service,

915

# the service considers them authorized to configure the beacon. Note

916

# that this key grants nothing on the service, only on the beacon itself.

Takashi Matsuo

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

[diff] [blame]

917

}

918

Sai Cheemalapati

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

[diff] [blame^]

919

projectId: string, The project id of the project the beacon will be registered to. If

920

the project id is not specified then the project making the request

921

is used.

922

Optional.

Takashi Matsuo

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

[diff] [blame]

923

x__xgafv: string, V1 error format.

Sai Cheemalapati

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

[diff] [blame^]

924

Allowed values

925

1 - v1 error format

926

2 - v2 error format

Takashi Matsuo

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

[diff] [blame]

927

928

Returns:

929

An object of the form:

930

931

{ # Details of a beacon device.

Sai Cheemalapati

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

[diff] [blame^]

932

"status": "A String", # Current status of the beacon.

933

# Required.

934

"description": "A String", # Free text used to identify and describe the beacon. Maximum length 140

935

# characters.

936

# Optional.

937

"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

938

# Google Maps API.

939

# Optional.

940

# useful to indicate which floor of a building a beacon is located on.

Takashi Matsuo

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

[diff] [blame]

941

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

942

},

Sai Cheemalapati

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

[diff] [blame^]

943

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

944

# This location is given when the beacon is registered or updated. It does

945

# not necessarily indicate the actual current location of the beacon.

946

# Optional.

947

# of doubles representing degrees latitude and degrees longitude. Unless

948

# specified otherwise, this must conform to the

949

# <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

950

# standard</a>. Values must be within normalized ranges.

951

#

952

# Example of normalization code in Python:

953

#

954

# def NormalizeLongitude(longitude):

955

# """Wraps decimal degrees longitude to [-180.0, 180.0]."""

956

# q, r = divmod(longitude, 360.0)

957

# if r > 180.0 or (r == 180.0 and q <= -1.0):

# return r - 360.0

# return r

#

# def NormalizeLatLng(latitude, longitude):

962

# """Wraps decimal degrees latitude and longitude to

963

# [-90.0, 90.0] and [-180.0, 180.0], respectively."""

964

# r = latitude % 360.0

965

# if r <= 90.0:

966

# return r, NormalizeLongitude(longitude)

967

# elif r >= 270.0:

968

# return r - 360, NormalizeLongitude(longitude)

969

# else:

970

# return 180 - r, NormalizeLongitude(longitude + 180.0)

971

#

972

# assert 180.0 == NormalizeLongitude(180.0)

973

# assert -180.0 == NormalizeLongitude(-180.0)

974

# assert -179.0 == NormalizeLongitude(181.0)

975

# assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)

976

# assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)

977

# assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)

978

# assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)

979

# assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)

980

# assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)

981

# assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)

982

# assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)

983

# assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)

984

# assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)

985

#

986

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

987

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

988

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

989

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

990

},

Sai Cheemalapati

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

[diff] [blame^]

991

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

992

# the beacon is deployed. This is given when the beacon is registered or

993

# updated, not automatically detected in any way.

994

# Optional.

995

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

996

# (remotely resolved ephemeral ID) format. This information will not be

997

# populated in API responses. When submitting this data, the `advertised_id`

998

# field must contain an ID of type Eddystone-UID. Any other ID type will

999

# result in an error.

1000

# Two ways of securely registering an Eddystone-EID beacon with the service

1001

# are supported:

1002

#

1003

# 1. Perform an ECDH key exchange via this API, including a previous call

1004

# to `GET /v1beta1/eidparams`. In this case the fields

1005

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

1006

# populated and `beacon_identity_key` should not be populated. This

1007

# method ensures that only the two parties in the ECDH key exchange can

1008

# compute the identity key, which becomes a secret between them.

1009

# 2. Derive or obtain the beacon's identity key via other secure means

1010

# (perhaps an ECDH key exchange between the beacon and a mobile device

1011

# or any other secure method), and then submit the resulting identity key

1012

# to the service. In this case `beacon_identity_key` field should be

1013

# populated, and neither of `beacon_ecdh_public_key` nor

1014

# `service_ecdh_public_key` fields should be. The security of this method

1015

# depends on how securely the parties involved (in particular the

1016

# bluetooth client) handle the identity key, and obviously on how

1017

# securely the identity key was generated.

1018

#

1019

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

1020

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

1021

# ephemeral ID. "Nominal" because the beacon should randomize the

1022

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

1023

# for details. This value corresponds to a power-of-two scaler on the

1024

# beacon's clock: when the scaler value is K, the beacon will begin

1025

# broadcasting a new ephemeral ID on average every 2^K seconds.

1026

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

1027

# begun counting at this value immediately prior to transmitting this

1028

# value to the resolving service. Significant delay in transmitting this

1029

# value to the service risks registration or resolution failures. If a

1030

# value is not provided, the default is zero.

1031

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

1032

# key exchange. When this field is populated, `service_ecdh_public_key`

1033

# must also be populated, and `beacon_identity_key` must not be.

1034

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

1035

# `initial_clock_value`, and the secret key generated by the

1036

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

1037

# `service_ecdh_public_key`. This initial EID value will be used by the

1038

# service to confirm that the key exchange process was successful.

1039

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

1040

# key exchange. When this field is populated, `beacon_ecdh_public_key`

1041

# must also be populated, and `beacon_identity_key` must not be.

1042

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

1043

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

1044

# populated.

Jon Wayne Parrott

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

[diff] [blame]

1045

},

Sai Cheemalapati

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

[diff] [blame^]

1046

"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

1047

# populated when registering. It may be empty when updating a beacon

1048

# record because it is ignored in updates.

1049

#

1050

# When registering a beacon that broadcasts Eddystone-EID, this field

1051

# should contain a "stable" Eddystone-UID that identifies the beacon and

1052

# links it to its attachments. The stable Eddystone-UID is only used for

1053

# administering the beacon.

1054

"type": "A String", # Specifies the identifier type.

1055

# Required.

1056

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

1057

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

1058

# requests, and will be so encoded (with padding) in responses. The base64

1059

# encoding should be of the binary byte-stream and not any textual (such as

1060

# hex) representation thereof.

1061

# Required.

Takashi Matsuo

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

[diff] [blame]

1062

},

Sai Cheemalapati

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

[diff] [blame^]

1063

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

1064

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

1065

# the beacon and N is a code for the beacon's type. Possible values are

1066

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

1067

#

1068

# This field must be left empty when registering. After reading a beacon,

1069

# clients can use the name for future operations.

1070

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

1071

# updated, not automatically detected in any way.

1072

# Optional.

1073

"properties": { # Properties of the beacon device, for example battery type or firmware

1074

# version.

1075

# Optional.

Takashi Matsuo

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

[diff] [blame]

1076

"a_key": "A String",

1077

},

Sai Cheemalapati

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

[diff] [blame^]

1078

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

1079

# changing any of its configuration (e.g. broadcast frames, transmit power).

1080

# This field provides a place to store and control access to that key.

1081

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

1082

# from users with write access to the given beacon. That is to say: If the

1083

# user is authorized to write the beacon's confidential data in the service,

1084

# the service considers them authorized to configure the beacon. Note

1085

# 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^]

1090

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

1091

<pre>Updates the information about the specified beacon. **Any field that you do

1092

not populate in the submitted beacon will be permanently erased**, so you

1093

should follow the "read, modify, write" pattern to avoid inadvertently

1094

destroying data.

1095

1096

Changes to the beacon status via this method will be silently ignored.

1097

To update beacon status, use the separate methods on this API for

1098

activation, deactivation, and decommissioning.

1099

Authenticate using an [OAuth access token](https://developers.google.com/identity/protocols/OAuth2)

1100

from a signed-in user with **Is owner** or **Can edit** permissions in the

1101

Google Developers Console project.

Takashi Matsuo

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

[diff] [blame]

1102

1103

Args:

Sai Cheemalapati

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

[diff] [blame^]

1104

beaconName: string, Resource name of this beacon. A beacon name has the format

1105

"beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

1106

the beacon and N is a code for the beacon's type. Possible values are

1107

`3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

1108

1109

This field must be left empty when registering. After reading a beacon,

1110

clients can use the name for future operations. (required)

Takashi Matsuo

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

[diff] [blame]

1111

body: object, The request body. (required)

1112

The object takes the form of:

1113

1114

{ # Details of a beacon device.

Sai Cheemalapati

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

[diff] [blame^]

1115

"status": "A String", # Current status of the beacon.

1116

# Required.

1117

"description": "A String", # Free text used to identify and describe the beacon. Maximum length 140

1118

# characters.

1119

# Optional.

1120

"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

1121

# Google Maps API.

1122

# Optional.

1123

# useful to indicate which floor of a building a beacon is located on.

Takashi Matsuo

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

[diff] [blame]

1124

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

1125

},

Sai Cheemalapati

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

[diff] [blame^]

1126

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

1127

# This location is given when the beacon is registered or updated. It does

1128

# not necessarily indicate the actual current location of the beacon.

1129

# Optional.

1130

# of doubles representing degrees latitude and degrees longitude. Unless

1131

# specified otherwise, this must conform to the

1132

# <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

1133

# standard</a>. Values must be within normalized ranges.

1134

#

1135

# Example of normalization code in Python:

1136

#

1137

# def NormalizeLongitude(longitude):

1138

# """Wraps decimal degrees longitude to [-180.0, 180.0]."""

1139

# q, r = divmod(longitude, 360.0)

1140

# if r > 180.0 or (r == 180.0 and q <= -1.0):

# return r - 360.0

# return r

#

# def NormalizeLatLng(latitude, longitude):

1145

# """Wraps decimal degrees latitude and longitude to

1146

# [-90.0, 90.0] and [-180.0, 180.0], respectively."""

1147

# r = latitude % 360.0

1148

# if r <= 90.0:

1149

# return r, NormalizeLongitude(longitude)

1150

# elif r >= 270.0:

1151

# return r - 360, NormalizeLongitude(longitude)

1152

# else:

1153

# return 180 - r, NormalizeLongitude(longitude + 180.0)

1154

#

1155

# assert 180.0 == NormalizeLongitude(180.0)

1156

# assert -180.0 == NormalizeLongitude(-180.0)

1157

# assert -179.0 == NormalizeLongitude(181.0)

1158

# assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)

1159

# assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)

1160

# assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)

1161

# assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)

1162

# assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)

1163

# assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)

1164

# assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)

1165

# assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)

1166

# assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)

1167

# assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)

1168

#

1169

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

1170

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

1171

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

1172

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

1173

},

Sai Cheemalapati

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

[diff] [blame^]

1174

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

1175

# the beacon is deployed. This is given when the beacon is registered or

1176

# updated, not automatically detected in any way.

1177

# Optional.

1178

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

1179

# (remotely resolved ephemeral ID) format. This information will not be

1180

# populated in API responses. When submitting this data, the `advertised_id`

1181

# field must contain an ID of type Eddystone-UID. Any other ID type will

1182

# result in an error.

1183

# Two ways of securely registering an Eddystone-EID beacon with the service

1184

# are supported:

1185

#

1186

# 1. Perform an ECDH key exchange via this API, including a previous call

1187

# to `GET /v1beta1/eidparams`. In this case the fields

1188

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

1189

# populated and `beacon_identity_key` should not be populated. This

1190

# method ensures that only the two parties in the ECDH key exchange can

1191

# compute the identity key, which becomes a secret between them.

1192

# 2. Derive or obtain the beacon's identity key via other secure means

1193

# (perhaps an ECDH key exchange between the beacon and a mobile device

1194

# or any other secure method), and then submit the resulting identity key

1195

# to the service. In this case `beacon_identity_key` field should be

1196

# populated, and neither of `beacon_ecdh_public_key` nor

1197

# `service_ecdh_public_key` fields should be. The security of this method

1198

# depends on how securely the parties involved (in particular the

1199

# bluetooth client) handle the identity key, and obviously on how

1200

# securely the identity key was generated.

1201

#

1202

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

1203

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

1204

# ephemeral ID. "Nominal" because the beacon should randomize the

1205

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

1206

# for details. This value corresponds to a power-of-two scaler on the

1207

# beacon's clock: when the scaler value is K, the beacon will begin

1208

# broadcasting a new ephemeral ID on average every 2^K seconds.

1209

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

1210

# begun counting at this value immediately prior to transmitting this

1211

# value to the resolving service. Significant delay in transmitting this

1212

# value to the service risks registration or resolution failures. If a

1213

# value is not provided, the default is zero.

1214

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

1215

# key exchange. When this field is populated, `service_ecdh_public_key`

1216

# must also be populated, and `beacon_identity_key` must not be.

1217

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

1218

# `initial_clock_value`, and the secret key generated by the

1219

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

1220

# `service_ecdh_public_key`. This initial EID value will be used by the

1221

# service to confirm that the key exchange process was successful.

1222

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

1223

# key exchange. When this field is populated, `beacon_ecdh_public_key`

1224

# must also be populated, and `beacon_identity_key` must not be.

1225

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

1226

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

1227

# populated.

Jon Wayne Parrott

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

[diff] [blame]

1228

},

Sai Cheemalapati

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

[diff] [blame^]

1229

"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

1230

# populated when registering. It may be empty when updating a beacon

1231

# record because it is ignored in updates.

1232

#

1233

# When registering a beacon that broadcasts Eddystone-EID, this field

1234

# should contain a "stable" Eddystone-UID that identifies the beacon and

1235

# links it to its attachments. The stable Eddystone-UID is only used for

1236

# administering the beacon.

1237

"type": "A String", # Specifies the identifier type.

1238

# Required.

1239

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

1240

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

1241

# requests, and will be so encoded (with padding) in responses. The base64

1242

# encoding should be of the binary byte-stream and not any textual (such as

1243

# hex) representation thereof.

1244

# Required.

Takashi Matsuo

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

[diff] [blame]

1245

},

Sai Cheemalapati

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

[diff] [blame^]

1246

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

1247

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

1248

# the beacon and N is a code for the beacon's type. Possible values are

1249

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

1250

#

1251

# This field must be left empty when registering. After reading a beacon,

1252

# clients can use the name for future operations.

1253

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

1254

# updated, not automatically detected in any way.

1255

# Optional.

1256

"properties": { # Properties of the beacon device, for example battery type or firmware

1257

# version.

1258

# Optional.

Takashi Matsuo

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

[diff] [blame]

1259

"a_key": "A String",

1260

},

Sai Cheemalapati

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

[diff] [blame^]

1261

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

1262

# changing any of its configuration (e.g. broadcast frames, transmit power).

1263

# This field provides a place to store and control access to that key.

1264

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

1265

# from users with write access to the given beacon. That is to say: If the

1266

# user is authorized to write the beacon's confidential data in the service,

1267

# the service considers them authorized to configure the beacon. Note

1268

# that this key grants nothing on the service, only on the beacon itself.

Takashi Matsuo

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

[diff] [blame]

1269

}

1270

Sai Cheemalapati

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

[diff] [blame^]

1271

projectId: string, The project id of the beacon to update. If the project id is not

1272

specified then the project making the request is used. The project id

1273

must match the project that owns the beacon.

1274

Optional.

Takashi Matsuo

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

[diff] [blame]

1275

x__xgafv: string, V1 error format.

Sai Cheemalapati

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

[diff] [blame^]

1276

Allowed values

1277

1 - v1 error format

1278

2 - v2 error format

Takashi Matsuo

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

[diff] [blame]

1279

1280

Returns:

1281

An object of the form:

1282

1283

{ # Details of a beacon device.

Sai Cheemalapati

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

[diff] [blame^]

1284

"status": "A String", # Current status of the beacon.

1285

# Required.

1286

"description": "A String", # Free text used to identify and describe the beacon. Maximum length 140

1287

# characters.

1288

# Optional.

1289

"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

1290

# Google Maps API.

1291

# Optional.

1292

# useful to indicate which floor of a building a beacon is located on.

Takashi Matsuo

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

[diff] [blame]

1293

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

1294

},

Sai Cheemalapati

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

[diff] [blame^]

1295

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

1296

# This location is given when the beacon is registered or updated. It does

1297

# not necessarily indicate the actual current location of the beacon.

1298

# Optional.

1299

# of doubles representing degrees latitude and degrees longitude. Unless

1300

# specified otherwise, this must conform to the

1301

# <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

1302

# standard</a>. Values must be within normalized ranges.

1303

#

1304

# Example of normalization code in Python:

1305

#

1306

# def NormalizeLongitude(longitude):

1307

# """Wraps decimal degrees longitude to [-180.0, 180.0]."""

1308

# q, r = divmod(longitude, 360.0)

1309

# if r > 180.0 or (r == 180.0 and q <= -1.0):

# return r - 360.0

# return r

#

# def NormalizeLatLng(latitude, longitude):

1314

# """Wraps decimal degrees latitude and longitude to

1315

# [-90.0, 90.0] and [-180.0, 180.0], respectively."""

1316

# r = latitude % 360.0

1317

# if r <= 90.0:

1318

# return r, NormalizeLongitude(longitude)

1319

# elif r >= 270.0:

1320

# return r - 360, NormalizeLongitude(longitude)

1321

# else:

1322

# return 180 - r, NormalizeLongitude(longitude + 180.0)

1323

#

1324

# assert 180.0 == NormalizeLongitude(180.0)

1325

# assert -180.0 == NormalizeLongitude(-180.0)

1326

# assert -179.0 == NormalizeLongitude(181.0)

1327

# assert (0.0, 0.0) == NormalizeLatLng(360.0, 0.0)

1328

# assert (0.0, 0.0) == NormalizeLatLng(-360.0, 0.0)

1329

# assert (85.0, 180.0) == NormalizeLatLng(95.0, 0.0)

1330

# assert (-85.0, -170.0) == NormalizeLatLng(-95.0, 10.0)

1331

# assert (90.0, 10.0) == NormalizeLatLng(90.0, 10.0)

1332

# assert (-90.0, -10.0) == NormalizeLatLng(-90.0, -10.0)

1333

# assert (0.0, -170.0) == NormalizeLatLng(-180.0, 10.0)

1334

# assert (0.0, -170.0) == NormalizeLatLng(180.0, 10.0)

1335

# assert (-90.0, 10.0) == NormalizeLatLng(270.0, 10.0)

1336

# assert (90.0, 10.0) == NormalizeLatLng(-270.0, 10.0)

1337

#

1338

# The code in logs/storage/validator/logs_validator_traits.cc treats this type

1339

# as if it were annotated as ST_LOCATION.

Takashi Matsuo

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

[diff] [blame]

1340

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

1341

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

1342

},

Sai Cheemalapati

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

[diff] [blame^]

1343

"placeId": "A String", # The [Google Places API](/places/place-id) Place ID of the place where

1344

# the beacon is deployed. This is given when the beacon is registered or

1345

# updated, not automatically detected in any way.

1346

# Optional.

1347

"ephemeralIdRegistration": { # Write-only registration parameters for beacons using Eddystone-EID format. # Write-only registration parameters for beacons using Eddystone-EID

1348

# (remotely resolved ephemeral ID) format. This information will not be

1349

# populated in API responses. When submitting this data, the `advertised_id`

1350

# field must contain an ID of type Eddystone-UID. Any other ID type will

1351

# result in an error.

1352

# Two ways of securely registering an Eddystone-EID beacon with the service

1353

# are supported:

1354

#

1355

# 1. Perform an ECDH key exchange via this API, including a previous call

1356

# to `GET /v1beta1/eidparams`. In this case the fields

1357

# `beacon_ecdh_public_key` and `service_ecdh_public_key` should be

1358

# populated and `beacon_identity_key` should not be populated. This

1359

# method ensures that only the two parties in the ECDH key exchange can

1360

# compute the identity key, which becomes a secret between them.

1361

# 2. Derive or obtain the beacon's identity key via other secure means

1362

# (perhaps an ECDH key exchange between the beacon and a mobile device

1363

# or any other secure method), and then submit the resulting identity key

1364

# to the service. In this case `beacon_identity_key` field should be

1365

# populated, and neither of `beacon_ecdh_public_key` nor

1366

# `service_ecdh_public_key` fields should be. The security of this method

1367

# depends on how securely the parties involved (in particular the

1368

# bluetooth client) handle the identity key, and obviously on how

1369

# securely the identity key was generated.

1370

#

1371

# See [the Eddystone specification](https://github.com/google/eddystone/tree/master/eddystone-eid) at GitHub.

1372

"rotationPeriodExponent": 42, # Indicates the nominal period between each rotation of the beacon's

1373

# ephemeral ID. "Nominal" because the beacon should randomize the

1374

# actual interval. See [the spec at github](https://github.com/google/eddystone/tree/master/eddystone-eid)

1375

# for details. This value corresponds to a power-of-two scaler on the

1376

# beacon's clock: when the scaler value is K, the beacon will begin

1377

# broadcasting a new ephemeral ID on average every 2^K seconds.

1378

"initialClockValue": "A String", # The initial clock value of the beacon. The beacon's clock must have

1379

# begun counting at this value immediately prior to transmitting this

1380

# value to the resolving service. Significant delay in transmitting this

1381

# value to the service risks registration or resolution failures. If a

1382

# value is not provided, the default is zero.

1383

"beaconEcdhPublicKey": "A String", # The beacon's public key used for the Elliptic curve Diffie-Hellman

1384

# key exchange. When this field is populated, `service_ecdh_public_key`

1385

# must also be populated, and `beacon_identity_key` must not be.

1386

"initialEid": "A String", # An initial ephemeral ID calculated using the clock value submitted as

1387

# `initial_clock_value`, and the secret key generated by the

1388

# Diffie-Hellman key exchange using `service_ecdh_public_key` and

1389

# `service_ecdh_public_key`. This initial EID value will be used by the

1390

# service to confirm that the key exchange process was successful.

1391

"serviceEcdhPublicKey": "A String", # The service's public key used for the Elliptic curve Diffie-Hellman

1392

# key exchange. When this field is populated, `beacon_ecdh_public_key`

1393

# must also be populated, and `beacon_identity_key` must not be.

1394

"beaconIdentityKey": "A String", # The private key of the beacon. If this field is populated,

1395

# `beacon_ecdh_public_key` and `service_ecdh_public_key` must not be

1396

# populated.

Jon Wayne Parrott

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

[diff] [blame]

1397

},

Sai Cheemalapati

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

[diff] [blame^]

1398

"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

1399

# populated when registering. It may be empty when updating a beacon

1400

# record because it is ignored in updates.

1401

#

1402

# When registering a beacon that broadcasts Eddystone-EID, this field

1403

# should contain a "stable" Eddystone-UID that identifies the beacon and

1404

# links it to its attachments. The stable Eddystone-UID is only used for

1405

# administering the beacon.

1406

"type": "A String", # Specifies the identifier type.

1407

# Required.

1408

"id": "A String", # The actual beacon identifier, as broadcast by the beacon hardware. Must be

1409

# [base64](http://tools.ietf.org/html/rfc4648#section-4) encoded in HTTP

1410

# requests, and will be so encoded (with padding) in responses. The base64

1411

# encoding should be of the binary byte-stream and not any textual (such as

1412

# hex) representation thereof.

1413

# Required.

Takashi Matsuo

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

[diff] [blame]

1414

},

Sai Cheemalapati

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

[diff] [blame^]

1415

"beaconName": "A String", # Resource name of this beacon. A beacon name has the format

1416

# "beacons/N!beaconId" where the beaconId is the base16 ID broadcast by

1417

# the beacon and N is a code for the beacon's type. Possible values are

1418

# `3` for Eddystone, `1` for iBeacon, or `5` for AltBeacon.

1419

#

1420

# This field must be left empty when registering. After reading a beacon,

1421

# clients can use the name for future operations.

1422

"expectedStability": "A String", # Expected location stability. This is set when the beacon is registered or

1423

# updated, not automatically detected in any way.

1424

# Optional.

1425

"properties": { # Properties of the beacon device, for example battery type or firmware

1426

# version.

1427

# Optional.

Takashi Matsuo

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

[diff] [blame]

1428

"a_key": "A String",

1429

},

Sai Cheemalapati

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

[diff] [blame^]

1430

"provisioningKey": "A String", # Some beacons may require a user to provide an authorization key before

1431

# changing any of its configuration (e.g. broadcast frames, transmit power).

1432

# This field provides a place to store and control access to that key.

1433

# This field is populated in responses to `GET /v1beta1/beacons/3!beaconId`

1434

# from users with write access to the given beacon. That is to say: If the

1435

# user is authorized to write the beacon's confidential data in the service,

1436

# the service considers them authorized to configure the beacon. Note

1437

# that this key grants nothing on the service, only on the beacon itself.

Takashi Matsuo