Google Sheets Getting Started: API Access & First Request (2026)

Getting started overview

Integrating with the Google Sheets API enables programmatic interaction with spreadsheets, allowing for tasks such as reading data, updating cell values, and managing sheet properties. This guide outlines the essential steps to configure your environment, obtain necessary credentials, and execute a foundational API call.

Before making any API requests, developers must complete three primary setup phases:

1. Google Account Setup: Ensure you have a Google account, which is a prerequisite for accessing Google Cloud services and the Sheets API.
2. Google Cloud Project Configuration: Create a new project within the Google Cloud Console and enable the Google Sheets API for that project. This project acts as a container for your application's resources and API usage data.
3. OAuth 2.0 Credentials: Generate the appropriate OAuth 2.0 client ID and secret to authenticate your application. Google Sheets API utilizes OAuth 2.0 for authorization, allowing users to grant your application specific permissions to their data without sharing their passwords (OAuth 2.0 specification overview).

Once these steps are complete, you can use the client libraries provided by Google to interact with the API in your preferred programming language.

Create an account and get keys

Accessing the Google Sheets API requires a Google account and specific configurations within the Google Cloud Console. Follow these steps to prepare your environment:

1. Create or sign in to a Google Account

If you do not already have one, create a Google account. This account will be used to access the Google Cloud Console and manage your API projects (Google Sheets official page).

2. Set up a Google Cloud Project

• Navigate to the Google Cloud Console.
• From the project selector dropdown at the top, select New Project.
• Enter a descriptive Project name and click Create. Note the Project ID, as it may be needed for some calls.

3. Enable the Google Sheets API

• With your new project selected, use the navigation menu (☰) to go to APIs & Services > Library.
• Search for Google Sheets API and select it from the results.
• Click the Enable button. This step registers your project to use the Sheets API (Google Sheets API concepts guide).

4. Configure OAuth Consent Screen

Before creating credentials, you need to configure the OAuth consent screen, which is displayed to users when they authorize your application.

• In the Google Cloud Console, navigate to APIs & Services > OAuth consent screen.
• Choose the User Type (e.g., External for public applications, Internal for Google Workspace organizations) and click Create.
• Fill in the required fields: App name, User support email, and Developer contact information.
• Click Save and Continue. For a basic setup, you can skip adding scopes and test users initially and proceed to create credentials.

5. Create OAuth 2.0 Client ID Credentials

• Go to APIs & Services > Credentials.
• Click + CREATE CREDENTIALS and select OAuth client ID.
• For Application type, choose the appropriate option (e.g., Desktop app for local scripts, Web application for web servers).
• Enter a Name for your OAuth client.
• If choosing Web application, you may need to specify Authorized JavaScript origins and Authorized redirect URIs. For a desktop application or local script, these are typically not required for the initial setup.
• Click Create.
• A dialog will appear displaying your Client ID and Client secret. Download these credentials as a JSON file or copy them, as they are essential for authenticating your API requests. Keep these credentials secure (Google Sheets API authorization guide).

Your first request

This example demonstrates how to make a basic request to read data from a Google Sheet using the Python client library. This approach is common as Python is one of the primary languages for Google Sheets API examples.

Prerequisites

• Python 3.6+ installed.
• The google-api-python-client and google-auth-oauthlib libraries installed:

  pip install google-api-python-client google-auth-oauthlib google-auth-httplib2

• A Google Sheet with some sample data. Create a new sheet in Google Sheets and populate cells A1:C3 with arbitrary text (e.g., "Name", "Age", "City" in A1:C1 and data below). Note the Spreadsheet ID from the URL (https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit#gid=0).
• The credentials.json file (containing your client ID and secret) downloaded from the Google Cloud Console and placed in the same directory as your Python script.

Python example: Reading cell values

This script will authenticate with OAuth 2.0, prompt for user authorization if needed, and then read a specified range from your Google Sheet.

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
# The 'https://www.googleapis.com/auth/spreadsheets.readonly' scope allows read-only access.
SCOPES = ["https://www.googleapis.com/auth/spreadsheets.readonly"]

# The ID and range of a sample spreadsheet.
SPREADSHEET_ID = "YOUR_SPREADSHEET_ID" # Replace with your actual Spreadsheet ID
RANGE_NAME = "Sheet1!A1:C3"

def get_sheet_data():
    """Shows basic usage of the Sheets API. Reads values from a spreadsheet.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            # 'client_secrets.json' should be renamed to 'credentials.json'
            # or directly specify the file name for client_secrets_file
            flow = InstalledAppFlow.from_client_secrets_file(
                "credentials.json", SCOPES
            )
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        service = build("sheets", "v4", credentials=creds)

        # Call the Sheets API
        sheet = service.spreadsheets()
        result = (
            sheet.values()
            .get(spreadsheetId=SPREADSHEET_ID, range=RANGE_NAME)
            .execute()
        )
        values = result.get("values", [])

        if not values:
            print("No data found.")
            return
        
        print(f"Data from {RANGE_NAME}:")
        for row in values:
            # Print columns A, B, C, which correspond to the first three items.
            print(row)

    except HttpError as err:
        print(err)

if __name__ == "__main__":
    get_sheet_data()

To run this code:

1. Replace "YOUR_SPREADSHEET_ID" with the actual ID of your Google Sheet.
2. Ensure your credentials.json file (downloaded from the Google Cloud Console) is in the same directory as this Python script.
3. Execute the script: python your_script_name.py.
4. The first time you run it, a browser window will open, prompting you to authorize your application with your Google account. After authorization, the script will print the data from the specified range in your sheet.

Common next steps

After successfully making your first API call, consider these next steps to expand your usage of the Google Sheets API:

• Explore different API methods: Beyond reading data, the Sheets API allows for writing, updating, and formatting cells, as well as managing sheets and workbooks. Refer to the Google Sheets API Reference for a comprehensive list of available methods and their parameters.
• Implement other SDKs: If Python is not your primary language, explore the official Google client libraries for Node.js, Java, PHP, Ruby, and .NET to integrate the Sheets API into your existing applications.
• Manage permissions and scopes: Understand the different OAuth 2.0 scopes available for the Sheets API. Using more restrictive scopes (e.g., read-only access if write access isn't needed) enhances the security of your application.
• Error handling: Implement robust error handling in your application to gracefully manage API rate limits, authentication failures, and other potential issues. Google's client libraries typically provide specific exceptions for different error types (Google Cloud API design guide on error handling).
• Google Apps Script: For automating tasks directly within Google Sheets or extending its functionality without external servers, explore Google Apps Script. This JavaScript-based platform allows you to create custom functions, menu items, and triggers within Google Workspace.
• Webhooks and Triggers: While the Google Sheets API itself doesn't directly offer webhooks for real-time updates, you can use Google Apps Script to create custom triggers that respond to sheet changes or time-driven events, effectively simulating webhook-like behavior for internal automation.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some frequent problems and their solutions:

• ❌ Error 403: Access Not Configured. Google Sheets API has not been used in project [project ID] before
  • Solution: Ensure the Google Sheets API is enabled for your specific Google Cloud project. Go to APIs & Services > Library in the Google Cloud Console, search for "Google Sheets API", and click Enable.
• ❌ Error 401: Invalid Credentials or unauthorized_client
  • Solution: This typically indicates an issue with your OAuth 2.0 client ID or secret. Verify that your credentials.json file is correctly placed, uncorrupted, and contains the correct client ID and client secret. For web applications, ensure the Authorized redirect URIs in your OAuth client ID configuration match the URI your application uses. If running a desktop app, ensure the token.json file (if it exists from a previous run) is valid or deleted to force re-authentication.
• ❌ Error 400: Invalid Value or The remote server returned an error: (400) Bad Request.
  • Solution: Check the SPREADSHEET_ID and RANGE_NAME in your code. Ensure the spreadsheet ID is correct and the range (e.g., Sheet1!A1:C3) accurately reflects a valid sheet name and cell range within your target spreadsheet. Double-check for typos.
• ❌ Error 403: The caller does not have permission (or similar permission denied errors)
  • Solution: The authorized Google account does not have sufficient permissions to access the specified spreadsheet. Ensure the Google account used for authorization has at least "Viewer" access to the Google Sheet. Also, verify that the OAuth 2.0 scopes requested by your application are sufficient for the desired operation (e.g., spreadsheets.readonly for reading, spreadsheets for read/write).
• ❌ Python script not opening browser for authentication
  • Solution: Ensure your environment allows local server redirection for OAuth. If running in a headless environment, you might need to use an alternative authorization flow for devices with limited input capabilities, or open the authorization URL manually in a browser from another machine and copy the resulting authorization code.