Getting Started

How an application makes an API request using the JavaScript client library

There are many ways to use the JavaScript client library to make API requests, but they all follow the same basic pattern:

1. The application loads the JavaScript client library.
2. The application sets its API key, which authenticates the application with Google services.
3. If the application needs access to the user's personal information, it sets its OAuth 2.0 client ID and opens a session with a Google auth server. The auth server opens a dialog box which prompts the user to authorize the use of personal information.
4. The application loads the API for the Google service.
5. The application initializes a request object (also called a service object) that specifies the data to be returned by the API.
6. The application executes the request and processes the data returned by the API.

The next section describes shows how these tasks could be handled in a web page's JavaScript.

How it looks in JavaScript

This example code is adapted from authSample.html. It is shown here to give you a quick impression of how the JavaScript client library is used.

For a discussion of this code, see the Authentication page.

var apiKey = 'YOUR_API_KEY';
var clientId = 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com';
var scopes = 'profile';

function initAuth() {
  gapi.client.setApiKey(apiKey);
  gapi.auth2.init({
      client_id: clientId,
      scope: scopes
  }).then(function () {
    // Listen for sign-in state changes.
    gapi.auth2.getAuthInstance().isSignedIn.listen(updateSigninStatus);

    signinButton.addEventListener("click", handleSigninClick);
  });
}

// Get authorization from the user to access profile info
function handleSigninClick(event) {
  gapi.auth2.getAuthInstance().signIn().then(function() {
    makeApiCall();
  });
}

gapi.load('client:auth2', initAuth);

// Load the API and make an API call.  Display the results on the screen.
function makeApiCall() {
  gapi.client.load('people', 'v1', function() {
    var request = gapi.client.people.people.get({
      resourceName: 'people/me'
    });
    request.execute(function(resp) {
      var p = document.createElement('p');
      var name = resp.names[0].givenName;
      p.appendChild(document.createTextNode('Hello, '+name+'!'));
      document.body.appendChild(p);
    });
  });
  // Note: In this example, we use the People API to get the current
  // user's name. In a real app, you would likely get basic profile info
  // from the GoogleUser object to avoid the extra network round trip.
  console.log(auth2.currentUser.get().getBasicProfile().getGivenName());
}

Get a Google Account

First, sign up for a Google Account if you do not already have one.

Choose Google services

Next, choose which of Google's online services your application will use. See the APIs Explorer for information about Google services with APIs that the JavaScript client library can work with.

Get access keys for your application

Google defines two levels of API access:

To acquire an API key for simple access, do the following:

1. Open the Credentials page in the API Console.
2. Click Create credentials > API key and select the appropriate key type.

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

To acquire OAuth 2.0 credentials for authorized access, open the Credentials page in the API Console and then do the following:

1. From the Credentials page, click Create credentials > OAuth client ID to create your OAuth 2.0 credentials or Create credentials > Service account key to create a service account.
2. If you created an OAuth client ID, then select your application type.
3. Fill in the form and click Create.

Your application's client IDs and service account keys are now listed on the Credentials page. For details, click a client ID; parameters vary depending on the ID type, but might include email address, client secret, JavaScript origins, or redirect URIs.

For information about how to use OAuth 2.0 credentials in your application, see the Authentication page.

Activate APIs

To enable an API for your project, do the following:

1. Open the API Library in the Google API Console. If prompted, select a project or create a new one. The API Library lists all available APIs, grouped by product family and popularity.
2. If the API you want to enable isn't visible in the list, use search to find it.
3. Select the API you want to enable, then click the Enable button.
4. If prompted, enable billing.
5. If prompted, accept the API's Terms of Service.