The Google APIs Explorer dynamically generates code samples, which are designed to be copied and run locally. The samples update to reflect the parameter and property values you have entered in the tool. To see the samples, open the fullscreen APIs Explorer by clicking the icon in the APIs Explorer.
By default, the APIs Explorer shows how to use cURL to execute your request. Some APIs might also show samples for other languages, such as JavaScript, Java, and Python.
Running code samples locally
The tabs below explain the prerequisites for running code samples in different languages. For any code sample, you will need your own API credentials, and some samples require OAuth 2.0 authorization. Your credentials will be one of the following, depending on the sample in question:
- an API key
- a
client_secret.json
file containing your OAuth 2.0 client ID and client secret - an OAuth 2.0 access token
If you run a sample that requires OAuth 2.0 authorization using only an API key, the API response will contain an error message indicating that the request is not properly authorized. Also, before trying to run a sample locally, look in the code sample for the strings TODO and YOUR. Code samples use those strings to identify changes that you need to make to run the sample successfully.
-
Create or select a project in the API Console. Complete the following tasks in the API Console for your project:
-
In the library panel, search for the API you are calling and make sure it is enabled for your project.
-
In the credentials panel, either create an API key or create an OAuth 2.0 client ID and set the application type to web application. Note that some API requests require OAuth 2.0 authorization.
If you created an OAuth 2.0 client ID, set the authorized JavaScript origins to identify the URL from which you'll be sending requests (e.g.
http://localhost
).
-
-
Copy the full code sample to a local file accessible to your web server (e.g.
/var/www/html/example.html
). -
Find the line in the code sample that sets the API key or client ID to be used for the request, and replace the value with the appropriate value for your credentials:
- API key
gapi.client.setApiKey(YOUR_API_KEY);
- OAuth 2.0 client ID
gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',
- API key
-
Open the file in your browser (e.g.
http://localhost/example.html
). It is recommended to use a browser with a debugging console, such as Google Chrome. -
Authorize the request if necessary. If the request is authorized, the debugging console should display the API response to the request as a JSON object.
Prerequisites
- Java 1.7 or greater
- Gradle 2.3 or greater
Set up your project and run code samples
-
Create or select a project in the API Console. Complete the following tasks in the API Console for your project:
-
In the library panel, search for the API you are calling and make sure it is enabled for your project.
-
In the credentials panel, either create an API key or create an OAuth 2.0 client ID and set the application type to Other. Note that some API requests require OAuth 2.0 authorization.
If you created an OAuth 2.0 client ID, download the JSON file that contains your OAuth 2.0 credentials. The file has a name like
client_secret_CLIENTID.json
, whereCLIENTID
is the client ID for your project.
-
-
Complete the following steps to prepare your Gradle project:
- In your working directory, run the following commands to create a new project structure:
$ gradle init --type basic $ mkdir -p src/main/java src/main/resources
- If you created an OAuth 2.0 client ID in step 1, rename the JSON file that you downloaded to
client_secret.json
. Save the renamed file in thesrc/main/resources
directory that you created in step 2a. (If you name the file something else, you must also update the code sample to look for the right filename.) - Open the
build.gradle
file in your working directory and replace its contents with the following:
apply plugin: 'java' apply plugin: 'application' mainClassName = 'ApiExample' sourceCompatibility = 1.7 targetCompatibility = 1.7 version = '1.0' repositories { mavenCentral() } dependencies { compile 'com.google.api-client:google-api-client:1.23.0' compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0' API_SPECIFIC_DEPENDENCY }
- In your working directory, run the following commands to create a new project structure:
- In the
build.gradle
file, replace the line that saysAPI_SPECIFIC_DEPENDENCY
with an instruction to compile code for the API you are calling. Here is a sample for the YouTube Analytics API:compile 'com.google.apis:google-api-services-youtubeAnalytics:v2-rev16-1.23.0'
The instruction follows this template:
compile 'com.google.apis:google-api-services-API_NAME:API_VERSION-revREVISION-CL_VERSION'
In that template:
- API_NAME is the API name listed for the API on this page.
- API_VERSION is the API version listed for the API below the API name on the same page.
- REVISION is the revision number listed in the JavaDoc reference for the API. The JavaDoc reference can be found at
https://developers.google.com/resources/api-libraries/documentation/API_NAME/API_VERSION/java/latest/
. (Replace API_NAME and API_VERSION in the URL with the correct information.) - CL_VERSION is the client library version. It also appears in the JavaDoc reference. The screenshot below shows where the REVISION and CL_VERSION values appear in the JavaDoc for reference for the YouTube Analytics API:
From your working directory, copy the code sample from APIs Explorer to src/main/java/ApiExample.java
. (The class name in each sample is ApiExample
so that you do not need to modify the build.gradle
file to run different samples.)
Run the sample from the command line:
gradle -q run
The sample should execute your API request and print the response to STDOUT
. You can also check the service you are calling to see the effects of requests that write data.
Prerequisites
- Node.js and npm installed
- The Google APIs Client Library for Node.js:
- If you have not previously installed the client library:
npm install googleapis --save
- If you previously installed the client library, we recommend updating it to ensure
that you have the most up-to-date classes for the library you are testing:
npm update googleapis --save
- If you have not previously installed the client library:
Set up your project and run code samples
-
Create or select a project in the API Console. Complete the following tasks in the API Console for your project:
-
In the library panel, search for the API you are calling and make sure it is enabled for your project.
-
In the credentials panel, either create an API key or create an OAuth 2.0 client ID and set the application type to Other. Note that some API requests require OAuth 2.0 authorization.
-
-
Save the client secrets JSON file associated with your credentials to a local file, such as
client_secret.json
. -
Copy the full code sample to a local file and modify the sample to correctly identify your API key or client secrets file. In the sample, the API key value is
YOUR_API_KEY
, and the client secrets file location isYOUR_CLIENT_SECRET_FILE.json
. -
Run the sample from the command line:
node sample.js
-
Most samples print an API response (or something else) to
STDOUT
.
Prerequisites
- PHP 5.4 or greater with the command-line interface (CLI) and JSON extension installed.
- The Composer dependency management tool installed globally.
- The Google APIs Client Library for PHP:
- If you have not previously installed the client library:
composer require google/apiclient:^2.0
- If you previously installed the client library, we recommend updating it to ensure
that you have the most up-to-date classes for the library you are testing:
composer update google/apiclient --with-dependencies
- If you have not previously installed the client library:
Set up your project and run code samples
-
Create or select a project in the API Console. Complete the following tasks in the API Console for your project:
-
In the library panel, search for the API you are calling and make sure it is enabled for your project.
-
In the credentials panel, either create an API key or create an OAuth 2.0 client ID and set the application type to Other. Note that some API requests require OAuth 2.0 authorization.
-
-
Save the client secrets JSON file associated with your credentials to a local file, such as
client_secret.json
. -
Copy the full code sample to a local file and modify the sample to correctly identify your API key or client secrets file. In the sample, the API key value is
YOUR_API_KEY
, and the client secrets file location isYOUR_CLIENT_SECRET_FILE.json
. -
Run the sample from the command line:
php sample.php
-
Most samples print an API response (or something else) to
STDOUT
.
Prerequisites
- Python 2.7 or Python 3.5+
- The pip package management tool
- The Google APIs Client Library for Python:
pip install --upgrade google-api-python-client
- The google-auth-oauthlib and google-auth-httplib2 libraries for user authorization.
pip install --upgrade google-auth-oauthlib google-auth-httplib2
Set up your project and run code samples
-
Create or select a project in the API Console. Complete the following tasks in the API Console for your project:
-
In the library panel, search for the API you are calling and make sure it is enabled for your project.
-
In the credentials panel, either create an API key or create an OAuth 2.0 client ID and set the application type to Other. Note that some API requests require OAuth 2.0 authorization.
-
-
Save the client secrets JSON file associated with your credentials to a local file, such as
client_secret.json
. -
Copy the full code sample to a local file and modify the sample to correctly identify your API key or client secrets file. In the sample, the API key value is
YOUR_API_KEY
, and the client secrets file location isYOUR_CLIENT_SECRET_FILE.json
. -
Run the sample from the command line:
python sample.py
-
Most samples print an API response (or something else) to
STDOUT
.
Troubleshooting
This section explains how to troubleshoot some frequently reported issues. Most of these errors can occur when you execute requests in the APIs Explorer widget or if you test the APIs Explorer's code samples locally. To run samples locally, you must usually make at least one change to the sample, which is to update the code to identify the your API key or the local path to your client secrets file. However, sometimes additional changes are required as well.
- YOUR_CLIENT_SECRET_FILE
- YOUR_VIDEO_ID
- TODO: For this request to work, you must replace "YOUR_FILE" with the path to the file where that content should be written.
Authorization and authentication errors
Every API request must use some type of credentials to identify the application that is calling the API and, depending on the request, the user who is making the request. If the API server needs to identify the user making the request and obtain their permission to complete the request, then that request requires user authorization. For example, if a request calls the Gmail API to retrieve your Gmail messages, the API server should only return those messages if you authorized the operation.
Your code can use an API key or an OAuth 2.0 client ID to identify your application. However, requests that require user authorization must use an OAuth 2.0 client ID.
When you try to execute an API request, the API server verifies a few different things before returning a result. If you are getting a 401
or 403
error when testing a sample, it is likely due to a problem at one of those steps. The following subsections explain several common causes of those errors. Note that 401
errors are often communicated as Unauthorized
or Login Required
, while 403
errors are often communicated as Forbidden
or insufficientPermissions
.
Note: The APIs Explorer uses demo credentials by default to make it easier to get started. But you need your own credentials to call APIs from your own code so that you have your own quota, permissions, etc.
Your code calls an API that isn't enabled for your project
In the API Console you need to enable your project to call different APIs. The API server usually returns a 403
error if you try to call an API that hasn't been enabled for your project. To enable an API, go to the API Library page in the API Console and find the API. The page that describes the API should display a button to enable it.
Credential restrictions prevent the request from being executed
When you create your API credentials, you can set restrictions to help prevent unauthorized use of your credentials and, hence, your API quota. For example, you can specify authorized HTTP referrers, IP addresses, JavaScript origins, Android package names, and redirect URIs. The API server uses that information to confirm that a request that's using your credentials is actually coming from your application.
If you place restrictions on your API credentials, then a request that uses those credentials must meet those restrictions. For example, if you specify valid JavaScript origins, then any request that uses your API credentials must originate from one of those locations. The API server usually returns a 403
error if a request uses API credentials that specify restrictions but the request doesn't meet those restrictions.
Request specifies API key, but requires OAuth 2.0 client ID
Many API requests require an authenticated user to authorize the request. For example, an API request that uploads a YouTube video must be authorized by the user whose channel the video is being uploaded to. Requests that require user authorization must use an OAuth 2.0 client ID.
If your request requires user authorization but only specifies an API key, the API server usually returns a 401
error because the request cannot be completed without permission from the user making the request. Using the example from the previous paragraph, you can't upload a video to your YouTube channel if the API server can't securely figure out who you are.
Google uses your OAuth 2.0 client ID during the authorization process to obtain a token that identifies the user. That identification can't be made using only an API key.
User has not granted the permissions needed for the request
When an application makes a request that requires user authorization, the user must have also granted the application permission to make that request. Permissions are requested using scopes. The API server usually returns a 403
(Insufficient Permission) error if the authorization credentials do not cover the scopes required for the request.
For example, suppose you send an API request that lists your Google Drive files. For that request, you need to grant the application making the request permission to read data from Google Drive.
Then, you make a second request to retrieve data about events in your Google Calendar. The second request accesses different data and requires different permissions than the first request. If you try to use the same authorization credentials as in the first request, the second request returns an error.
Your request is authorized by the wrong user
An application doesn't just need permission from any user to complete a request. Rather, it needs permission from someone who is actually authorized to grant that permission. For example, you can't authorize a request to retrieve someone else's Gmail messages.
The API server usually returns a 403
(Forbidden) error if a request is authorized by one user but should be authorized by a different user.
Language-specific errors
JavaScript
-
gapi is not defined
This error occurs when your JavaScript code tries to call the Google API Client Library for JavaScript before the library has actually loaded. Make sure that your code that references the
gapi
variable is not called until after the client library has loaded.The examples for loading an API and making a request and for loading the client library asynchronously show two different ways to make sure the library is loaded before your code starts calling it.