Get Started with the Proximity Beacon REST API

You can use the Proximity Beacon API to register beacons in the cloud, associate data with registered beacons as attachments, and maintain beacon registration data. This guide walks you through creating a Google Developers Console project, activating the Proximity Beacon API, and obtaining the appropriate credentials.

Every request your application sends to the Proximity Beacon API must be either authorized using OAuth 2.0, or authenticated with an API key. Requests which can modify beacon data or return administrative beacon data must be authorized using OAuth 2.0. Requests for public data (for example calls to methods like beaconinfo.getforobserved) do not require authorization, but must still be authenticated by using an API key.

Before using the Proximity Beacon API, it is helpful to understand the basics of RESTful web services and JSON representations.

Get a Google Account

To use the Google Proximity Beacon API, you need a Google Account. If you already have an account, then you're all set. You may also want to create a separate Google Account for testing purposes.

Request an OAuth 2.0 Client ID

Requests which can modify beacon data, or return administrative beacon data, must be authorized using OAuth 2.0. Follow these steps to request an OAuth 2.0 client ID for the Google Proximity Beacon API.

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one. If you are using the Nearby Messages API, be sure to use the same Google Developers Console project that the Nearby Messages API is registered under.
  3. Click Continue to enable the Google Proximity Beacon API.
  4. Click Go to credentials.
  5. Click New credentials, then select OAuth Client ID.
  6. Under Application type, select the appropriate choice for your app (Web application, Android, iOS, etc.). Select Web application to get credentials you can use with the OAuth 2.0 Playground.
  7. You will be prompted for further information based on the Application type you chose. Fill in the appropriate fields.

  8. Click Create to get your new OAuth 2.0 Client ID. The ID appears as a string of characters that looks something like this:

    780816631155-gbvyo1o7r2pn95qc4ei9d61io4uh48hl.apps.googleusercontent.com

Request a browser API key

Requests for public data (for example calls to methods like beaconinfo.getforobserved) do not require authorization, but must still be authenticated by using an API key. Follow these steps to request a browser API key for the Google Proximity Beacon API.

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one. If you are using the Nearby Messages API, be sure to use the same Google Developers Console project that the Nearby Messages API is registered under.
  3. Click Continue to enable the Google Proximity Beacon API.
  4. Click Go to credentials.
  5. Click New credentials, then select API Key.
  6. Under Create a new key select Browser key.
  7. Enter a name for the key.
  8. Under Accept request from these HTTP referrers (web sites), enter the base URL of the site from which requests will originate. You can skip this step if the key will only be used for testing.
  9. Click Create. Your new API key will appear in the list of API keys for your project.

Try the REST API in the OAuth Playground

The OAuth Playground is the easiest way to familiarize yourself with the Google Proximity Beacon API by submitting HTTP requests and observing the responses.

  1. If you have not done so already, follow these instructions to create a new Web application client ID.
  2. Go to the OAuth 2.0 Playground.
  3. Click the gear icon to open the configuration options and make the following changes:
    1. Set OAuth flow to Client-side.
    2. Check Use your own OAuth credentials.
    3. Paste in your OAuth client ID.
  4. Close the configuration options.
  5. Under Step 1 Select & authorize APIs, paste the scope for the Proximity Beacon API into the field labeled Input your own scopes: https://www.googleapis.com/auth/userlocation.beacon.registry
  6. Click Authorize APIs.
  7. Click Allow when prompted.
  8. Under Step 2 Configure request to API, paste the following URI into the Request URI field: https://proximitybeacon.googleapis.com/v1beta1/beacons
  9. Set HTTP Method to GET.
  10. Click Send the request.

  11. The response body should show a status of 200 OK, and look similar to this:

    HTTP/1.1 200 OK
Alternate-protocol: 443:quic,p=1
Content-length: 1799
X-xss-protection: 1; mode=block
Content-location: https://proximitybeacon.googleapis.com/v1beta1/beacons?q=status:active
X-content-type-options: nosniff
Transfer-encoding: chunked
Vary: Origin, X-Origin, Referer
Server: ESF
-content-encoding: gzip
Cache-control: private
Date: Fri, 04 Sep 2015 17:04:22 GMT
X-frame-options: SAMEORIGIN
Alt-svc: quic=":443"; p="1"; ma=604800
Content-type: application/json; charset=UTF-8
{
  "beacons": \[
    {
      "status": "ACTIVE",
      "description": "Dot Beacon, reporting for duty!",
      "indoorLevel": {
        "name": "1"
      },
      "latLng": {
        "latitude": 47.669377099999998,
        "longitude": -122.1966037
      },
      "placeId": "ChIJTxax6NoSkFQRWPvFXI1LypQ",
      "advertisedId": {
        "type": "EDDYSTONE",
        "id": "hZ3uYXQBwm2IsAAAAAAAyA=="
      },
      "beaconName": "beacons/0123abcd4567efgh890",
      "expectedStability": "STABLE",
      "properties": {
        "type": "Radius Dot beacon",
        "location": "Entryway"
      }
    }
  \],
  "nextPageToken": "Civ55cv//f/9zN7NnMrGzZ7LnJ6bysbJnsmZzJ3Oz8/Pz8/Pz8/Pz8/PzP/+EAMh5L1umSgzmnQxBQHmb3DvF+sxZZVNTdNeID05AgACADQaAABQAFoLCdMiAswr49SsEAE",
  "totalCount": "3"
}

  12. Visit the Proximity Beacon API reference to learn more about how to make various types of requests.

Make an authenticated request

You can make calls against beaconinfo.getforobserved to return public data associated with your beacons. You can do this using the REST client of your choice.

  1. If you don't have a browser API key, see Get Started with the Proximity Beacon REST API to find out how to obtain credentials for authorization and authentication.

  2. Open the REST client of your choice, and make a POST request using the following URL and request body (use the API key you created in the first step). Be sure to set your REST client to use the application/json content type for the request body.

    https://proximitybeacon.googleapis.com/v1beta1/beaconinfo:getforobserved?key=API_KEY

{
  "observations": \[
    {
      "advertisedId": {
          "type": "EDDYSTONE",
          "id": "YOUR-BEACON-ID"
      }
    }
  \],
  "namespacedTypes": \[
    "*"
  \],
}

  3. The response body should show a status of 200 OK, and look similar to this:

    HTTP/1.1 200 OK
Alternate-protocol: 443:quic,p=1
Content-length: 534
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Transfer-encoding: chunked
Vary: Origin, X-Origin, Referer
Server: ESF
-content-encoding: gzip
Cache-control: private
Date: Fri, 04 Sep 2015 17:54:18 GMT
X-frame-options: SAMEORIGIN
Alt-svc: quic=":443"; p="1"; ma=604800
Content-type: application/json; charset=UTF-8
{
  "beacons": \[
    {
      "attachments": \[
        {
          "data": "QmFuYW5hczoyCg==",
          "namespacedType": "psyched-silicon-89888/string"
        },
        {
          "data": "VVMtS0lSLTZUSEItMS0xMTVH",
          "namespacedType": "psyched-silicon-89888/string"
        }
      \],
      "advertisedId": {
        "type": "EDDYSTONE",
        "id": "hZ3uYYZBwm2IsAAAAAAAyA=="
      },
      "description": "Dot Beacon, reporting for duty!",
      "beaconName": "beacons/0123abcd4567efgh890"
    }
  \]
}

Next steps

To learn more about the REST API, see these pages: