Get Started

One way to quickly get started with the Surveys API is to use the OAuth 2.0 Playground. This will allow you to connect to the API, create a survey, and see a list of your current surveys.

Before exploring the Surveys API, you will need to have a Google Account and activate the Surveys API.

Create a Google Account

To begin, you will need a Google Account. You can create a new account solely for development purposes.

Activate the Surveys API

To activate the Surveys API:

  1. Open the Google Developers Console.
  2. Create a new project using the drop-down menu at the top left of the page. For our examples, you can create a project called "Google Surveys Example".
  3. From the Use Google APIs card near the middle of the page, click Enable and Manage APIs.
  4. In the search bar that appears, type Surveys API then click Surveys API when it appears.
  5. Click Enable.

You've now enabled the Surveys API. Continue on to query the Surveys API with the OAuth 2.0 Playground.

Set up credentials

Before you can use the OAuth 2.0 Playground, you'll need to set up authentication:

  1. Visit the Credentials Tab of the API Manager in the Developers Console.
  2. Verify that your sample project is the active project, using the drop-down list at the top left of the page.
  3. Click the Create Credentials drop-down button to expand the selection. Click OAuth client ID on the drop-down list.
  4. Next, you will be asked to select the application type. For working with the OAuth2 playground, select Web Application. In the Authorized Javascript origins field, enter:

    https://developers.google.com

    For Authorized redirect URIs, enter:

    https://developers.google.com/oauthplayground

  5. Click Create. You will now be presented with a dialog window that shows the Client ID and Client Secret. You will need these to connect to the OAuth Playground in the next step.

Trying it out

To use the OAuth 2.0 Playground to access the Surveys API:

  1. Visit the OAuth 2.0 Playground
  2. Click the Gear button in the top right corner of the screen. This opens the OAuth 2.0 configuration dialog box.
  3. Check the Use your own OAuth credentials check box.
  4. You will now see text boxes for entering your OAuth client ID and OAuth client secret. Use the values from the Developer Console that were created in the last step. This will add your authentication information into the headers of any requests you make.
  5. Click Close.

Set scopes

Now that you've entered your authentication information, the next step is to set the scopes.

  1. In the text box labeled Input your own scopes, type:

    https://www.googleapis.com/auth/consumersurveys

    type one space, then enter the following URL:

    https://www.googleapis.com/auth/userinfo.email

  2. Click the Authorize APIs button.

  3. You will be presented with a consent screen that asks for permissions. Click Allow.

Exchange tokens

  1. On the right hand side of the page, you will see the request and response information. The menu on the left side of the screen will expand to Step 2.
  2. Click Exchange authorization code for tokens.

Send an HTTP GET request to the API to list your surveys

  1. Click Configure request to API if not selected already.
  2. In the Request URI text field, enter:

    https://www.googleapis.com/consumersurveys/v2/surveys

  3. Last, click the Send the Request button. If everything goes as expected, you will have just made a request to the API, and received a response. If you haven't created any surveys yet, an empty JSON response will be returned.

    {
      "resources": []
    }
    

Create a new survey with an HTTP POST request

To create a new survey:

  1. First, change the HTTP method to POST.
  2. Next, you will need to supply the body of the request to be enclosed with the POST. For this example, you can use the least amount of information required to create a new survey. To do this, copy the following request body.

    {
      'owners': ['your_email@your_domain.com'],
      'wantedResponseCount': 100,
      'title': 'Answer to the Ultimate Question of Life, the Universe, and Everything',
      'audience': {
        'country': 'US',
        'languages': ['en-US']
      },
      'questions': [
        {
          'question': 'Why is the answer 42?',
          'type': 'openEnded'
        }
      ]
    }
    

  3. Click the Enter request body button. You will see a dialog with an empty text box.

  4. Paste the request text into the empty text box.
  5. Edit the request so that it shows your development email address.
  6. Click Close.
  7. Click the Send the Request button.
  8. Congratulations! You've created your first survey using the API. At the end of the response, you should see your new survey's ID number, a 13 character string, something like this:

    {
      "surveyUrlId": "5vkj4g6x9is42"
    }
    

  9. You can now rerun the earlier GET request for all of your surveys, by clicking the HTTP Request button and reselecting GET. You will now see your survey listed below:

    {
      "requestId": "56f04cea00ff0cc780d0cf70840001737e3430322d747269616c320001707573682d30332d31372d72303800010106",
      "resources": [
        {
          "state": "editable",
          "surveyUrlId": "5vkj4g6x9is42",
          "title": ""
        }
      ]
    }
    

Send a GET request to examine a survey

To review the properties of a survey, run a GET request to retrieve the survey:

  1. In the Request URI text field, enter:

    https://www.googleapis.com/consumersurveys/v2/surveys/5vkj4g6x9is42

  2. Replace 5vkj4g6x9is42 with your new survey's ID number.

  3. Click the Send the request button.
  4. In response, you should see a description of the survey that looks exactly like the create request you sent:

    {
      "owners": ["your_email@your_domain.com"],
      "wantedResponseCount": 100,
      "title": "Answer to the Ultimate Question of Life, the Universe, and Everything",
      "audience": {
        "country": "US",
        "languages": ["en-US"]
      },
      "questions": [
        {
          "question": "Why is the answer 42?",
          "type": "openEnded"
        }
      ]
    }
    

For reference, you can also examine one of the pre-existing sample surveys with a GET request. The example below references the "Pricing" survey, whose ID is dfoce2a6iucvy.

  1. In the Request URI text field, enter:

    https://www.googleapis.com/consumersurveys/v2/surveys/dfoce2a6iucvy

  2. You should see a description of the example survey:

    {
      "owners": [
        "your_email@your_domain.com"
      ],
      "description": "Pricing surveys enable researchers to get a better sense of how much consumers are willing to pay for a product. There are lots of ways to do pricing and entire disciplines built around the study of pricing goods. In this survey we attempt to get some understanding of how users like to pay for digital goods like games and at what point price sensitivity kicks in for our new mobile game Loot.",
      "title": "Pricing ",
      "state": "complete",
      "audience": {
        "languages": [
          "en-US"
        ],
        "country": "US"
      },
      "cost": {
        "nanos": "2600000000000",
        "currencyCode": "USD",
        "costPerResponseNanos": "2600000000"
      },
      "questions": [
      {
        "type": "singleAnswer",
        "thresholdAnswers": [
          "Android (e.g. Samsung, LG, Lenovo, etc.)",
          "iOS (Apple iPhone)"
        ],
        "question": "What is the operating system of your primary mobile phone (the one you use the most)?",
        "answerOrder": "randomize",
        "answers": [
          "Android (e.g. Samsung, LG, Lenovo, etc.)",
          "iOS (Apple iPhone)",
          "Windows Mobile",
          "Blackberry",
          "Other operating system",
          "I don't own a cell phone"
        ]
      },
      ...
      ],
      "wantedResponseCount": 1000
    }
    

Send a GET request to the API for survey results

Your survey may not have any results to show yet, but you can use the public example surveys to try out the method for getting a survey's results.

  1. Click Configure request to API if not selected already.
  2. In the Request URI text field, enter:

    https://www.googleapis.com/consumersurveys/v2/surveys/dfoce2a6iucvy/results?alt=media

  3. Click the Send the Request button. This request may take longer than the others.

  4. You should see a binary file with survey results. This is a valid Excel file.

Next Steps

Send feedback about...

Google Surveys
Google Surveys