Using the Google Spectrum Database API

Before you use the Google Spectrum Database API, there are a few things to do (if you haven't done them already). It's also important to understand the format of Google Spectrum Database API JSON-RPC requests and responses.

Contents

Get a Google Account

You need a Google Account in order to create a project in the Google Developers Console. If you already have an account, then you're all set.

Create a project

Go to the Google Developers Console. Click Create Project, enter a name, and click Create.

Get an API key

An API key is required to authenticate your request. It should be used wherever the key parameter appears below.

  1. Open the Credentials page.
  2. This API supports two types of credentials. Create whichever credentials are appropriate for your project:
    • OAuth: Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

      To create an OAuth 2.0 token, click Create new Client ID, provide the required information where requested, and click Create Client ID.

      You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

      Web applications

      A web application is accessed by web browsers over a network.

      • Applications that use JavaScript to access the Google Spectrum Database API must specify authorized JavaScript origins. The origins identify the domains from which your application can send API requests.
      • Applications that use languages and frameworks like PHP, Java, Python, Ruby, and .NET must specify authorized redirect URIs. The redirect URIs are the endpoints to which the OAuth 2.0 server can send responses.

      Service accounts

      A service account is used in an application that calls APIs on behalf of an application that does not access user information. This type of application needs to prove its own identity, but it does not need a user to authorize requests. The Google Accounts documentation contains more details about service accounts.

      Installed applications

      An installed application runs on a desktop computer or handheld device. You can create OAuth 2.0 credentials for Android, Chrome, iOS, and other installed applications.

      Android

      You need to specify your Android app's package name and SHA1 fingerprint.

      1. In the Package name field, enter your Android app's package name.
      2. In a terminal, run the Keytool utility to get the SHA1 fingerprint for your digitally signed .apk file's public certificate.
        keytool -exportcert -alias androiddebugkey -keystore path-to-debug-or-production-keystore -list -v

        The Keytool prints the fingerprint to the shell. For example:

        $ keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v
        Enter keystore password: Type "android" if using debug.keystore
        Alias name: androiddebugkey
        Creation date: Aug 27, 2012
        Entry type: PrivateKeyEntry
        Certificate chain length: 1
        Certificate[1]:
        Owner: CN=Android Debug, O=Android, C=US
        Issuer: CN=Android Debug, O=Android, C=US
        Serial number: 503bd581
        Valid from: Mon Aug 27 13:16:01 PDT 2012 until: Wed Aug 20 13:16:01 PDT 2042
        Certificate fingerprints:
           MD5:  1B:2B:2D:37:E1:CE:06:8B:A0:F0:73:05:3C:A3:63:DD
           SHA1: D8:AA:43:97:59:EE:C5:95:26:6A:07:EE:1C:37:8E:F4:F0:C8:05:C8
           SHA256: F3:6F:98:51:9A:DF:C3:15:4E:48:4B:0F:91:E3:3C:6A:A0:97:DC:0A:3F:B2:D2:E1:FE:23:57:F5:EB:AC:13:30
           Signature algorithm name: SHA1withRSA
           Version: 3

        Copy the SHA1 fingerprint, which is highlighted in the example above.

      3. Paste the SHA1 fingerprint into the form where requested.
      4. Click Create.

      Chrome application

      You need to specify the Application ID for your Chrome app or extension. Use the Google Chrome Identity API to obtain that ID.

    • iOS

      You need to specify the app's Bundle ID and App Store ID.

      • The application's Bundle ID is the bundle identifier as listed in the app's .plist file. For example: com.example.myapp.
      • The application's App Store ID is in the app's iTunes URL so long as the app was published in the Apple iTunes App Store. For example, in the app URL http://itunes.apple.com/us/app/google+/id447119634, the App Store ID is 447119634.

      Other

      The Developers Console does not require any additional information to create OAuth 2.0 credentials for other types of installed applications.

    • Public API access: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.

      The API supports several types of API keys. If the key type that you need does not already exist, create an API key by selecting Create New Key and then selecting the appropriate key type. Then enter the additional data for that key type and click Create.

      Server keys

      Create and use a server key if your application runs on a server. Do not use this key outside of your server code. For example, do not embed it in a web page. To prevent quota theft, restrict your key so that requests are only allowed from your servers' source IP addresses.

      Browser keys

      Create and use a browser key if your application runs on a client, such as a web browser. To prevent your key from being used on unauthorized sites, only allow referrals from domains you administer.

      iOS keys

      Create and use an iOS key if your application runs on iOS devices. Google verifies that each request originates from an iOS application that matches one of the bundle identifiers you specify. An app's .plist file contains its bundle identifier. Example: com.example.MyApp

      Android keys

      Create and use an Android key if your application runs on Android devices. To do so, you need to specify the SHA1 fingerprints and package names of the application using that key.

      1. In the Package name field, enter your Android app's package name.
      2. In a terminal, run the Keytool utility to get the SHA1 fingerprint for your digitally signed .apk file's public certificate.
        keytool -exportcert -alias androiddebugkey -keystore path-to-debug-or-production-keystore -list -v

        The Keytool prints the fingerprint to the shell. For example:

        $ keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v
        Enter keystore password: Type "android" if using debug.keystore
        Alias name: androiddebugkey
        Creation date: Aug 27, 2012
        Entry type: PrivateKeyEntry
        Certificate chain length: 1
        Certificate[1]:
        Owner: CN=Android Debug, O=Android, C=US
        Issuer: CN=Android Debug, O=Android, C=US
        Serial number: 503bd581
        Valid from: Mon Aug 27 13:16:01 PDT 2012 until: Wed Aug 20 13:16:01 PDT 2042
        Certificate fingerprints:
           MD5:  1B:2B:2D:37:E1:CE:06:8B:A0:F0:73:05:3C:A3:63:DD
           SHA1: D8:AA:43:97:59:EE:C5:95:26:6A:07:EE:1C:37:8E:F4:F0:C8:05:C8
           SHA256: F3:6F:98:51:9A:DF:C3:15:4E:48:4B:0F:91:E3:3C:6A:A0:97:DC:0A:3F:B2:D2:E1:FE:23:57:F5:EB:AC:13:30
           Signature algorithm name: SHA1withRSA
           Version: 3

        Copy the SHA1 fingerprint, which is highlighted in the example above.

      3. Paste the SHA1 fingerprint into the form where requested.
      4. Click Create.

To keep your API keys secure, follow the best practices for securely using API keys.

Required field: FCC ID

Any request to the database from a geolocation inside the US jurisdiction must include an authorized FCC ID in the deviceDesc.fccId field. Typically, these are assigned during the certification process.

Google Spectrum Database API JSON-RPC requests

The Google Spectrum Database API uses JSON-RPC calls to make requests of the database as specified by the PAWS protocol. Required extensions to the protocol are detailed below:

  1. Your code must provide your project's API key as the key parameter.
  2. Your code must provide an apiVersion in the JSON-RPC envelope (typically v1explorer, but see more about API modes).

To see where and how to specify these fields, examine the structure and example below.

    {
      "jsonrpc": "2.0",
      "method": string, // Method names begin with the prefix "spectrum.paws."
                        // Examples: "spectrum.paws.init", "spectrum.paws.getSpectrum"
      "apiVersion": "v1explorer",
      "params": {
          // Request method parameters go here—see the API Reference.
          "key": string // Your API key goes here at the end of your method parameters.
      },
      "id": string // A user-defined ID that will be answered back in the response.
    }

Example: Google Spectrum Database JSON-RPC init request:

    {
      "jsonrpc": "2.0",
      "method": "spectrum.paws.init",
      "apiVersion": "v1explorer",
      "params": {
        "type": "INIT_REQ",
        "version": "1.0",
        "deviceDesc": {
          "serialNumber": "your_serial_number",
          "fccId": "your_FCC_ID",
          // ...
        },
        "location": {
          "point": {
            "center": {"latitude": 37.0, "longitude": -101.3}
          }
        }
        "key": "your_API_key"
      },
      "id": "any_string"
    }

Google Spectrum Database API JSON-RPC responses

There are two forms of the Google Spectrum Database API JSON-RPC response:

  1. Non-error response (see the JSON-RPC specification's section on Response Object for additional details):
      {
        "jsonrpc": "2.0",
        "result": {
            // The JSON response object associated with the method—see the API Reference.
        },
        "id": string // The user-defined ID that was sent with the request.
      }
      
  2. Error response:
      {
        "jsonrpc": "2.0",
        "error": {
          "code": integer,
          "message": string, // See the Error table below.
          "data": object
        },
        "id": string // The user-defined ID that was sent with the request.
       }
      

    In addition to the error codes specified for the JSON-RPC Error Object, the Google Spectrum Database API responds with other codes in certain circumstances. The following table describes those error codes and messages, and their meanings:

    Error CodeError MessageMeaning
    -101 VERSION The database does not support the specified version of the message.
    -102 UNSUPPORTED The database does not support the device. For example, it does not support the regulatory domain specified in the request.
    -103 UNIMPLEMENTED The database does not implement the optional request or optional feature.
    -104 OUTSIDE_COVERAGE The specified geolocation is outside the coverage area of the database.
    -105 DATABASE_CHANGE The database has changed its URI.
    -201 REQUIRED A required parameter is missing.
    -202 INVALID_VALUE A parameter value is invalid in some way.
    -301 UNAUTHORIZED The device is not authorized to use the database.
    -302 NOT_REGISTERED Device registration required, but the device is not registered.
    -32000 INTERNAL_DATABASE_ERROR The request failed due to an internal error in the database.
    400 Bad Request The request was invalid for some other reason. For example, the API key was invalid.
    403 Daily Limit Exceeded (or similar) The number of queries has exceeded the quota allocated to the project associated with the API key. This may also be triggered if the API key wasn't present in the request.

Try out Google Spectrum Database

You can run the following curl command to send a Google Spectrum Database API JSON-RPC getSpectrum request. Note: Make sure to insert your API key in the key field, below.

curl -XPOST https://www.googleapis.com/rpc -H "Content-Type: application/json" --data '{
  "jsonrpc": "2.0",
  "method": "spectrum.paws.getSpectrum",
  "apiVersion": "v1explorer",
  "params": {
    "type": "AVAIL_SPECTRUM_REQ",
    "version": "1.0",
    "deviceDesc": { "serialNumber": "your_serial_number", "fccId": "TEST", "fccTvbdDeviceType": "MODE_1" },
    "location": { "point": { "center": {"latitude": 42.0986, "longitude": -75.9183} } },
    "antenna": { "height": 30.0, "heightType": "AGL" },
    "owner": { "owner": { } },
    "capabilities": { "frequencyRanges": [{ "startHz": 800000000, "stopHz": 850000000 }, { "startHz": 900000000, "stopHz": 950000000 }] },
    "key": "your_API_key"
  },
  "id": "any_string"
}'

Here is the Google Spectrum Database JSON-RPC response to the above getSpectrum request. It lists available spectrum for the device based on the timestamp of the request and the device's location:

{
 "jsonrpc": "2.0",
 "id": "any_string",
 "result": {
  "type": "AVAIL_SPECTRUM_RESP",
  "version": "1.0",
  "timestamp": "2013-08-31T03:28:08Z",
  "deviceDesc": {
   "serialNumber": "your_serial_number",
   "fccId": "TEST",
   "fccTvbdDeviceType": "MODE_1"
  },
  "spectrumSchedules": [
   {
    "eventTime": {
     "startTime": "2013-08-31T03:28:08Z",
     "stopTime": "2013-09-02T03:28:08Z"
    },
    "spectra": [
     {
      "bandwidth": 6000000.0,
      "frequencyRanges": [
       {
        "startHz": 5.4E7,
        "stopHz": 5.12E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 5.12E8,
        "stopHz": 5.72E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 5.72E8,
        "stopHz": 5.84E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 5.84E8,
        "stopHz": 5.9E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 5.9E8,
        "stopHz": 5.96E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 5.96E8,
        "stopHz": 6.02E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 6.02E8,
        "stopHz": 6.2E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 6.2E8,
        "stopHz": 6.32E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 6.32E8,
        "stopHz": 6.44E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 6.44E8,
        "stopHz": 6.5E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 6.5E8,
        "stopHz": 6.62E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 6.62E8,
        "stopHz": 6.86E8,
        "maxPowerDBm": 15.99999928972511
       },
       {
        "startHz": 6.86E8,
        "stopHz": 6.92E8,
        "maxPowerDBm": -56.799999947335436
       },
       {
        "startHz": 6.92E8,
        "stopHz": 6.98E8,
        "maxPowerDBm": 15.99999928972511
       }
      ]
     }
    ]
   }
  ],
  "needsSpectrumReport": false,
  "rulesetInfo": {
   "authority": "US",
   "maxLocationChange": 100.0,
   "maxPollingSecs": 86400,
   "rulesetIds": [
    "FccTvBandWhiteSpace-2010"
   ]
  }
 }
}

Questions?

If you have further questions, please join the user community at https://groups.google.com/d/forum/google-spectrum-db-discuss.