Hide

Get Started

This document provides all the basic information you need to start using the library. It covers the library concepts, shows examples for various use cases, and gives links to more information.

Setup

There are a few setup steps you need to complete before you can use this library:

  1. If you don't already have a Google account, sign up.
  2. If you have never created a Google Developers Console project, read the Managing Projects page and create a project in the Google Developers Console.
  3. Install the NuGet package you want to work with.

Authentication and authorization

It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.

1. Simple API access (API keys)

These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google Developers Console project. This is needed to measure project usage for accounting purposes.

API key: To authenticate your application, use an API key for your Developers Console project. Every simple access call your application makes must include this key.

2. Authorized API access (OAuth 2.0)

These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.

Scope: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.

Refresh and access tokens: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.

Client ID and client secret: These strings uniquely identify your application and are used to acquire tokens. They are created for your project on the Developers Console. There are three types of client IDs, so be sure to get the correct type for your application:

Examples

In this section, there are examples of simple API usage without authorization. For more information about authorization calls, see the OAuth 2.0 page for .NET.

Simple API example

This example uses simple API access for a command-line application. It calls the Google Discovery API to list all Google APIs.

Setup for example

Get your Simple API key. To find your application's API key, do the following:

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, expand APIs & auth. Next, click APIs. Select the Enabled APIs link in the API section to see a list of all your enabled APIs. Make sure that the API is on the list of enabled APIs. If you have not enabled it, select the API from the list of APIs, then select the Enable API button for the API.
  4. In the sidebar on the left, select Credentials.
  5. 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 Google APIs 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 Client ID.

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

      2. Paste the SHA1 fingerprint into the form where requested.
      3. After the fingerprint, type a semicolon and then enter your Android app's package name.
      4. Click Create.

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

Code for example

using System;
using System.Threading.Tasks;

using Google.Apis.Discovery.v1;
using Google.Apis.Discovery.v1.Data;
using Google.Apis.Services;

namespace Discovery.ListAPIs
{
    /// <summary>
    /// This example uses the discovery API to list all APIs in the discovery repository.
    /// https://developers.google.com/discovery/v1/using.
    /// <summary>
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Discovery API Sample");
            Console.WriteLine("====================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            // Create the service.
            var service = new DiscoveryService(new BaseClientService.Initializer
                {
                    ApplicationName = "Discovery Sample",
                    ApiKey="[YOUR_API_KEY_HERE]",
                });

            // Run the request.
            Console.WriteLine("Executing a list request...");
            var result = await service.Apis.List().ExecuteAsync();

            // Display the results.
            if (result.Items != null)
            {
                foreach (DirectoryList.ItemsData api in result.Items)
                {
                    Console.WriteLine(api.Id + " - " + api.Title);
                }
            }
        }
    }
}

Tips for using API keys:

  • In order to use a specific service, you have to add a reference to it. For example if you want to use the Tasks API, you should install its NuGet package Google.Apis.Tasks.v1.
  • To create an instance of a service, just call its constructor. For example: new TasksService(new BaseClientService.Initializer {...});".
  • All methods of a service are located on individual resources on the service object itself. The Discovery service has an Apis resource, which contains a List method. When you call service.Apis.List(..) a request object targeting this method is returned.
    To execute a request, call the Execute() or ExecuteAsyc() method on a request.
  • Set the API key using the ApiKey property on the BaseClientService.Initializer instance.

Finding information about the APIs

The Supported APIs page lists all APIs that can be accessed using this library as well as links to documentation.

You can also use the APIs Explorer to browse APIs, list available methods, and even try API calls from your browser.