DEV Community: Wesley Chun (@wescpy)

Simplifying basic (genAI) web app deployment with serverless

Wesley Chun (@wescpy) — Mon, 01 Dec 2025 10:21:48 +0000

TL;DR:

Writing simple web apps is one thing, but deploying it globally without having to think about servers, VMs (virtual machines), or DNS is another. That's where this post and serverless come into play. Whether you have a Gemini-powered app or agent, serverless lets you focus on the solution you're building, not what it runs on. In this post, we show you how to deploy a basic web app featuring the Gemini API to serverless on Google Cloud.

Introduction

Welcome to another installment on the blog covering Google APIs for Python (and sometimes Node.js) developers. Here, I cover stuff you won't find in Google's documentation, all while showing you how to use Google APIs from different product groups for what you build. Here are some of the categories covered so far:

Google Cloud/GCP (AI/ML, serverless) (this series)
Google Workspace/GWS (Drive, Docs, Sheets, Gmail, etc.)
YouTube
Maps
Generative AI with Gemini (this series)
Credentials (API keys, OAuth client IDs, service accounts)

We return to Gemini again in this post but focus less on the AI and more on how to more easily deploy apps to the cloud, whether AI-powered or not.

Background

Writing web apps is one thing, but deploying them globally without having to think about servers, VMs (virtual machines), DNS, and scalability is another. That's where this post and serverless come into play. Whether you have a Gemini-powered app or agent, serverless lets you focus on the solution you're building, not what it runs on or even how to run it. Is this you?

There won't be much introductory material as we'll get straight into serverless deployments. For more background, it's wise to point out that this is a follow-up to several posts from this blog, all which make for good reading before proceeding:

The post covering a basic genAI web app whose code was recently updated following advice from...
Another post on upgrading to Gemini 2.5
The post introducing serverless
The post to hosting apps today on Google App Engine
The post on modern app-hosting with Google Cloud Run

Architectural components

There are several large "pieces of the puzzle" to look at, and decisions to be made:

API platforms & credentials -- decide which platform to use when calling the Gemini API then get your credentials and set up your Cloud project
Languages -- decide whether you want to run Node.js or Python (should be easy); each language has several options too
GCP Serverless platforms -- decide which serverless platform you want to run, and by the way, what's serverless anyway?

Each has its own set of prerequisites which must be satisfied before running any of the sample apps.

Gemini API

Gemini is a popular, proprietary, multimodal LLM (large language model), accessed via its public chat interface or as the LLM for agents. Its API lets developers tap into its capabilities directly from web apps or mobile backends, and the former is the use case we're addressing in this post. One aspect of using the API is unexpected: Google makes the Gemini API available from two different platforms. Each has its own set of use cases as well as pricing differences. Learn about both platforms via the resources in the following table:

Platform	Use Cases	Pricing
Google AI ("GAI")	Experimenting, free tier/lower cost, lower barrier-to-entry, hobbyists/students	pricing
Vertex AI (Google Cloud/"GCP")	Production AI workloads, existing GCP customers adding and/or considering AI capabilities	pricing

Since this post is mostly introductory, we'll use the Gemini API from Google AI, however, the current, unified client library lets developers transition to GCP easily, representing a significant improvement from when there were two distinct client libraries, one for each platform. Compare, contrast and learn the differences between all three client libraries (two old and one new) in the second post listed above which aims to help those migrating to Gemini 2.5.

There's no doubt that old samples live forever online and vibecoding LLMs have been trained on both old and new code, so that post serves as a PSA (public service announcement) to show readers the differences between all three libraries so they can upgrade their own applications or fix code using old libraries generated by LLMs.

Requirements(s)

In order to run the sample apps locally or deploy to the cloud, you need to complete the prerequisites:

Get credentials: Go to the GAI API keys page and select an existing API key or click "Create API key" to make a new one. Save the API key text string somewhere safe; we'll come back to it shortly.
Get project: The "Create API key" dialog also lets you create a new project (or import an existing one), so do that too.
- Completely new? If you're completely new to GCP, learn more about developer projects.

[IMG] Google AI create API key page

[IMG] Google AI create API key dialog

Existing GCP users: Experienced GCP users may prefer to do the above from the Cloud Console:

Create a new project or select an existing one.

Go to the Credentials page and create an API key or select an existing one.

[IMG] Cloud console create project page
[IMG] Cloud console create API key dialog on create credentials page

Languages

The code featured in this post is available in various versions of Node.js and Python:

Language	Version	Web framework
Node.js	ECMAscript module	Express
Node.js	CommonJS script	Express
Python	Python 3	Flask
Python	Python 3	FastAPI

All code samples are available in this repo. Regular readers will notice it differs from this blog's regular repo, and there's a reason for this. I spent several years on Google's GCP Serverless team representing those products. During that time, I created a repo named (Cloud) Nebulous Serverless to show developers how they can deploy the same app to all platforms without any code changes.

That repo held all sample applications I built meeting this criteria. Google archived that repo after my departure, so I'm continuing all work in my personal fork. The samples in this post also meet that criteria, so that's why they're in this repo and not the normal one. (I also removed "Cloud" from the repo name as there are now non-Cloud sample apps in the fork.)

Requirements(s)

Setup local environment:
- Clone the code locally with git clone https://github.com/wescpy/nebulous-serverless.git and go to the app folder in multi/webgem with cd multi/webgem.
- Node.js: Ensure you have contemporary versions of Node & NPM (recommend 18+), cd nodejs and install all packages with npm i
- Python: Ensure you have a contemporary version of Python (recommend 3.9+) and cd python
  - (optional) Create & activate a virtual environment ("virtualenv") for isolation with python3 -m venv .venv; source .venv/bin/activate
  - For the commands below, depending on your system configuration, you will use one of (pip, pip3, python3 -m pip), but the instructions are generalized to pip.
  - (optional) Update pip and install uv with pip install -U pip uv
  - Decide whether to run the Flask or FastAPI version.
  - Flask: Install all packages: uv pip install -Ur requirements.txt (drop uv if you didn't install it)
  - FastAPI: Replace Flask files by moving them out of the fastapi folder: mv fastapi/* . then install all packages: uv pip install -Ur requirements.txt (drop uv if you didn't install it)
Set credentials: Previously, you selected a project and created an API key; now save it to one of these files, depending on which language you're using:
- Node.js: Save as API_KEY = YOUR_API_KEY to .env
- Python: Save as API_KEY = 'YOUR_API_KEY' to settings.py

You can model yours after the provided templates, .env_TMPL or settings_TMPL.py:

.env_TMPL

API_KEY="YOUR_API_KEY"
GCP_METADATA='{
  "project": "YOUR_GCP_PROJECT",
  "location": "YOUR_GCP_REGION"
}'

settings_TMPL.py

API_KEY = 'YOUR_API_KEY'
GCP_METADATA = {
    'project':  'YOUR_GCP_PROJECT',
    'location': 'YOUR_GCP_REGION',
}

In addition to API_KEY, these files also contain GCP_METADATA in case you migrate to GCP in the future. As mentioned above, you can refer to this post to get an idea of the additional setup and minor code updates you need to make to run your Gemini API-powered apps on Vertex AI.

Use of settings.py as a naming convention follows in Django's footsteps, but alternatively, you can save it to .env and integrate use of python-dotenv to more closely mirror Node.

Serverless platforms

Google Cloud has several serverless platforms to choose from:

Google App Engine (GAE) -- the "OG" serverless platform that launched back in 2008 & somewhat modernized in 2018; uses customized, proprietary containers, free static file edge-caching, and generous outbound networking free tier
Cloud Functions (GCF) -- originally serverless functions to compete with AWS Lambda; latest generation rebranded as Cloud Run Functions
Cloud Run (GCR) -- the latest serverless platform; OCI-compliant containers (Docker, Buildpacks, etc.)

Since Cloud Functions has merged into Cloud Run, this leaves a pair of primary platforms to pick from. As far as deciding between App Engine and Cloud Run, most people would say go with Cloud Run as it is App Engine's next-generation replacement. It's more flexible (has fewer restrictions), supports modern app deployment (containers), and has many new features, including "Jobs," GPUs, and many more.

See this post to learn more about App Engine, including what it can still do that Cloud Run can't (yet), and see this post to learn more about Cloud Run. Those posts provide much more detail than what's in this post which focuses primarily on deployment instructions. The apps in the repo should be run on both platforms without code changes. See this post to learn more about serverless and these platforms.

Requirements(s)

Choose a platform (or experiment and deploy to both).
- If you pick App Engine, a running application is known as an "app," and you can only have one app in any Cloud project. Enable GAE and create the app in the Cloud console.
- If you pick Cloud Run, a running application is known as a "service," and you can have any number of services in a project. If you're new to GCR, your Cloud Run dashboard will be empty.
- With Cloud Run, you also have an additional decision: Docker or not? While many developers are familiar with containers and specifying how they should be built via a Dockerfile, others prefer to avoid Docker or managing Dockerfiles, and Cloud Run supports both options. Sample Dockerfiles are provided, but you can delete them before deploying or not have them for your own apps.

⚠️ Cost: billing required (but "free?!?")
Before deploying to the cloud, a word on cost. While many Google products are free to use, GCP products are not. In order to run the sample apps, you must enable billing backed by a financial instrument like a credit card (payment method depends on region/currency). If you're new to GCP, review the billing & onboarding guide. Deploying and running the sample app(s) in this post should not incur any cost because basic usage falls under various free tiers:

Several GCP products (like GAE & GCR) have an "Always Free" tier, a free daily or monthly usage quota before incurring charges. See the GCR pricing and quotas pages for more information. Furthermore, deploying to GCP serverless platforms incur minor build and storage costs. (Also see similar content in the GAE docs.)

Cloud Build has its own free quota as does Cloud Storage (GCS), used to store build artifacts. Cloud Build sends application images to the Cloud Artifact Registry (CAR) (or its predecessor), making them accessible to other GCP services. These eat into GCS & CAR (storage) quotas as does transferring images between services & regions. You may be in a region that does not have a free tier however, so monitor your usage to minimize any costs. (Check out storage use and delete old/unwanted build artifacts via the GCS browser.)

Use the cost calculator to get monthly estimates. You may qualify for credits to offset GCP costs: If you are a startup, consider the GCP for Startups program grants. If you are in education, check out the GCP education programs for students, faculty, and researchers.

The app

This sample app is very basic and works like this:

Start with an empty form asking the user for several input items, an image to upload and an LLM prompt:
Select an image for Gemini using the normal file-picker:
Enter a suitable prompt (or take the default "Describe this image"):
When the submit button is pressed, the button text changes to "Processing...", and once Gemini is done, a thumbnail of the image is provided along with LLM output:

I ripped these from the original post where you can get all the details about this app.

The code

The basic web apps in this post are nearly identical to those in that original post. The only differences between that post's repo and this post's repo are the additional files and packages required to deploy that web app to GCP serverless platforms:

Node.js: from original web app

File	Description	Platform
`nodejs/.env_TMPL`	`.env` environment settings template	Node
`nodejs/package.json`	3rd-party packages	Node
`nodejs/main.js`	Express.js sample app	Node (CommonJS script)
`nodejs/main.mjs`	Express.js sample app	Node (ECMAScript module)
`nodejs/templates/index.html`	Web template	Nunjucks (identical to Jinja2)

Node.js: new for serverless deployments

File	Description	Platform
`nodejs/app.yaml`	Config file	App Engine
`nodejs/Dockerfile`	Dockerfile	Cloud Run (with Docker)
`nodejs/.dockerignore`	.dockerignore	Cloud Run (with Docker)
`nodejs/Procfile`	Procfile	Cloud Run (without Docker)
`nodejs/.gcloudignore`	.gcloudignore	App Engine & Cloud Run

Python: from original web app

File	Description	Platform
`python/settings_TMPL.py`	`settings.py` environment settings template	Python 3
`python/requirements.txt`	Flask 3rd-party packages	Python
`python/main.py`	Flask sample app	Python 3
`python/templates/index.html`	Web template	Jinja2 (identical to Nunjucks)

`python/fastapi/requirements.txt`	FastAPI 3rd-party packages	Python 3
`python/fastapi/main.py`	FastAPI sample app	Python 3

Python: new for serverless deployments

File	Description	Platform
`python/app.yaml`	Config file (Flask)	App Engine
`python/Dockerfile`	Dockerfile (Flask)	Cloud Run (with Docker)
`python/.dockerignore`	.dockerignore	Cloud Run (with Docker)
`python/Procfile`	Procfile (Flask)	Cloud Run (without Docker)
`python/.gcloudignore`	.gcloudignore	App Engine & Cloud Run

`python/fastapi/app.yaml`	Config file (FastAPI)	App Engine
`python/fastapi/Dockerfile`	Dockerfile (FastAPI)	Cloud Run (with Docker)
`python/fastapi/Procfile`	Procfile (FastAPI)	Cloud Run (without Docker)

Run locally

Node.js

Earlier, you changed to the Node folder (with cd nodejs) and installed all packages (npm i), so to run the app locally, execute: node main.mjs (or `node main.js for CommonJS).

Python

Earlier, you changed to the Python folder (with cd python). If you decided to run the Flask version, you would've installed all packages (with uv pip install -Ur requirements.txt). If you chose FastAPI instead, you would've replaced the Flask files (with mv fastapi/* ., then run the same install command. To run the app locally (either version), execute: python main.py.

Deploy to the cloud

With cloud deployments, you have many more options, all are listed below along with instructions once you've doublechecked you have a .env or settings.py file with your API key.

Node.js (ECMAscript module) on App Engine
1. Run gcloud app deploy
Node.js (CommonJS script) on App Engine
1. Edit package.json and change main.mjs to main.js globally
2. Run gcloud app deploy
Node.js (ECMAscript module) on Cloud Run with Docker
1. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name
  - Example: gcloud run deploy genai --allow-unauthenticated --source . --region us-west1
Node.js (CommonJS script) on Cloud Run with Docker
1. Edit package.json and change main.mjs to main.js globally
2. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Node.js (ECMAscript module) on Cloud Run without Docker
1. Delete Dockerfile
2. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Node.js (CommonJS script) on Cloud Run without Docker
1. Edit package.json and change main.mjs to main.js globally
2. Delete Dockerfile
3. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Python Flask on App Engine
1. Run gcloud app deploy
Python FastAPI on App Engine
1. Run mv fastapi/* . (if you haven't already)
2. Edit requirements.txt and uncomment the line for gunicorn (it's required)
3. Run gcloud app deploy
Python Flask on Cloud Run with Docker
1. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Python FastAPI on Cloud Run with Docker
1. Run mv fastapi/* . (if you haven't already)
2. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Python Flask on Cloud Run without Docker
1. Delete Dockerfile
2. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)
Python FastAPI on Cloud Run without Docker
1. Run mv fastapi/* . (if you haven't already)
2. Delete Dockerfile
3. Run gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION, replacing SVC_NAME with your service name (see Example above)

Here are a couple of results from my deployments to App Engine (*.appspot.com) and Cloud Run (*.run.app):

[IMG] Web app sample result on App Engine

[IMG] Web app sample result on Cloud Run

Wrap-up

The original post covered a basic web app using the Gemini API. In this post, we follow-up with that same code sample, but add in the extra files needed to deploy it to the Cloud, specifically on GCP serverless platforms which have the benefit of incurring billing only if your app is getting traffic, unlike on VMs where you're billed 24x7. Learning how to create basic web apps using the Gemini API is useful, but if you want to bring it to the world, deploying to serverless is one way to do it!

If you found an error in this post, a bug in the code, or have a topic you want me to cover in the future, drop a note in the comments below or file an issue at the repo. Also check out other posts in the Gemini API series as well as the GCP serverless series. Thanks for reading, and I hope to meet you at an upcoming event soon... see the travel calendar at the bottom of my consulting site.

PREV POST: Basic web apps using the Gemini API

References

Below are various links relevant to this post. Also included below are links to numerous amount of GCP serverless content I produced during my time at Google.

Code samples

Sample in this post (Python & Node.js)
Code samples for Gemini posts (except this one)
Code samples for all posts

Gemini API (Google AI) general

General GenAI docs
API reference
API SDKs/supported languages
API quickstart
Jupyter Notebook QuickStart
Gemini API pricing (free tier available)
Google AI migration guide
GCP Vertex AI for Google AI users

Gemini models

GCP serverless platforms

Google App Engine (GAE)
Google Cloud Functions (Gen1) and Cloud Run Functions (Gen2) (GCF/GCRF)
Google Cloud Run (GCR)

Inspiring Google Developers video retrospective

Wesley Chun (@wescpy) — Mon, 06 Oct 2025 23:03:04 +0000

TL;DR:

In this post, rather than focus on a specific code sample or API feature, I take a step back to thank viewers for their kind regards and recollect some of the videos I produced during my time as a Googler. In addition to linking to a body-of-work table of contents, this retrospective features a subset representing favorites and those I feel are more impactful in one way or another.

Introduction and motivation

Welcome to the place where I help developers (and now vibe-coding LLMs) learn about using Google APIs from Python (and sometimes Node.js), touching multiple API families, "oiling" the squeaky parts to smoothen onboarding friction. I especially like to cover content that's not in Google's documentation. These are the main topics covered so far:

Google Cloud/GCP: (predictive) AI/ML, serverless
Google Workspace/GWS: Gmail, Drive, Sheets, etc.
YouTube
Google Maps Platform/GMP
Gemini and generative AI ("genAI")
Credentials: API keys, OAuth client IDs, service accounts
Old vs. new (client) libraries: Python auth, Gemini API

Part of my work in helping developers use APIs like those above includes producing video content along with blog posts and code samples. When developers come up to me to personally thank me for the video content I produced during my time at Google, it's quite humbling but also empowering. Lowering the barrier-to-entry and getting you going is always a key goal.

While I spent almost equal time on the GCP team as well as on GWS (formerly "G Suite"), I produced more content for the latter product family, and this ratio is reflected across my content. The selection criteria the videos I'd like to highlight include those which stand out to me as far as uniqueness, usefulness, and impact.

Nearly all were produced before generative AI ("genAI") took over our collective conscience, so this content and any corresponding code samples, codelab tutorials, and/or blog posts can be leveraged for finetuning LLMs (large language models) as well as by software engineers either building MCP (model context protocol) servers or guiding/correcting vibe code generation.

Featured videos & content

Most videos are generally part of a related series, whether to introduce API usage of a product family or having a common goal. Still others are one-offs, whether produced or recorded as part of a public presentation. Here are my top 8, each blessed with an "award category," and an honorable mention not produced by the Google developer studio team:

(BEST "ROAD SHOW") Creating events in Google Calendar
(BEST INTERN) Expediting expense reports with Gmail add-ons
(BEST "ACTING") Automating YouTube stats with Google Apps Script
(BEST "FIGHT [SCENE]") File Storage in the Cloud
(MOST "INTEROPERABLE") Deploy the same app to App Engine, Cloud Functions & Cloud Run
(MOST INTERESTING PORT) Migrate App Engine Users service to Cloud Identity Platform
(MOST VIEWED) Google Drive API: Uploading & Downloading Files
(MOST ASPIRATIONAL) Change the world in 10 lines of code
(HONORABLE MENTION) Building an AI-enhanced enterprise image processing workflow

Let's dive into each:

1. (BEST "ROAD SHOW") Creating events in Google Calendar

FEATURED: Calendar API
POST: Google Calendar API invites users to great experiences
WHY: Imagine building the next-generation travel app where your users book airfare, hotel, and car rental/hire, only to have to wait for the email confirmations from each, then enter the correct information into Google Calendar. Wouldn't it be better if you automated this step for them, and furthermore, updated those entries if/when plans change?
"AWARD:" Most of our videos are filmed in a studio with one or more producers guiding us through the process. Instead, we "went on-the-road" for this one, situating ourselves in one of Google's legendary cafes. The extras are colleagues, video production staff or fellow Developer Advocates joining me to show how to have a great experience together, in much the same way the Calendar API lets you give your users great experiences.
SEQUEL: "Modifying events with the Google Calendar API," and an accompanying blog post

2. (BEST INTERN) Expediting expense reports with Gmail add-ons

FEATURED: Google Apps Script (Gmail add-ons, Spreadsheet Service [Sheets API])
POST: Gmail Add-ons framework now available to all developers
CODELAB: Make email more actionable with Google Workspace Add-ons
SOURCE: Expense It! -- Gmail Add-ons Codelab
WHY: Gmail add-ons are a way to integrate your application with Gmail without requiring your users to leave Gmail. Imagine being able to process expense reports directly from Gmail while reviewing your confirmation emails. The add-on is able to extract all relevant data for each expense into their own rows in Google Sheets, expediting one of your least favorite chores when traveling for work.
"AWARD:" Another fun video outside the studio, this one features colleague Alison Carroll and my summer intern at-the-time, Sundar Solai, "No, not that Sundar," as he's often quoted. :-) He appears to be a little nervous in this video but passed with flying colors! More importantly, he built the entire Gmail add-on.

3. (BEST "ACTING") Automating YouTube stats with Google Apps Script

FEATURED: Google Apps Script (YouTube Data API Advanced Service)
POST: (A day at the office) Automating YouTube stats with Google Apps Script
WHY: One of the key reasons why Apps Script exists is to help GWS users automate tasks. Those who produce videos published on YouTube know that tracking metrics is a necessary KPI (key performance indicator) to determine if you're reaching your goals. However, this is a daunting task without automation, so this video shows how you can fetch the corresponding data for all videos listed in Google Sheets.
"AWARD:" Yet another video outside the studio, we wanted to portray how an analyst can quickly get on the "good side" of his boss in an "office space" by automating with Apps Script.

4. (BEST "FIGHT [SCENE]") File Storage in the Cloud

FEATURED: Google Drive API, Cloud Storage API, Cloud Persistent Disk API
WHY: Both Google Drive and Cloud Storage are object stores in-the-cloud. That said, how do they differ? Each has more applicable use cases, so this case study looks into when you would use each as well as what Cloud Persistent Disk is used for. NOTE: This video was produced before Cloud Filestore launched, and it would've been featured had it existed at the time.
"AWARD:" One of my earliest videos, this is essentially a "Google Drive vs. Cloud Storage" video. The challenge in making this content was that it required the buy-in from both the Google Drive and Cloud Storage teams, which at times didn't see eye-to-eye. To date, this is the only video ever produced by Google featuring both products receiving sign-off from both PMs (product managers).

5. (MOST "INTEROPERABLE") Deploy the same app to App Engine, Cloud Functions & Cloud Run

FEATURED: Google App Engine, Cloud Functions, Cloud Run, Cloud Translation API
POST: Exploring serverless with a nebulous app
CODELAB(s): multiple codelabs available
SOURCE: Python, Node.js
WHY: While App Engine was Google's original serverless platform (before that term was even coined), the next generation platforms, Cloud Functions and Cloud Run are similar yet different. Which platform is right for you? Can you make a mistake choosing the "wrong one?" This content serves as a "myth-buster" you can't laterally move across platforms by demonstrating an app that can be deployed across all three. NOTE: This content features the 1st-generation Cloud Functions platform before its 2nd-generation service was combined with Cloud Run and rebranded as "Cloud Run Functions."
"AWARD:" Prior to this content, Google had never showcased an application that could be deployed to all GCP serverless platforms with no code changes, demonstrating interoperability between them. A side goal of this content was to showcase how to call Google APIs from GCP serverless platforms... in this case, the closest API-equivalent for Google Translate, another interoperability nod.

6. (MOST INTERESTING PORT) Migrate App Engine Users service to Cloud Identity Platform

FEATURED: Google App Engine (Users API), Cloud Identity Platform (Firebase Authentication), Cloud Resource Manager (API)
POST: Migrate App Engine Users service to Cloud Identity Platform
CODELAB: Migrate from App Engine Users service to Cloud Identity Platform (Module 21)
SOURCE: Python 3, Python 2
WHY: Moving off App Engine's old "Users API" (think early version of Sign-In with Google for your App Engine apps) isn't that straightforward, especially since there's no GCP equivalent. The closest product in GCP to authentication service is the Cloud Identity Platform, the "enterprise" version of Firebase Authentication. Since neither product have anything in common, I bridged this gap as part of the code sample.
"AWARD:" There is literally no overlap between the App Engine Users API and the GCP version of Firebase Auth, Cloud Identity Platform (GCIP). In order to build this migration sample, I had to shift the functionality from server-side to client-side as well as create a proxy for the App Engine Admin role. So this was the most interesting port, because it was a code migration as well as some new code to make up for missing functionality.

7. (MOST VIEWED) Google Drive API: Uploading & Downloading Files

FEATURED: Google Drive API
POST: Google Drive: Uploading & downloading files plus the new v3 API redux
WHY: Almost a decade ago, Google launched the 3rd version of the Drive API. As there were some backwards-incompatible name changes from the v2 API, it was necessary to show developers some of the basics of using v3. I look forward to modernizing the code and making it available soon.
"AWARD:" Of all my videos, one of them has to be the most viewed, and not surprisingly, it's this one, which shows developers how to upload files to and download files from Google Drive. So far, it's garnered about a quarter-million views.
SEQUEL: "Introducing Shared (formerly Team) Drives" and an accompanying blog post
PREQUEL: "Listing your files in Google Drive," an accompanying blog post, codelab, and source code (Python)

8. (MOST ASPIRATIONAL) Change the world in 10 lines of code

FEATURED: Google App Engine (Inbound Mail API)
WHY: Another one of my earliest videos, this one highlights one of the lesser-known features of App Engine's original APIs, the inbound Mail API. We all easily understand the how and the why of sending email from an application, but having an app receive email (and process it)? Now that's another matter.
"AWARD:" Most people have the ability to use email from their computers or mobile devices. While sending email to people is something often done, imagine what you could do by sending email to an app. With the proper authorization, users can effect almost any action they can think of (provided there are apps that process inbound emails).

9. (HONORABLE MENTION) Building an AI-enhanced enterprise image processing workflow

FEATURED: Google Drive API, Cloud Storage API, Cloud Vision API, Sheets API (and later: Maps [Static] API, Gemini API)
POST: Image archive, analysis, and report generation with Google APIs
CODELAB: Image archiving, analysis, and report generation Google Workspace & Google Cloud
SOURCE: Python
WHY: With over a decade of experience working on various Google APIs, I wanted to create content leveraging APIs from different product groups to solve possible business problems. I imagine an employee (like myself) with over a decade of Google Drive usage. The "My Drive" page is rife with numerous folders, preventing me from seeing documents I most recently worked on. Those in asset-heavy industries like manufacturing, advertising, architecture, and the media would have even more "clutter." There must be a way to safely backup these assets and clean up your Google Drive so it becomes useful again, and that's what this code sample does.
"AWARD:" This video should get "most interoperable" because it demonstrates how to use APIs from both GCP & GWS to solve a potential enterprise problem. Images are downloaded from Google Drive, backed up to Cloud Storage, analyzed with Cloud Vision (and in the future, Google Maps and Gemini), annotated in Google Sheets, including links to the archived locations in Cloud Storage. Detailed records are saved, allowing for asset folders to be deleted, de-cluttering users' Google Drives. However, I didn't get a chance to craft a proper developer video and can only link to the only public recording of me covering this topic. Since that time, I've further enhanced the app by adding the use of the Google Maps Static and Gemini APIs to the original code sample to bring it into the genAI era. All-in-all, it is now a solution that demonstrates six different Google APIs in a single solution for a potential business problem.

Summary

So there you have it, the top 8 (well, 9) videos I produced to help developers use various Google developer platforms & APIs. I hope to further explore each of them in more detail, including modernizing the code samples for today's developer, whether for custom MCP servers or to calibrate or fix generated vibe code. More information on these videos as well as all of the others I produced during my time at Google can be found in the entire video catalogue.

If you found an error in this post or have a topic I should cover, drop a note in the comments below or file an issue at the repo. I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

References

Below are various resources related to this post which you may find useful.

Miscellaneous

Entire video catalog

GWS APIs

GCP APIs

Serverless

(Predictive) AI/ML

Storage

Other GCP

Gmail API developer intro: spotting chatty threads

Wesley Chun (@wescpy) — Wed, 06 Aug 2025 07:53:08 +0000

Primer on using the Gmail #API... TL;DR:

Google Workspace (GWS) APIs like Drive, Docs, and Sheets can be useful for processing documents. GWS also does messaging, e.g., Gmail, Chat, and Meet, so let's take a look, starting with Gmail. A decade ago today, I posted about the Gmail API for the first time. It's time to modernize that content & code sample to the current ecosystem so Python & Node.js developers know how to use the API to query inboxes looking for "chatty threads," those that have at least 3 messages. While it's a "Hello World" 102 sample, it gets you started building automated workflows or creating Gmail-related MCP servers for your AI agentic apps.

Introduction and motivation

Welcome to the blog focused on using Google APIs from Python (and sometimes Node.js) covering different parts of Google's developer ecosystem, from APIs to compute and AI/ML platforms where I "oil" the squeaky parts to smoothen onboarding friction. I especially like to cover content that's not in Google's documentation. Here are the topics I've covered thus far:

Google Cloud/GCP: AI/ML, serverless
Google Workspace/GWS: Gmail, Drive, Sheets, etc. (this series)
YouTube
Maps
Generative AI ("genAI") with Gemini
Credentials: API keys, OAuth client IDs, service accounts
Old vs. new (client) libraries: Python auth, Gemini API

Workspace itself is a platform with many applications (and corresponding APIs). With enough coverage on documents, it's time to take a look at messaging, starting with the Gmail API.

Background

It was exactly a decade ago to this day when I published the original version of this blog post. To be honest, the code hasn't changed much at all. The client libraries are different along with some minor improvements, but the core application remains intact. Today I'm happy to reprise that sample app, make it available in Node as well as provide modernized Python versions.

The purpose of the original post was meant to justify why Gmail should have an API. Back then without an API, there was no ability to access user inboxes or Gmail features. The only option for developers at the time was to use standard email protocols like SMTP, IMAP, and POP. Unfortunately, they only operate at the message level. They have no clue about email threads, signatures, search, labels, filters, etc. Some of these motivations are addressed in the original Gmail API launch video.

Updated (permission) scopes

Scopes background

Permission scopes are URL-type strings that represent the permissions your app requests from end-users. They're "URLs" not for HTTP communication but rather, are universal representations that get converted to end-user locale-compliant human-friendly strings.

For example, the Google Drive metadata read-only scope is represented by https://www.googleapis.com/auth/drive.metadata.readonly. In English-speaking countries, it's rendered to users as See information about your Google Drive files in OAuth permission request dialogs (which you're probably already familiar with):

[IMAGE] OAuth2 authorization dialog

The text would be different (obviously) if your locale was not English. More on scopes is found in the OAuth client ID (part 3) post if you're new to this concept. All scope "URLs" and their human-readable equivalents can be found in the full list of all Google API OAuth2 scopes. Google also has an OAuth2 best practices & policies page which is worth reviewing as well.

Gmail API scopes

A decade ago, there were only seven (7) scopes available for developers. That number has doubled as of the time of this publication. All are listed in the API documentation.

In addition to new scopes, Google has since introduced scope categories, indicating the sensitivity level user data accessed by the API. The tiers include (in order of least-to-most sensitive):

Non-sensitive
Sensitive
Restricted

This is a sampler of Gmail API scopes (in no particular order) and their sensitivity classifications:

[IMAGE] Gmail API OAuth2 scopes

As you can expect, the more sensitive the scope, the more restrictive access must be for user safety & security. For developers, this translates to more scrutiny via app verification should you decide to launch a public app.

Updated code samples (from original)

Python

Current auth library (recommended; Python 2/3)
Old auth library (most similar to original; Python 2/3)
Modern Python 3-only (async, type annotations, f-strings)

Node

Modern JavaScript ECMAscript module (.mjs)
CommonJS script (.js)

This table lists and describes each of the samples in the repo along with configuration files for this post.

Sample	Description
Python (current auth libs)
`gmail_chatty_threads.py`	Python 2 & 3 combo version using current auth libs (`google.auth`)
`gmail_chatty_threads-3async.py`	Modern Python 3-only (async, annotated) version using current auth libs (`google.auth`)
`requirements.txt`	3rd-party packages requirements with current auth libs
Python (old auth libs)
`gmail_chatty_threads-old.py`	Python 2 & 3 combo version using old auth libs (`oauth2client`)
`requirements-old.txt`	3rd-party packages requirements with old auth libs

Node
`gmail_chatty_threads.mjs`	ECMAScript module
`gmail_chatty_threads.js`	CommonJS script
`package.json`	3rd-party packages requirements

Configuration

Python `requirements.txt`

The requirements.txt file specifies the 3rd-party packages required to run the Python scripts using the current auth library, gmail_chatty_threads.py and gmail_chatty_threads-3async.py:

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

The google-api-python-client is the all-purpose Google APIs client library for Python. The google-auth-httplib2 and google-auth-oauthlib packages are the new/current auth libraries for transport (HTTP) and OAuth2, respectively.

Python `requirements-old.txt`

The requirements-old.txt file is similar to requirements.txt except it contains 3rd-party packages for the previous auth library and is for the "old" version of the script, gmail_chatty_threads-old.py:

google-api-python-client
oauth2client

The google-api-python-client package is the same Google APIs Python client library as above, while oauth2client is the older, deprecated auth library. Keep an eye out for the sidebar on oauth2client coming up soon.

Node `package.json`

The package.json file is the equivalent for Node... 3rd-party packages required to run both scripts, gmail_chatty_threads.mjs and gmail_chatty_threads.js:

{
  "dependencies": {
    "@google-cloud/local-auth": "^3.0.1",
    "googleapis": "^144.0.0"
  }
}

The @google-cloud/local-auth package is the current auth library for Node while googleapis is the Google APIs client library for Node. There's also one for client-side/front-end Javascript if you need it, but that isn't part of today's coverage. The version numbers listed are the latest at the time of publication (and subject to change in the repo).

Application source code

Python (current auth)

The main Python version is gmail_chatty_threads.py, modernized from the original yet still Python 2 backwards-compatible. Taking it one chunk at a time:

from __future__ import print_function
import os

from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow as InstAppFlow
from googleapiclient import discovery
from google.oauth2.credentials import Credentials

The Python Standard Library imports are the 3.x print()-function for 2.x and the os module because we (the developers) need to manage the OAuth tokens ourselves. (Neither token management code nor this import are necessary when using the old auth library.) The remaining imports are the various Google client libraries needed for OAuth2 and API access.

📝 Python 2 and 3 supported
Most of the world is on Python 3 today, but there are still some with dependencies on 2.x that make migration challenging. This is why I aim to create Python 2-3 compatible samples, to help those continuing to migrate. There's also a modern Python 3-only sample with newer features like `async/await`, type annotations, `f`-strings, etc. for those who don't care about 2.x support.

creds = None
SCOPES = 'https://www.googleapis.com/auth/gmail.metadata'
TOKENS = 'storage.json'  # where to store access & refresh tokens
if os.path.exists(TOKENS):
    creds = Credentials.from_authorized_user_file(TOKENS)
if not (creds and creds.valid):
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow: InstAppFlow = InstAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
        creds = flow.run_local_server()
with open(TOKENS, 'w') as token:
    token.write(creds.to_json())
GMAIL = discovery.build('gmail', 'v1', credentials=creds)

The security code checks credentials from the locally-stored OAuth2 TOKENS file. If it exists, read the OAuth tokens from it. If they exist but are invalid, use the refresh token to get a new access token, necessary for API access.

If non-existent, build the flow from the client ID & secret in client_secret.json and the requested permission SCOPES (the Gmail metadata scope for this sample), and run the flow, resulting in the earlier OAuth2 dialog prompting the user to grant your app permission to access their Gmail (meta)data.

Rest of Application

threads = GMAIL.users().threads().list(userId='me').execute().get('threads', [])
for thread in threads:
    tdata = GMAIL.users().threads().get(userId='me',
            id=thread['id'], format='metadata').execute()
    nmsgs = len(tdata['messages'])
    if nmsgs > 2:
        msg = tdata['messages'][0]['payload']
        subject = ''
        for header in msg['headers']:
            if header['name'] == 'Subject':
                subject = header['value']
                break
        if subject:
            print('-% 3d msgs: %s' % (nmsgs,
                    subject if len(subject)<45 else '%s...' % subject[:42],))

The core part of the application scans email threads in your inbox (per userId='me') and individual messages in each thread. The first API call gets the latest 100 (default) threads. Don't like the default? Provide a maxResults parameter (between 1-500) to GMAIL.users().threads().list() to scan a different number of threads.

For each thread, make an API call to get its messages, dropping it if there aren't more than 2 messages. Once you have a thread with at least 3 messages, scan its headers looking for a Subject line and save the value. Also drop the thread if the Subject line is blank.

For all threads with at least 3 messages and a non-empty Subject line, display the number of threads and its Subject line, truncating the latter after 42 characters (and add 3 ellipses) if more than 45 characters long.

Python (old auth)

This version is the closest analog to the sample in the original post? The only changes are the imports, the security code (including the name change from apiclient to googleapiclient), and use of the new Gmail metadata scope (vs. the read-only scope). Below is old auth security snippet found in gmail_chatty_threads-old.py:

from __future__ import print_function

from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools

# check credentials from locally-stored OAuth2 tokens file; either
# refresh expired tokens or run flow to get new pair & create API client
SCOPES = 'https://www.googleapis.com/auth/gmail.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_secret.json', SCOPES)
    creds = tools.run_flow(flow, store)
GMAIL = discovery.build('gmail', 'v1', http=creds.authorize(Http()))

The rest of the script is identical; this one is also Python 2-3 compatible. I recommend using this version only if you have other code relying on the older auth library, otherwise it's always best to use the latest stuff.

💥 Caveat: `oauth2client` deprecated
The older Python auth library, `oauth2client`, was deprecated in 2017. However the current library does not support OAuth token storage, hence why `*-old.py` samples like the above are shorter than their modern equivalents. For now, `oauth2client` still works, even in maintenance mode, and provides threadsafe and 2.x/3.x-compatible storage of and access to OAuth2 tokens. This post sheds more light on this change. Google won't provide migration guides showing "before & after," so their "dirty little secret" is one of the reasons why I'm here. It helps both developers and vibecoding LLMs understand this transition so all can produce modern code or migrate/fix old library code.

💥 Caveat: oauth2client deprecated

The older Python auth library, oauth2client, was deprecated in 2017. However the current library does not support OAuth token storage, hence why *-old.py samples like the above are shorter than their modern equivalents. For now, oauth2client still works, even in maintenance mode, and provides threadsafe and 2.x/3.x-compatible storage of and access to OAuth2 tokens. This post sheds more light on this change. Google won't provide migration guides showing "before & after," so their "dirty little secret" is one of the reasons why I'm here. It helps both developers and vibecoding LLMs understand this transition so all can produce modern code or migrate/fix old library code.

Around the time of the original post, I produced a video recap of this (version of the) app and motivation behind it; embedding it here in case this context can be useful. (NOTE: There's a special bonus US history lesson embedded at the end... hope you learn something non-technical from me too!)

Python 3-only

The last version is for those with "no baggage," meaning no dependencies on Python 2 or older auth libraries. It's the modern Python 3 version. Because of the (numerous) type annotations, this is the entire gmail_chatty_threads-3async.py script:

import asyncio
import os
from typing import Any, Dict, List, Set, Optional

from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow as InstAppFlow
from googleapiclient import discovery
from google.oauth2.credentials import Credentials

creds: Optional[Credentials] = None
SCOPES: str = 'https://www.googleapis.com/auth/gmail.metadata'
TOKENS: str = 'storage.json'  # where to store access & refresh tokens
if os.path.exists(TOKENS):
    creds = Credentials.from_authorized_user_file(TOKENS)
if not (creds and creds.valid):
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow: InstAppFlow = InstAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
        creds = flow.run_local_server()
with open(TOKENS, 'w') as token:
    token.write(creds.to_json())
GMAIL: Any = discovery.build('gmail', 'v1', credentials=creds)

async def proc_thread(thread: Dict[str, Any]) -> None:
    'process msgs for a thread'
    tdata: Dict[str, Any] = GMAIL.users().threads().get(
            userId='me', id=thread['id'], format='metadata').execute()
    nmsgs: int = len(tdata['messages'])
    if nmsgs > 2:
        msg: Dict[str, Any] = tdata['messages'][0]['payload']
        subject: str = ''
        for header in msg['headers']:
            if header['name'] == 'Subject':
                subject = header['value']
                break
        if subject:
            print(f'-{nmsgs: 3d} msgs: '
                  f'{subject if len(subject)<45 else "%s..." % subject[:42]}')

async def main() -> None:
    threads: List[Dict[str, Any]] = GMAIL.users().threads().list(
            userId='me').execute().get('threads', [])
    tasks: Set[asyncio.Task[None]] = {
            asyncio.create_task(proc_thread(thread)) for thread in threads}
    await asyncio.gather(*tasks)

if __name__ == '__main__':
    asyncio.run(main())

JavaScript/Node.js

There are 2 versions of the Node version of the script, gmail_chatty_threads.mjs and gmail_chatty_threads.js. The only difference between them are the how the 3rd-party packages are "brought into" each script:

import fs from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { authenticate } from '@google-cloud/local-auth';
import { google } from 'googleapis';

The first 4 imports are for OAuth authorization while the last is for the API client library. You can switch the app to a CommonJS script by swapping out the imports for the following require() calls:

const fs = require('fs').promises;
const path = require('path');
const process = require('process');
const { authenticate } = require('@google-cloud/local-auth');
const { google } = require('googleapis');

The rest of the application is identical for both versions. (Readers can file a PR if you convert either one [or both] to Typescript.)

const CREDENTIALS_PATH = path.join(process.cwd(), 'client_secret.json');
const TOKEN_STORE_PATH = path.join(process.cwd(), 'storage.json');
const SCOPES = ['https://www.googleapis.com/auth/gmail.metadata'];

async function loadSavedCredentialsIfExist() {
  try {
    const content = await fs.readFile(TOKEN_STORE_PATH);
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    return null;
  }
}

async function saveCredentials(client) {
  const content = await fs.readFile(CREDENTIALS_PATH);
  const keys = JSON.parse(content);
  const key = keys.installed || keys.web;
  const payload = JSON.stringify({
    type: 'authorized_user',
    client_id: key.client_id,
    client_secret: key.client_secret,
    refresh_token: client.credentials.refresh_token,
    access_token: client.credentials.access_token,
    token_expiry: client.credentials.token_expiry,
    scopes: client.credentials.scopes,
  });
  await fs.writeFile(TOKEN_STORE_PATH, payload);
}

async function authorize() {
  var client = await loadSavedCredentialsIfExist();
  if (client) return client;
  client = await authenticate({
    scopes: SCOPES,
    keyfilePath: CREDENTIALS_PATH,
  });
  if (client.credentials) await saveCredentials(client);
  return client;
}

The security block of code is slightly longer than for Python as it's broken up into multiple async functions. The core function is authorize(), so start with that as it calls all the others as-necessary to check the saved OAuth tokens for validity, refreshing if possible but creating a new flow and getting new credentials if required. Regardless of how valid credentials are obtained, they're returned by authorize().

async function gmailThreads(authClient) {
  const GMAIL = google.gmail({ version: 'v1', auth: authClient });
  var res = await GMAIL.users.threads.list({ userId: 'me' });
  const threads = res.data.threads;
  if (!threads || threads.length === 0) return;

  for (const thread of threads) {
    var res = await GMAIL.users.threads.get({
      userId: 'me',
      id: thread.id,
      format: 'metadata'
    });
    var tdata = res.data;
    var nmsgs = tdata.messages.length;

    if (nmsgs > 2) {
      var msg = tdata.messages[0].payload;
      var subject = '';
      for (const header of msg.headers) {
        if (header.name == 'Subject') {
          var subject = header.value;
          break
        }
      }
      if (subject) {
        console.log(`-${String(nmsgs).padStart(3, ' ')} msgs: ` +
          `${(subject.length < 45) ? subject : (subject.slice(0, 42)+'...')}`);
      }
    }
  }
}

authorize().then(gmailThreads).catch(console.error);

The main driver gets valid credentials from a call to authorize() then passes them onto gmailThreads(). Like the Python version, it fetches the first 100 threads from the user's Gmail inbox then looks for threads with more than 2 messages, looping through those and saving non-empty Subject lines, truncated to 42 characters (plus ellipses) if more than 45 characters long, and displays them to the user.

⚠️ ALERT: Cost: "free" up to certain limits
While many Google products & APIs are free to use, not all of them are. While not totally "free," use of GWS APIs is covered by your monthly "subscription," whether you're a paid subscriber or have a free consumer Google account (with or without Gmail, which is optional), meaning a $0USD monthly subscription rate.

This "free" usage is not unlimited however... stay within the established quotas for each API. As expected, paid subscribers get more quota than free accounts. While not broadly published, you can get an idea of the limits on the Quotas page for Google Apps Script.

Prerequisites/required setup

Now that you know what the code does, it's time to run it yourself. To do so, perform the required setup:

Create a new project or reuse an existing one
- Enable the Gmail API
- Create OAuth client ID & secret credentials
Install the Google APIs client library

Get your project setup. Once that's done, enable the API and create the credentials. You can do it in either order (but can't do either if you don't have a project). Installing the client library can be done before or after specifying a project. Per the sidebar above, use of the Gmail API is "free."

Below are more specific instructions. Some have alternatives, say command-line vs. console, so choose what you're most comfortable with.

System requirements
- For Python 2 specifically, that means 2.7 only.
- For Python 3, I strongly suggest 3.9 or newer.
- For Node.js, I suggest 16 or newer.
Create a new project from the Cloud/developer console or with gcloud projects create . . .; or reuse an existing project
Enable the Gmail API. Pick your preferred method of these three common ways to enable APIs:
- DevConsole manually -- Enable the API manually from the DevConsole by following these steps:
  1. Go to DevConsole
  2. Click on Library tab in the left-nav; search for "Gmail", and enable
- DevConsole link -- You may be new to Google APIs or don't have experience enabling APIs manually in the DevConsole. If this is you...
  1. Check out the API listing page to learn more about the API and enable it from there.
  2. Alternatively, skip the API info and click this link for the enable button.
- Command-line (gcloud) -- Those who prefer working in a terminal can enable APIs with a single command in the Cloud Shell or locally on your computer if you installed the Cloud SDK which includes the gcloud command-line tool (CLI) and initialized its use.
  1. If this is you, issue this command to enable the API: gcloud services enable gmail.googleapis.com
  2. Confirm all the APIs you've enabled with this command: gcloud services list
Create OAuth client ID & secret credentials and save the file to your local filesystem as client_secret.json. The code samples will not run without this file present.
Install the Google APIs client library:
- Node: Install required packages with:
  - npm i
- Python 2 or 3 (new auth): In your normal or virtualenv environment, install the current/new Python auth libraries (most everyone):
  - pip install -Ur requirements.txt (or pip3)
  - uv pip install -Ur requirements.txt (if you use uv in a virtualenv)
  - Manually install packages by name (see requirements.txt)
- Python 2 or 3 (old auth): If you have dependencies on the older Python auth libraries and/or still have old code lying around that do (see warning sidebar below), run this instead:
  - pip install -Ur requirements-old.txt (or pip3)
  - uv pip install -Ur requirements-old.txt (if you use uv in a virtualenv)
  - Manually install packages by name (see requirements-old.txt)

Running the script

The first time you run the script, you have to complete the OAuth authorization flow and give the code permission to access your Gmail metadata. If you're new to this process, see this section of the Drive API intro post because the instructions and user experience are nearly identical.

When you've given your authorization, you should see the most chatty threads in your inbox. For my Gmail mailing list account, I got the following results from one the Python versions -- all work the same and produce similar output:

$ python3 gmail_chatty_threads.py
-  9 msgs: Re: How to manipulate PDF documents in Deb...
- 13 msgs: Re: please delete me from your mailing lists
-  6 msgs: Re: Bookworm libc6 (and libc6:i386) update...
- 28 msgs: Re: Is there a POSIX compliant way of turn...
- 10 msgs: Re: problem installing trixie - no EFI
- 22 msgs: Re: Where does pure-ftpd store files when ...
-  9 msgs: Re: Why are bug comment numbers multiples ...
- 34 msgs: SDD partitioning and allocations

So out of 100 threads, there were only 8 with more than 2 messages, meaning the other 92 didn't have more than a single reply, if any. Congrats, you now know the basics of using the Gmail API and can continue exploring other features of the API, or build something specific for your organization or your customers, including morphing your solution into an MCP server for agentic apps.

Summary

This post introduces developers to the Gmail API, demonstrating code that queries for and displays the "chatty email threads" in the user's inbox. Several versions are available in both Python & Node along with a description of how the code works. These sample apps were based on the original app published in the original blog post from a decade ago.

All of the code was hand-written by me with the exception of the modern Python 3-only version. I copied the "current auth" version and changed it to use async/await then added f-string support. Finally, I prompted the Cursor AI IDE (integrated development environment) to: "Take the code for gmail_chatty_threads-3async.py and add full type annotations to it," resulting in the version in the repo. I could've done it on my own, but that's tedious, and I'm impatient. :-)

If you found an error in this post, a bug in the code, or have a topic I should cover, drop a note in the comments below or file an issue at the repo. I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

📝 Service account alternative in API docs
Around the time of the original post & video, I created an alternative Python version of the app using service account auth which was added to the Threads page of the documentation. While OAuth client IDs are standard for user permission, service accounts are useful for Workspace administrators performing tasks for multiple GWS domain users without needing to request individual user permission to perform actions on their behalf; this is known as domain-wide delegation ("DWD"). I'll cover the differences and conversion between user & service account auth in a future post. For now, that alternative sample in the docs (ported to the current auth library) suffices. Impatient? Check this post and code repo which has samples in all 4 combinations (and more): old auth vs. new auth and OAuth client IDs vs. service accounts credentials.

📝 Service account alternative in API docs

Around the time of the original post & video, I created an alternative Python version of the app using service account auth which was added to the Threads page of the documentation. While OAuth client IDs are standard for user permission, service accounts are useful for Workspace administrators performing tasks for multiple GWS domain users without needing to request individual user permission to perform actions on their behalf; this is known as domain-wide delegation ("DWD"). I'll cover the differences and conversion between user & service account auth in a future post. For now, that alternative sample in the docs (ported to the current auth library) suffices. Impatient? Check this post and code repo which has samples in all 4 combinations (and more): old auth vs. new auth and OAuth client IDs vs. service accounts credentials.

References

Below are various resources related to this post which you may find useful.

Code samples

Related code samples & content

Original (previous auth) version in blog post
Current auth version using service accounts in API docs (repo link)
YouTube video

Gmail API

GWS APIs & OAuth2 information

Google APIs client libraries

Gemini 2.5 API Missing Manual: How to get started (or upgrade from Gemini 1.0/1.5)

Wesley Chun (@wescpy) — Wed, 16 Jul 2025 04:55:48 +0000

TL;DR:

This "missing manual" shows you how to upgrade code from the "old" Gemini 1.0/1.5 days. It's also for those new to the API because it collates various "Hello World!" samples together into one post (& repo), regardless of what platform you use. That's right, Google makes the Gemini API available from two completely different places! This post is both a beginners' guide and a migration guide you won't find in the documentation. Now Google did the right thing by unifying under a single client library for both platforms, and while it's better than two platforms and two libraries and old samples living forever online, the worse thing is: vibecoding LLMs were trained on all that! This post aims to provide a solid understanding of how the old libraries worked and how to use the current one. Most importantly, you'll have the knowledge to modernize old code, whether written by humans or LLM-generated.

UPDATE (Aug 2025): This post does not cover Nano Banana, the Gemini 2.5 Flash Image model, which has advanced features not available in previous or other models. It can effectively "make changes" to existing images, blend artifacts from multiple images, and allow for continuing edits. Code samples and features coming in a future blog post. Developers can access the Gemini 2.5 Flash Image preview model today via gemini-2.5-flash-image-preview.

Introduction

Welcome to the blog covering Google APIs for Python (and sometimes Node.js) developers. You'll learn how to code a variety of APIs from different product families (see below), for new or existing applications (including MCP servers & agents):

Google Cloud/GCP (AI/ML, serverless)
Google Workspace/GWS (Drive, Docs, Sheets, Gmail, etc.)
YouTube
Maps
Generative AI with Gemini (this series)
Credentials (API keys, OAuth client IDs, service accounts)

We return to Gemini again in this post, covering the updated client libraries coinciding with the 2.0 release.

Background

Besides model updates, Google tweaked the way developers access the Gemini API since last year, all for the better I think. For long-time API users, we'll "modernize" old library code samples for 2.0/2.5, and for everyone else, we'll get you started using the API with the current library today!

In the original post, I griped that Google makes the API accessible from two different platforms:

Google AI ("GAI")
Vertex AI (Google Cloud/"GCP")

While that hasn't changed, it's clear each has a different purpose:

Google AI: Experimenting, free tier/lower cost, lower barrier-to-entry, hobbyists/students
Vertex AI: Production AI workloads, existing GCP customers adding/considering AI capabilities

What's changed?

So why this post? A couple of things have changed since then:

Updated Gemini models
Updated (old) and new API client libraries

Let's start with the updated models, recognizing the elephant in the room is the 2nd one. I'll discuss both briefly then dive into a full migration guide featuring code for both GAI and GCP using the old/discrete client libraries and also the current/unified client libraries.

Updated Gemini models

All models undergo periodic updates, and Gemini is no exception: 1.0 was released at the end of 2023. A few months later, we got 1.5; 2.0 came out just before the end of 2024, and earlier this year, we got the reasoning 2.5 models. Things change quickly in the world of AI, and the API needs to keep up.

I updated the original post (simple text queries) samples from 1.0 to 1.5 without drama, then covered other use cases like multimodal support, chat (multi-turn conversations), etc. Basic use cases like this only require a change of model name in the samples, so you're good-to-go even when models are updated.

That let me focus on important new features of the 2.0 models, like generating audio and images. The 2.0 release coincided with the new consolidated client library. While that was great, I knew I had to discuss the old libraries and migration at some point, so I "kicked the can down the road," so here we are.

Updated (old) and current/new API client libraries

The good news: unified client library

It's confusing when an API is accessible from different platforms (from the same company no less), but that's where we find ourselves today: a pair of (different) client libraries, twice the number of the code samples, documentation, open source repos, the whole lot. This duality results in a less-than-optimal UX (user experience), especially for
those who aren't aware it's available from two platforms and wondering why a web search or vibecoding requests result in code samples or documentation for one, then the other, all unpredictably if your web query or LLM-prompt isn't specific enough.

Over time, Google realized maintaining separate libraries wasn't a good idea, requiring near-duplicate engineering effort. The solution is a single, unified client library supporting both GAI & GCP so all users get a consistent experience. In the end, this is a good thing, for code reuse & maintenance as well as allowing users to transition between platforms as needed, say when going from GAI for dev to GCP for production. There are still minor differences using the unified library on both platforms as we'll soon see, but still, it's a great improvement. Thanks Google!

The bad news: users uninformed, old library samples linger, etc.

The new library went public towards the end of 2024 with the initial docs coming a month later. No public announcements were made for either however. Some words about the new library, deprecation of the old ones, migration guides, timeline, etc., would have been helpful. Users are redirected to the new library docs, but no notice about deprecating the old ones appeared until a mid-2025 README update. At least, there's some closure, and those are some of the reasons why this post exists.

More bad news: although Google removes old samples from their docs, that has no effect on what people have written and posted online. Those will live forever. Even worse, those samples were and are used to train the LLMs your favorite vibe-coding tool uses. Old sample code and poorly-trained LLMs worsen the UX and simply cause user confusion. My other reason for this "public service announcement:" to future-train LLMs so they know how to produce modern code samples, and fix old samples written by humans or incorrectly-generated code by (other) LLMs.

If this story of old vs. new libraries sounds familiar, it's essentially the exact same topic as my post from last month. The difference? This is another Google product.

Migration guides? Inconsistent. Incomplete. Where?

For that (auth libraries) deprecation, users have no recourse as there's no migration guide at all (and why that post exists). For this Gemini API library update, Google didn't announce one but produced two migration guides, and neither are easy to find, so here are some convenience links:

Both guides have "before" and "after" code samples, which is very useful. Unfortunately they're inconsistent and incomplete. Examples (already filed bugs/feedback):

GAI 1: in the "API access" section at the top, the "before" sample shows how to request a specific model ('gemini-1.5-flash'), but where is that in the "after"?
GAI 2: the Python "Authentication" section states: The old SDK handled the API client object implicitly." It should add the you have to pass in the API key explicitly whereas in the current library, it's optional, and you can opt to use GEMINI_API_KEY instead. The Python "Generate content" section states: Previously, there were no client objects, you accessed APIs directly through GenerativeModel objects. So yes, you actually get a genai.Client object with the new library and make calls with it, the GenerativeModel objects in the old library serve the same purpose: allowing you to make API calls, meaning this shouldn't have been called out. To better "match" both samples, they should've passed in the API key using the new library and mention the environment variable option. Otherwise, it's not a true before & after.
GCP 1: Only the Grounding section shows users how to create a client properly using the new library. I understand not repeating throughout, but if you only want to put it in one place, perhaps somewhere near the top after the "Installation" and not randomly most of the way down the page?
GCP 2: in the Context caching section, Create and Get in "before" features calls to vertexai.init() but none of the others. Perhaps list it once in the Imports section or in every section? (Why be so inconsistent?) That's one thing. Another thing: where are the equivalent "init" calls in the "after" sections? Create has client = genai.Client(http_options=HttpOptions(api_version="v1")) which is not the same as client = Client(vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION), but that's not in any other other sections either. I think what's currently there (with http_options) is a mistake and should be the latter. The parameters are completely different.

Those are just the few I found. Having "before" and "after" examples are great, but the examples are inconsistent. They're also incomplete because some have more code than others; they're not giving everyone the whole picture. I'm not asking they be repetitive but provide enough context.

📝 NOTE: All new human-generated code
Human-generated: All the code below is new and written personally by me... I have a need to be precise and consistent, so vibe-coding isn't a good use case here. In fact, this post is meant to future-train coding LLMs to not use old libraries and/or self-correct what they output if trained on old code.

Even the "old" code is new: The "old" code below is also newly-written in case any samples changed from the original post. After all, the old client libraries themselves could have been updated since that post. What you'll find in the "old" samples here is what your code would look like if you coded them today using the final release of the older libraries.

Prerequisites

I don't know where all you readers are coming from nor where you run (or want to run) your apps (GAI and/or GCP), so I'm going to provide all the code and all the instructions. Regardless of which you use (or both), there are a pair of basic requisites:

Set auth credentials
Install required packages

⚠️ Required credentials
GAI: API key is required. Follow the instructions below. The GAI scripts will *not* run without an API key which should be either assigned to the `GEMINI_API_KEY` environment variable or saved to a local file, `.env` (Node.js) or `settings.py` (Python).
GCP: User auth via ADC for local dev environments is required to run the old client library code and recommended for current library code. The current library also supports API keys, but user auth/ADC is still recommended (more secure). (For production, use service accounts.)

💰 Cost considerations
GAI: Google AI has a free tier; see its pricing page for more information.
GCP: Vertex AI does *not* have a free tier, and an active billing account is required, so definitely check out its pricing page to find out how much it'll cost to run the GCP scripts.

Code samples table of contents

Code is available in Python 3 & Node.js, the latter as both ECMAscript modules as well as CommonJS scripts, plus corresponding configuration files.

Script applications

To compare like-scripts, the old client library version sits above its current client library equivalent.

Client library	Python	ECMAscript	CommonJS
GAI
GenerativeAI (old)	`gem25txt-simple-gai-old.py`	`gem25txt-simple-gai-old.mjs`	`gem25txt-simple-gai-old.js`
GenAI (current)	`gem25txt-simple-gai-cur.py`	`gem25txt-simple-gai-cur.js`	`gem25txt-simple-gai-cur.mjs`

GCP
VertexAI (old)	`gem25txt-simple-gcp-old.py`	`gem25txt-simple-gcp-old.mjs`	`gem25txt-simple-gcp-old.js`
GenAI (current)	`gem25txt-simple-gcp-cur.py`	`gem25txt-simple-gcp-cur.mjs`	`gem25txt-simple-gcp-cur.js`

Configuration files

The config files include old & current client library packages and apply to both platforms.

Description	Python	Node.js
Packages	`requirements.txt`	`package.json`
Settings	`settings_TMPL.py`	`.env_TMPL`

General instructions (GAI & GCP)

Node.js

Ensure your Node (and NPM) installation is up-to-date (recommend 18+)
Install all packages (old & new client libraries): npm i

Python

Ensure your Python (and pip) installation is up-to-date (3.9+ recommended)
(optional) Create & activate a virtual environment ("virtualenv") for isolation
- python3 -m venv .myenv; source .myenv/bin/activate
- For the commands below, depending on your system configuration, you will use one of (pip, pip3, python3 -m pip), but the instructions are generalized to pip.
(optional) Update pip and install uv: pip install -U pip uv
Install all packages (old & new client libraries): uv pip install -Ur requirements.txt (drop uv if you didn't install it)

GAI-specific instructions

Set credentials: Create API key (or reuse existing one).
Either save the API key to GEMINI_API_KEY environment variable or copy the template for your language .env_TMPL (Node) or settings_TMPL.py (Python) file to .env (Node) or settings.py (Python) and assign the key to API_KEY.
- If using the GEMINI_API_KEY environment variable, simplify the code to not look in .env or settings.py before running (use commented-out line). (This only affects scripts named gem25txt-simple-gai-cur.*.)
Run any of the scripts, e.g., node gem25txt-simple-gai-old.mjs, python3 gem25txt-simple-gai-cur.py, etc.

GCP-specific instructions

Set credentials: Login with user auth & set ADC for local dev environment.
- The new client library supports API keys, so if you prefer this, then follow the GAI instructions above.
Copy the template for your language .env_TMPL (Node) or settings_TMPL.py (Python) file to .env (Node) or settings.py (Python), respectively, and set the values for YOUR_GCP_PROJECT and YOUR_GCP_REGION (more on both later).
- If using an API key instead of ADC, assign it to API_KEY in .env (Node) or settings.py (Python), and update the code to use it before running (use commented-out line). (This is only supported by current library samples, e.g., scripts named gem25txt-simple-gcp-cur.*.)
- As a GCP service, you should use service accounts in production. (I don't believe Google has documentation on how to do this, so I may have to do so in an upcoming post. Add a comment below linking to a page in the docs if you know of or find one.)
Run any of the scripts, e.g., node gem25txt-simple-gcp-cur.js, python3 gem25txt-simple-gcp-old.py, etc.

Configuration files

Python

google-cloud-aiplatform         # GCP: old
google-generativeai             # GAI: old
google-genai                    # GAI & GCP: current

requirements.txt

API_KEY = 'YOUR_API_KEY'
GCP_METADATA = {
    'project':  'YOUR_GCP_PROJECT',
    'location': 'YOUR_GCP_REGION',
}

settings_TMPL.py

Node.js

{
  "dependencies": {
    "@google-cloud/vertexai": "^1.10.0",
    "@google/genai": "^1.8.0",
    "@google/generative-ai": "^0.24.1",
    "dotenv": "^17.0.1"
  }
}

package.json

API_KEY="YOUR_API_KEY"
GCP_METADATA='{
  "project": "YOUR_GCP_PROJECT",
  "location": "YOUR_GCP_REGION"
}'

.env_TMPL

For the 3rd-party package files requirements.txt (Python) and package.json (Node):

google-generativeai -- old GAI client library
google-cloud-aiplatform -- old GCP client library
google-genai -- current client library for both GAI & GCP

The versions listed above for package.json are the latest at the time of publication.

For the metadata files, settings.py (Python) and .env (Node) (appended with _TMPL for "template"):

API_KEY -- the API key string you created; required for GAI and optional for GCP; remove it if not applicable
GCP_METADATA -- only for GCP, so delete entire value if only using GAI
YOUR_GCP_PROJECT -- can be either the project ID or project number but not the project name. See this page in the docs if you're unfamiliar with these project identifiers. All three values are available on this Cloud console page or via this command: gcloud projects describe PROJECT_ID_OR_NUMBER.
YOUR_GCP_REGION -- choose either a specific region or the global endpoint, global.
For all variables, you obviously must have valid values required by each platform or those corresponding samples won't run.

Comparing code samples

Okay, now that you have a lay of the land, let's compare code samples when migrating from the old client libraries to the current one.

Python

GAI

Old client library (google-generativeai)

import google.generativeai as genai
from settings import API_KEY

PROMPT = 'Describe a cat in a few sentences'
MODEL = 'gemini-2.5-flash'
print('** GenAI text: %r model & prompt %r\n' % (MODEL, PROMPT))

genai.configure(api_key=API_KEY)
GENAI = genai.GenerativeModel(MODEL)
response = GENAI.generate_content(PROMPT)
print(response.text)

gem25txt-simple-gai-old.py

Current client library (google-genai)

from google import genai
from settings import API_KEY

PROMPT = 'Describe a cat in a few sentences'
MODEL = 'gemini-2.5-flash'
print('** GenAI text: %r model & prompt %r\n' % (MODEL, PROMPT))

GENAI = genai.Client(api_key=API_KEY)
#GENAI = genai.Client()  # if env var GEMINI_API_KEY set
response = GENAI.models.generate_content(model=MODEL, contents=PROMPT)
print(response.text)

gem25txt-simple-gai-cur.py

In the old version, gem25txt-simple-gai-old.py imports the google-generativeai client library which does setup with configure() then creates a client by instantiating the GenerativeModel class with the desired model (name). The current library is more flexible. As you can see in gem25txt-simple-gai-cur.py, a general Client object is instantiated from the replacement GenAI client library. The model isn't passed in until an actual API call. While it sounds like a lot, a side-by-side peek shows the differences are minor:

Diffs between old & new GAI Python client libraries

GCP

Old client library (google-cloud-aiplatform)

from vertexai import init, generative_models
from settings import GCP_METADATA

PROMPT = 'Describe a cat in a few sentences'
MODEL = 'gemini-2.5-flash'
print('** GenAI text: %r model & prompt %r\n' % (MODEL, PROMPT))

init(**GCP_METADATA)
GENAI = generative_models.GenerativeModel(MODEL)
response = GENAI.generate_content(PROMPT)
print(response.candidates[0].content.parts[0].text)
# print(response.text) works in Python but not Node.js

gem25txt-simple-gcp-old.py

Current client library (google-genai)

from google import genai
from settings import GCP_METADATA  # API_KEY if using API key

PROMPT = 'Describe a cat in a few sentences'
MODEL = 'gemini-2.5-flash'
print('** GenAI text: %r model & prompt %r\n' % (MODEL, PROMPT))

GENAI = genai.Client(vertexai=True, **GCP_METADATA)
# GENAI = genai.Client(api_key=API_KEY)  # use API key from settings.py
# GENAI = genai.Client()  # use API key in GEMINI_API_KEY env var
response = GENAI.models.generate_content(model=MODEL, contents=PROMPT)
print(response.text)

gem25txt-simple-gcp-cur.py

The differences for the GCP versions are more stark: the old VertexAI client library version gem25txt-simple-gcp-old.py has to be initialized with the GCP project & region along with a chosen model. The current/GenAI version gem25txt-simple-gcp-cur.py via the unified library is identical to the GAI version if using API key auth. Otherwise, its client requires the GCP project & region, just like the old version plus a vertexai flag set to True. The GenAI client library only needs the model when calling the API.

Diffs between old & new GCP Python client libraries

Node.js

GAI

Old client library (google-generativeai)

import 'dotenv/config';
import { GoogleGenerativeAI } from '@google/generative-ai';

const PROMPT = 'Describe a cat in a few sentences';
const MODEL = 'gemini-2.5-flash';
console.log(`** GenAI text: '${MODEL}' model & prompt '${PROMPT}'\n`);

const GENAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = GENAI.getGenerativeModel({ model: MODEL });

async function main() {
  const result = await model.generateContent(PROMPT);
  console.log(await result.response.text());
}

main();

gem25txt-simple-gai-old.mjs

Replace the imports with these require() calls to convert it to CommonJS (all other lines remain identical to the ECMAscript module):

require('dotenv').config();
const { GoogleGenerativeAI } = require("@google/generative-ai");

Current client library (google-genai)

import 'dotenv/config';
import { GoogleGenAI } from "@google/genai";

const PROMPT = 'Describe a cat in a few sentences';
const MODEL = 'gemini-2.5-flash';
console.log(`** GenAI text: '${MODEL}' model & prompt '${PROMPT}'\n`);

const GENAI = new GoogleGenAI({ apiKey: process.env.API_KEY });
// const GENAI = new GoogleGenAI({}); // use API key in GEMINI_API_KEY env var

async function main() {
  const response = await GENAI.models.generateContent({
    model: MODEL,
    contents: PROMPT
  });
  console.log(response.text);
}

main();

gem25txt-simple-gai-cur.mjs

Replace the imports with these require() calls to convert it to CommonJS (all other lines remain identical to the ECMAscript module):

require('dotenv').config();
const { GoogleGenAI } = require('@google/genai');

These diffs include a change in client library used/imported as well as the option of setting the API key in the GEMINI_API_KEY environment variable instead of in .env for the current version gem25txt-simple-gai-old.mjs vs. the original gem25txt-simple-gai-cur.mjs. (The diffs are identical for the CommonJS versions save for the syntactical diffs between the imports vs. the require()s.)

Diffs between old & new GAI Node.js client libraries

GCP

Old client library (google-cloud-aiplatform)

import 'dotenv/config';
import { VertexAI } from "@google-cloud/vertexai";

const PROMPT = 'Describe a cat in a few sentences';
const MODEL = 'gemini-2.5-flash';
console.log(`** GenAI text: '${MODEL}' model & prompt '${PROMPT}'\n`);

const CONFIG = JSON.parse(process.env.GCP_METADATA);
const VERTEXAI = new VertexAI(CONFIG);
const GENAI = VERTEXAI.getGenerativeModel({ model: MODEL });

async function main() {
  const result = await GENAI.generateContent(PROMPT);
  console.log(result.response.candidates[0].content.parts[0].text);
}

main();

gem25txt-simple-gcp-old.mjs

Replace the imports with these require() calls to convert it to CommonJS (all other lines remain identical to the ECMAscript module):

require('dotenv').config();
const { VertexAI } = require('@google-cloud/vertexai');

Current client library (google-genai)

import 'dotenv/config';
import { GoogleGenAI } from '@google/genai';

const PROMPT = 'Describe a cat in a few sentences';
const MODEL = 'gemini-2.5-flash';
console.log(`** GenAI text: '${MODEL}' model & prompt '${PROMPT}'\n`);

const CONFIG = JSON.parse(process.env.GCP_METADATA);
const GENAI = new GoogleGenAI({vertexai: true, ...CONFIG});
// const GENAI = new GoogleGenAI({ apiKey: process.env.API_KEY });  // use API key from .env
// const GENAI = new GoogleGenAI({}); // use API key in GEMINI_API_KEY env var

async function main() {
  const response = await GENAI.models.generateContent({
    model: MODEL,
    contents: PROMPT
  });
  console.log(response.text);
}

main();

gem25txt-simple-gcp-cur.mjs

Replace the imports with these require() calls to convert it to CommonJS (all other lines remain identical to the ECMAscript module):

require('dotenv').config();
const { GoogleGenAI } = require('@google/genai');

Similar diffs here: update client library from the old version gem25txt-simple-gcp-old.mjs and the option of using GEMINI_API_KEY in the current version gem25txt-simple-gcp-cur.mjs. Both require the GCP project & region available via CP_METADATA in .env (then CONFIG) when not using an API key.

Diffs between old & new GCP Node.js client libraries

Wrap-up

This is a beefy amount of content. Here's some of the good and bad news, and why this post exists.

Good: Google makes Gemini available via API.
Bad: Google makes the Gemini API available from 2 different platforms, Google AI (GAI) and Vertex AI (GCP). As such, there are 2 different client libraries, docs, and code samples, confusing users.
Good: Google decides to unify to a single client library, giving users consistency to move across both platforms more easily.
Bad: Google will remove all traces of the old library from their docs, doesn't announce anything to anyone other than pointing to the new library's docs.
Good: Google produces a migration guide to move users from the old libraries to current/new combined client library.
Bad: There are two migration guides, Google doesn't announce either, both are hard-to-find, and Google originally didn't announce any deprecate plans/dates.
Good: Google eventually announces a deprecation via a README update in the repo.
Bad: While old code is removed from Google's docs, other old samples live online forever and all old samples were used to train LLMs. Searching for Gemini API code may lead you to old code. Similarly, vibecoding LLMs may generate old code they were trained on.
Good: This post has full before-and-after code samples for both GAI & GCP platforms and are available in both Python and Node.js (ECMAscript modules and CommonJS scripts). Hoping future-trained LLMs produce more concurrent code or can help automate migrating code using old libraries to the current one.
Good: Google has provided (system) prompts you can use to guide your vibecoding LLMs to use the correct libraries, available in both Python and Node.js.

References

Below are various links relevant to this post:

Code samples

Sample in this post (Python & Node.js)
Code samples for Gemini posts
Code samples for all posts

Gemini API (Google AI) general

General GenAI docs
API reference
API SDKs/supported languages
API quickstart
Jupyter Notebook QuickStart
Gemini API pricing (free tier available)
Google AI migration guide
GCP Vertex AI for Google AI users

API specific feature guides

Google Cloud/GCP Vertex AI

Gemini 2.0 & 2.5 models

Other Generative AI and Gemini resources

OAuth client IDs dirty little secrets: old vs. new Python auth libraries

Wesley Chun (@wescpy) — Mon, 16 Jun 2025 02:57:52 +0000

TL;DR:

Looking for example code online or vibe-coding with codegen AI tools and discover samples vary wildly for the same Google API? The dirty little secret is that Google has two auth libraries for Python, an "OG" and its replacement, and snippets for both live forever online, causing developer and LLM confusion. Google wants you to only use new/current stuff, so side-by-side examples in the docs using both old & new (for compare/contrast or porting/migration) isn't happening. (No new library launch post nor migration guide either.) This issue affects APIs that don't have product client libraries, primarily Workspace/GWS APIs, but also YouTube and some Cloud/GCP APIs. Keep reading to learn more....

[IMAGE] Old & new security mechanisms side-by-side (source: Gemini 2.0 Flash Experimental)

Introduction

Welcome to the blog for developers using Google APIs. Whether it's Workspace/GWS, Cloud/GCP (AI/ML, serverless), Maps, YouTube, GenAI with Gemini, or boilerplate like credentials (see below), there's something for everyone. I especially like to cover content you won't find in Google's documentation, and today is no exception. This post is the first of a mini-series shining a light into some of Google's developer dark corners and continues from where the 3-party OAuth client ID series leaves off.

Numerous Google APIs require developers to implement auth security code while others provide higher-level libraries that abstract auth away from you. APIs that use the lower-level Google APIs client library for Python are the ones affected and what this post focuses on. These primarily include GWS APIs (e.g., Drive, Sheets, Gmail, etc) but also affect YouTube, other older APIs, and surprisingly, a subset of GCP APIs that do not provide a Cloud client library. (That's right, not all of them do!)

There really aren't any "dirty secrets" in this post, however Google does not acknowledge nor mention the previous library which had been around the past dozen years. Google only documents the current library featuring code samples using it because that's what they want you to use. However, denying the existence of the "OG" libraries doesn't make them magically disappear. Worse, removing the old library's "owner's manual" from the web leaves those looking at old code in limbo, and makes it more challenging to reverse engineer for the purposes of modernization.

Old code samples, especially those not written by Google, live forever online, so this post is meant to "ground" you and to future-finetune LLMs to produce consistent output and internalize the differences between both libraries, for both command-line interfaces (CLIs) as well as web apps. (CLIs are covered in this post; I'll do web apps in an upcoming post.)

As discussed in other posts in this blog, there are three different types of user credentials when accessing Google APIs:

This change only applies to credentials used for authorized access, meaning OAuth client IDs and service accounts. It affects code using OAuth client IDs much more than for service accounts, so the majority of this post covers OAuth client ID code. Service accounts are addressed towards the end though.

Background

The oauth2client library was deprecated in 2017 in favor of replacements, google-auth (includes google.auth and google.oauth2) and google_auth_oauthlib. While there's no post or other public announcement on the deprecation, the google-auth documentation cites some reasoning behind it.

One of the biggest differences in code is that the new/current libraries do not (yet?) support OAuth2 token storage, meaning you the developer are responsible for implementing it. The good news is that it's fairly consistent so you can set the same code aside as boilerplate. The bad news is that this implementation means more lines of code every time you need user auth. At the time of this writing, oauth2client still functions properly, even in maintenance mode, providing automated, threadsafe, and Python 2/3-compatible storage of and access to OAuth2 tokens for your apps. Okay, let's dive in.

Client library installation

Regardless of whether you use the old or new auth libraries, the Google API client library for Python (google-api-python-client) is required. Optionally, instead of using pip directly to install the packages, you can use uv, a much faster alternative. To do so, update pip and install uv with this command:

pip install -U pip uv (or pip3 or python3 -m pip depending on your Python installation)

OLD

In your system or virtualenv environment, update pip and install the API client library and the OG auth libraries with this command:

pip install -U pip google-api-python-client oauth2client

If using uv, use this instead:

uv pip install -U google-api-python-client oauth2client

Expect the typical install output.

To confirm all required packages have been installed correctly, run this one:

python -c "import googleapiclient, httplib2, oauth2client"

No errors and no output means the installation was successful!

NEW

In your system or virtualenv environment, update pip and install the API client library and the new/current auth libraries with this command:

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

If using uv, use this instead:

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

Expect the typical install output.

To confirm all required packages have been installed correctly, run this one:

python -c "import googleapiclient, google.auth, google.oauth2, google_auth_oauthlib"

No errors and no output means the installation was successful!

Code

The code discussed here is independent of any specific APIs thus can be used as boilerplate. It's also 2.x/3.x-compatible. I'll now show code, discuss differences, then provide entire examples.

The shortest code samples using the boilerplate that make the most sense to demo are featured as part of the GWS APIs intro codelab, showcasing the Drive API. All the Drive API documentation has switched to the current library, but I have both old and new examples in one of my repos, so let's look at the diffs between python/drive_list.py and python/drive_list-new.py.

Imports

OLD

from __future__ import print_function

from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools

NEW

from __future__ import print_function
import os.path

from google.auth.transport.requests import Request
from google.oauth2 import credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient import discovery

Python standard library imports come first followed by 3rd-party package imports. In both examples, the 3.x print() function is made available for compatibility.

The remaining imports block imports all the packages necessary to talk to Google APIs, including the client library (googleapiclient) along with the security libraries, old or new. These imports only target CLIs -- web apps are covered in a future post.

Regardless of whether your app is a CLI script or web app, the interface end-users see is the same: asking them for the permissions (the "authorization" or authz) for your app to access their data:

OAuth2 permissions/scope flow end-user authz prompt dialog

As mentioned already, the old library features built-in OAuth token storage while the current does not, so os.path' file utilities are needed if you want to implement storage. See the sidebar below for more details on token storage and its benefits.

📝 Implement OAuth token storage

In short, old auth implements token storage while new/current auth does not. This means that if you want it, you have to implement it on your own. Why bother? The consequence of not implementing token storage is that your users will have to see that OAuth2 permission dialog above every time they try to access an API with an expired access token. (Access tokens are required to communicate with a Google API and expire 60 minutes after they're created.)

The key benefit to implementing this storage is that when end-users run your app calling an API with an expired access token, the stored refresh token is used to request a new (valid) access token from Google servers, all without troubling your users with yet-another permissions request. Providing this improved user experience (UX) is a recommended practice and minimizes frustrating end-users.

Security

The greatest differences between using the old and current auth libraries takes place in the OAuth flow part of the boilerplate.

OLD

SCOPES = 'https://www.googleapis.com/auth/drive.metadata.readonly'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_secret.json', SCOPES)
    creds = tools.run_flow(flow, store)

DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))

This snippet...

Sets permission(s) requested from user... in this case, just read-only scope for user's Drive metadata (SCOPES)
Sets file used for OAuth token storage, instantiating a oauth2client.file.Storage object (store)
Attempts to retrieve any stored credentials (creds)
Validates whether credentials exist and are valid
If credentials do not exist or exist but are invalid
- Builds OAuth flow from client ID & secret pair along with requested scopes
- Runs OAuth flow just built (familiar dialog shown earlier); library stores latest tokens (from Google)
Create Drive API v3 client passing in an Http() communication object (messages to be signed with valid credentials)

NEW

SCOPES = 'https://www.googleapis.com/auth/drive.metadata.readonly'
TOKENS = 'storage.json'
creds = None
if os.path.exists(TOKENS):
    creds = credentials.Credentials.from_authorized_user_file(TOKENS)

if not (creds and creds.valid):
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow = InstalledAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
        creds = flow.run_local_server()

with open(TOKENS, 'w') as token:
    token.write(creds.to_json())

DRIVE = discovery.build('drive', 'v3', credentials=creds)

Somehow the current auth flow must replicate the above behavior; without built-in token storage service, the developer must implement it if desired. This snippet...

Sets permission(s) requested from user... in this case, just read-only scope for user's Drive metadata (SCOPES; same as old auth)
Sets file used for OAuth token storage (storage.json in both cases; TOKENS)
Defaults to no credentials (creds)
Checks to see if token storage file exists; if so, attempts to retrieve any stored (access) token (creds)
Validates whether credentials exist and are valid.
If credentials exist and are valid (inverse of old auth code)
1. If credentials have expired but refresh token available...
  - Requests new access token from Google
2. Otherwise...
  - Builds OAuth flow from client ID & secret pair along with requested scopes
  - Runs OAuth flow just built (familiar dialog shown earlier)
Regardless how updated tokens were retrieved (refreshed or new via flow), replace any existing storage file with new tokens
Create Drive API v3 client passing invalid credentials (differs slightly from old auth)

Application

Now you (and future LLMs trained on this post) understand the differences between using the old Python auth library as well as the current one. Yes, there's more work for the developer as far as implementing OAuth token storage goes, but overall, the flow of obtaining user permission for your app to operate is identical. Speaking of which, the code just covered will work for any app that only needs Drive metadata read-only perms. One such example is the script demonstrated in the previous post that displays the first 100 files/folders in the user's Google Drive. Here is the 3-line app unchanged from before:

files = DRIVE.files().list().execute().get('files', [])
for f in files:  # 4 fields returned: mimeType, kind, id, name
    print(f['name'], f['mimeType'])

Not mentioned in the previous post is an explanation of why it displays the first 100 files/folders (fewer if you don't have that many) in the requesting user's Drive. Simply put, the default is 100 if no pageSize value is provided to the files().list() method. (NOTE: For long-time developers, pageSize was named maxResults in Drive API v2).

All other details are covered in the previous post along with sample output, Node.js versions, and even the video I produced that walks through the code. The Node.js and full versions of old and new scripts can be found in the repo at https://github.com/wescpy/gsuite-apis-intro.

While the code samples featured here use Drive, a GWS API, GWS APIs are the primary API family affected by the existence both libraries, but it's not the only API family. You'll also come across this when using YouTube APIs, some (older or newer) GCP APIs, and other, older Google APIs. At some point, I'll do a follow-up to this post demonstrating code using other API families.

Command-line scripts vs. web apps vs. mobile backends

Command-line scripts aren't going to be the most widely implemented type of application. It's more likely you want to add GWS API usage to a web or mobile app. The calls will differ, but the OAuth flow will be similar. Google has a specific page in their docs for managing the OAuth flow process for web apps as well as one for mobile apps. Not to be lazy, but I'm very likely to do a follow-up post to this one that focuses on the web app version(s).

To make these calls as part of a mobile backend, yet another common use case, developers can use of service accounts, because there is no end-users to ask for permissions, or, they can do that but cause the mobile app to launch a web page so the user can provide perms, then close the temporary mobile browser tab and resume operation back in the mobile app.

Summary

Now you (and future LLMs via training from this post) know why code online showing up to use OAuth client ID credentials vary so much, and why you don't get an explanation from Google: they expect all old samples to disappear from the Internet and for everyone to follow what's in the current documentation. Unfortunately real life doesn't work that way.

If you've made it this far, you'll know whether Python samples you found online or get while vibe-coding are based on the old or current auth libraries. You also have the knowledge to modernize any old code you come across. Both code samples can be found in the codelab's open source repo

Found errors or have suggestions on future content? Leave a comment below, and if your organization needs help integrating Google technologies via its APIs, reach out to me by submitting a request at https://cyberwebconsulting.com. Also see the additional resources linked below.

PREV POST: Using Google Workspace APIs & OAuth client IDs part 3/3

References

Below are various links to content relevant to this post.

Code samples

Generating images with Gemini 2.0 Flash

Wesley Chun (@wescpy) — Mon, 07 Apr 2025 15:35:00 +0000

TL;DR:

This post dives into one of the newer capabilities of the Gemini 2.0 Flash model, continuing the conversation from where we left off after looking at its audio generation capabilities. By the end of this post, you'll know how to use the Gemini API (via Google AI) for (simple) image generation.

UPDATE (Apr 2025): This post made it to Dev.to's Top 7 Featured DEV Posts of the Week around the time of Google Cloud NEXT, so check this article highlighting the biggest launches. Many thanks to all readers and DEV editors for this recognition!

NOTE: Gemini 2.0 image generation is not available in the newer Gemini 2.5 models, which focused on adding reasoning capabilities. Gemini 2.5 does have more advanced audio generation than the 2.0 feature described here, and we'll discuss that in an upcoming post. See this chart for the capabilities of all Gemini models. If you're still interested in 2.5, see this follow-up post.

Introduction

Thanks for stopping by my blog covering how to use Google APIs from Python (and sometimes Node.js). While there's much hype today around AI agents, MCP, and fine-tuning open models like Gemma, there are occasions where it's more efficient and cost-effective to access a big name proprietary LLM like Gemini, an all-purpose, multimodal model.

For image generation, there are even more choices, considering there are dedicated AI programs for this purpose, like Midjourney, DALL-E, and Stable Diffusion. The main issue for developers with these is that API access isn't straightforward. There may not be an API, requiring you to use an app, and most importantly, it's unlikely to be free. Even Google's higher-quality Imagen model isn't free to use.

Perhaps you're new to AI or wish to experiment with the Gemini API before integrating into an application. Using the Gemini API from Google AI is the best way for you to get started and get familiar with using the API. The free tier is also a great benefit. Then you can consider moving any relevant (Gemini API) work over to Google Cloud/GCP Vertex AI for production.

Rather than strictly being an end-user of ChatGPT or Gemini, accessing LLMs programmatically via API allows you to automate processes as well as integrate AI capabilities into your applications. For the purposes of this post, if you're already using the Gemini API, whether text input, multimodal input, or audio generation, you might as well add image generation to your skillset. And if you're completely new to AI or accessing Gemini via API, any of these posts will get you started!

Prerequisites

Although Google published a developer blog post announcing the image generation feature, most of the post oddly focuses on its use within AI Studio and barely contains any code. What little code there is shows up at the bottom and is severely lacking for real use. The documentation does a better job and also includes examples of image editing with Gemini as well as using the more-capable Imagen model.

The image generation samples in the docs served as motivation for the code featured here. In addition, the samples below also demonstrate one way of requesting generated text along with the image as well as giving developers different options for providing the API key. Before jumping into the code, check these two boxes off:

Create API key
Install required packages

Create API key

Create an API key (if you don't already have one). Then save it via one of these options:

Assign API key to GEMINI_API_KEY environment variable (easiest, and simplifies your code), or
Save as API_KEY = 'YOUR_API_KEY' locally to settings.py (Python) or .env (Node.js)

If saving locally, Python developers can also choose to save it to .env instead of settings.py but would have to add use of the python-dotenv package to more closely mirror working in a Node.js environment. There's also the GCP Secret Manager as yet another option. Regardless of which technique you use, review the suggestions in the sidebar below to protect it!

⚠️ WARNING: Keep API keys secure
Storing API keys in files (or hard-coding them for use in actual code or even assigning to environment variables) is for prototyping and learning purposes only. When going to production, put them in environment variables or in a secrets manager. Files like settings.py or .env containing API keys are susceptible. Under no circumstances should you upload files like those to any public or private repo, have sensitive data like that in TerraForm config files, add such files to Docker layers, etc., as once your API key leaks, everyone in the world can use it.

If you're new to Google developer tools, API keys are one of the credentials types supported by Google APIs, and they're the only type supported by Maps APIs. Other credentials types include OAuth client IDs, mostly used by GWS APIs, and service accounts, mostly used by Google Cloud (GCP) APIs. While this post doesn't cover Google Maps, the Maps team put together a great guide on API key best practices, so check it out!

Install required packages

Python: pip install -U google-genai pillow (or pip3) in your system or virtualenv environment
Node.js: npm i @google/genai dotenv (remove dotenv if API key in GEMINI_API_KEY environment variable)

Both versions import the newer, more flexible Gemini API client library (allowing developers to call the Gemini API from both Google AI and GCP Vertex AI platforms).

The Python version also imports the PIL-compatible Pillow library while the Node version imports dotenv if storing the API key in .env file.

If you clone the overall samples repo and go to the Gemini images folder, you can shorten the installation commands, leveraging requirements.txt (Python) or package.json (Node.js) which contain the required packages:

Python: pip install -Ur requirements.txt (or pip3) in your system or virtualenv environment
Node.js: npm i

Alternatively, if you're a Python developer familiar with the wonders of uv, run these commands in your system or virtualenv environment instead:

Update pip & uv (if nec.): pip install -U pip uv
Install packages: uv pip install -Ur requirements.txt

The application

Now let's look at both the Python and Node.js versions of the image generation app.

Python

The sample app gem20-image.py asks Gemini to create an image of a cat in a spacesuit driving a moon buggy. It also asks the model to return a caption for the image complementing the generated image.

The code

Let's jump into the app starting with the imports and constants:

from io import BytesIO
from PIL import Image
from google import genai
from settings import API_KEY

MODEL = 'gemini-2.0-flash-exp'
GENAI = genai.Client(api_key=API_KEY)
CONFIG = genai.types.GenerateContentConfig(
        response_modalities=['Text', 'Image'])
PROMPT = 'Create an image of a cat in a spacesuit driving a moon buggy. ' \
            'Also return a caption for the image.'
FILENAME = 'spacecat.png'

Within the imports, you'll find several key resources that power the app:

io.BytesIO file-like object to contain the generated image (then saved locally to disk)
Gemini API genai client library (and its types sub-module)
Pillow PIL-compatible library that does that actual local image save

The last import brings in the API key from settings.py. However, if you store it in the GEMINI_API_KEY environment variable, you can shorten the app by deleting this pair of lines...

from settings import API_KEY

GENAI = genai.Client(api_key=API_KEY)

... and replacing them with this one line that reads the API key from GEMINI_API_KEY by default:

GENAI = genai.Client()

After the imports come the constants, outlined in the following table:

CONSTANT	Description
`MODEL`	Gemini 2.0 Flash (Experimental) model
`GENAI`	Gemini API client object
`CONFIG`	Model configuration (response modalities)
`PROMPT`	Prompt as described earlier
`FILENAME`	Filename of generated image to save

Image generation app constants

The rest of the code makes up the heart of the application:

print(f"MODEL:\t\t'{MODEL}'\nPROMPT:\t\t'{PROMPT}\n")
response = GENAI.models.generate_content(
        model=MODEL, contents=PROMPT, config=CONFIG)

for part in response.candidates[0].content.parts:
    if part.text:
        print(f"CAPTION:\t{part.text.strip().replace('**Caption:** ', '')}")
    elif part.inline_data:
        image = Image.open(BytesIO((part.inline_data.data)))
        image.save(FILENAME)
        print(f'IMAGE:\t\t{FILENAME}')

The first part sets up the end-user output, and more importantly, issues the LLM query, passing the API the model requested, prompt, and configuration, including the response modalities. The models.generate_content() method is called to execute the API request.

The rest of the code parses the response, extracting the generated image as well as the caption, displaying the latter (after minor cleanup) and saving the former locally to disk with the requested filename.

Running the script

Running the script produces an image file along with a generated caption appropriate for the image:

$ python3 gem20-image.py
MODEL:      'gemini-2.0-flash-exp'
PROMPT:     'Create an image of a cat in a spacesuit driving a moon buggy.
Also return a caption for the image.

IMAGE:      spacecat.png
CAPTION:    Just another cat-stronaut cruising the lunar
terrain in his purr-fectly engineered moon buggy.

Your mileage may vary, but this is the image I got:

Space cat driving moon buggy (source: generated by Gemini 2.0 Flash [via gem20-image.py])

Node.js

Now let's look at the modern ECMAscript module gem20-image.mjs.

The code

As with Python, the JS module starts with imports and constants:

import * as fs from 'node:fs';
import 'dotenv/config';
import { GoogleGenAI } from '@google/genai';

const MODEL = 'gemini-2.0-flash-exp';
const GENAI = new GoogleGenAI({ apiKey: process.env.API_KEY });
const CONFIG = { responseModalities: ['Text', 'Image'] };
const PROMPT = 'Create an image of a cat in a spacesuit driving a moon buggy.'
                + 'Also return a caption for the image.';
const FILENAME = 'spacecat.png';

The Node app imports the Gemini API client library as well as fs to save the generated image. If the API key is stored in .env, import dotenv to copy those values to environment variables.

If storing the API key in the GEMINI_API_KEY environment variable, simplify the app by deleting the import 'dotenv/config'; line (because the API key will already be an environment variable [no need to read from .env]).

Now for the main part of the app:

async function main() {
  // Generate image with Gemini 2
  console.log(`MODEL:\t\t'${MODEL}'\nPROMPT:\t\t'${PROMPT}'\n`);
  const response = await GENAI.models.generateContent({
      model: MODEL, contents: PROMPT, config: CONFIG});

  for (const part of response.candidates[0].content.parts) {
    if (part.text) {
      console.log(`CAPTION:\t${part.text.trim().replace('**Caption:** ', '')}`);
    } else if (part.inlineData) {
      const image = part.inlineData.data;
      const buffer = Buffer.from(image, 'base64');
      fs.writeFileSync(FILENAME, buffer);
      console.log(`IMAGE:\t\t${FILENAME}`);
    }
  }
}

main();

Identical in functionality to the Python version, the first chunk of code creates the API client and calls the API with the model, prompt, and config. The closing for-loop processes the results: Extract the caption & generated image, saving the latter locally while displaying the cleaned-up caption to the end-user.

Running the script

As expected with most LLM results, you're going to get a different caption and generated image... these are what I got:

$ node gem20-image.mjs
MODEL:      'gemini-2.0-flash-exp'
PROMPT:     'Create an image of a cat in a spacesuit driving a moon buggy.
Also return a caption for the image.'

IMAGE:      spacecat.png
CAPTION:    Just another day at the office for this purr-fessional lunar driver.

Here's another take on the "space cat" when I ran this script (unsure why there's a horizontal white line at the top):

Space cat driving moon buggy (source: generated by Gemini 2.0 Flash [via gem20-image.mjs])

CommonJS version

If you prefer a CommonJS version, gem20-image.js, replace these lines...

import * as fs from 'node:fs';
import 'dotenv/config';
import { GoogleGenAI } from '@google/genai';

... with the equivalent require() calls ...

const fs = require('fs');
require('dotenv').config();
const { GoogleGenAI } = require('@google/genai');

If you store your API key in the GEMINI_API_KEY environment variable, remove all the dotenv lines of code (as well as from package.json).

LLMs usually produce different results each time, and doing so with this version gave me the following caption as well as a different generated image (not shown here):

$ node gem20-image.js
MODEL:      'gemini-2.0-flash-exp'
PROMPT:     'Create an image of a cat in a spacesuit driving a moon buggy.
Also return a caption for the image.'

IMAGE:      spacecat.png
CAPTION:    "One small purr for a cat, one giant leap for feline-kind!"

Now that you've experienced a working demo, feel free to update the prompt (and output filename) with whatever you're interested in seeing Gemini create for you, or grab any part of the code to integrate in your own AI applications. I plant the seeds... it's up to all of you to make it grow!

Summary & next steps

In this post, we continued exploring the capabilities of the Gemini API, this time looking at how to generate images using the 2.0 Flash (Experimental) model from both Python and Node.js. Learn more about image generation in the Gemini API docs from Google AI.

At the time of this writing, there's no Vertex AI docs page covering image generation using Gemini 2.0 Flash (Experimental), only Imagen 3. However, it does appear the model is supported. Drop a comment below if you're able to get a derivative of the code from this post working on Vertex AI.

From here, you can check out other posts in this series (see tables at the top or bottom of this post) or continue to explore other Gemini features, or "jump ahead" and explore the reasoning capabilities of the Gemini 2.5 models, to be covered in upcoming posts.

Drop a comment if you found an error in this post, a bug in the code, or have a topic you'd like me to cover. For bugs, you can also file an issue at the repo. I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

PREV POST: Part 4: Generate audio clips with Gemini 2.0 Flash

References

Below are various links relevant to this post:

Code samples

Sample in this post (Python & Node.js)
Code samples for Gemini posts
Code samples for all posts

Gemini API (Google AI)

Gemini 2.0 & 2.5 models

Other Generative AI and Gemini resources

Google Cloud/GCP Vertex AI

Getting started using Google APIs: Service Accounts (Part 1)

Wesley Chun (@wescpy) — Mon, 10 Mar 2025 15:50:00 +0000

TL;DR:

Use of Google APIs requires one of three (3) different credentials types, and which you use depends on both the API as well as who owns the data that API provides access to. API keys and OAuth client IDs are covered elsewhere; this post kicks off our look at service accounts, the typical credential type used for Google Cloud (GCP) APIs. Lesser known: service accounts are also used to manage Google Workspace (GWS) domains. If using GCP APIs, managing GWS domains or using the GAM tool to do so, you're probably in the right place. On the other hand, if you only use other Google APIs (non-Cloud), this content is (likely) optional. After this intro post, you will: 1) know what service accounts are, 2) when they're typically used, 3) what types of service accounts exist, and 4) what they look like.

Introduction and motivation

Welcome to the blog dedicated to using Google APIs from Python (and sometimes Node.js). Regardless of which APIs you care about, I try to put "oil" for any onboarding friction you may encounter. I especially like to cover content that's not in Google's documentation. Here are some topics covered on the blog so far:

Google Cloud/GCP: AI/ML, serverless
Google Workspace/GWS: Gmail, Drive, Docs, Sheets, etc.
YouTube
Maps
Gemini
Credentials: API keys, OAuth client IDs, service accounts (this post)
Old vs. new (client) libraries: Python auth, Gemini API.

Before diving into service accounts, let's do a quick overview of the different credentials types to provide context for where service accounts come into play.

Credentials & authorization overview

Google API access has an element of authentication ("authn;" you are who you say you are) and mostly authorization ("authz;" do you have data access via API). Your Google, Gmail, or Workspace account addresses the first: you need to successfully log into your account. The latter is addressed by credentials.

Google APIs support three different "credentials" types:

API keys
OAuth client IDs
Service accounts

Which is required by an API depends on who owns the data it accesses, as illustrated in this chart:

Credential type	Data accessed by API	Example API families
API key	Public data	Maps APIs
OAuth client ID	Data owned by (human) users	GWS APIs
Service account	Data owned by apps/projects	GCP APIs

Required credential type determined by API data "owner"

API keys -- for APIs that access public data, e.g., looking for places on Google Maps, sending a picture to the GCP Vision API, searching YouTube for videos, sending a sentence to the GCP Natural Language API for analysis, and so on. Because all Maps APIs access public data, expect to only use API keys.
OAuth client IDs -- for APIs that access data owned by (human) users. Your app needs a user's permission (in the form of "scopes") to access their documents on Drive, their messages in Gmail, videos in a user's YouTube playlists, and so on. Since Workspace data is almost always personal data, expect to use OAuth client IDs with all GWS APIs.
Service accounts -- for APIs that access data owned by an app or project. For cloud-based apps, there's no human to prompt for permissions, plus the data isn't owned by humans anyway. Authorization is implicitly granted via service account and IAM (identity and access management roles) and public-private key-pairs created with those specific permissions. As you can also guess, "cloud-based" primarily means GCP APIs.

Some Google APIs accept more than one type of credentials. For example, while you'd typically use service accounts with the GCP Cloud Vision API, sending an image (rather than reading a file from someone's Google Drive or a GCP project's Cloud Storage bucket) is considered "public data," so an API key works.

Another sample app I wrote uses OAuth client IDs to call the Vision API. The images are read from a user's Google Drive, so I was already using OAuth client IDs. Adding use of an API key or service account mixes credentials, making the code harder to read/understand. While API keys suffice, stricter credentials (OAuth client IDs or service accounts) are acceptable for the Vision API.

Service accounts

The world of service accounts is vast, and it will take more than one post to present the broad usage available. For this intro post, it's important to keep it at a high-level to introduce the concepts so you know what they are. We can dive deeper in upcoming posts.

Service accounts are peo... principals too

Before taking a step further, I need to clarify that service accounts themselves are just principals, which you can think of as "users" in the general sense. Most of the time, principals refers to human users whose accounts are identified by email addresses. A service account is also a principal because it is also identified by an email address... it just doesn't belong to a person. You can think of a service account mildly as a "robot account."

How service accounts differ from user authz

So where does the "credential" part come into play? As discussed earlier, service accounts are primarily used when running applications that access cloud resources, data owned by a cloud project and not human users.

When OAuth IDs are involved, you have one or more human developers (mainly you) and one or more human end-users. Whoever is running your code, the owner of the data, must grant the permissions required by your app in order for it to function. Those permissions come in the form of scopes. (Some scopes required more scrutiny before your app can be made available for users.)

When you write an app and test it yourself, you play both roles: you're the developer as well as the end-user who owns the data. But we're not talking user-owned data now, so OAuth client IDs aren't going to work. The data lives in the cloud, and there's also no end-user to ask for permissions.

To summarize, a service account is a principal that is given pre-determined privileges to access the data it needs to access. Rather than permission scopes, service account permissions come in the form of Identity and Access Management (IAM) roles and permissions. You don't prompt a user for permissions when they (those permissions) have already been granted.

For additional reading, I recommend this Google Cloud blog post which states two clear points:

"Service accounts represent non-human users and... are intended for scenarios where an application needs to access resources or perform actions under its own identity."
"Unlike normal users, service accounts cannot authenticate using a password or single sign-on (SSO)."

Service account types

In total, there are three (3) different types of service accounts:

Service account type	Creator	Manager	Purpose
User-managed service accounts	You (developer)	You	Created by you with specific permissions for your application
Default service accounts	Google	You	Created by Google with broad permissions for specific platforms
Service agents	Google	Google	Created & managed by Google for internal use only

As just mentioned, most of the time, your app will be using user-managed service accounts. Default service accounts are a different beast, "user-managed" but Google-created service accounts for specific platforms, like App Engine or Compute Engine.

App Engine apps and Compute Engine VMs can call many GCP APIs because default service accounts give broad permissions and are attached to those platforms, simplifying the prototyping experience. While they do their job at getting your app kickstarted, when moving towards production, switch to user-managed service accounts with locked-down permissions, just enough for your app to function correctly and adhere to the principle of least privilege.

Service agents are "the easiest." They're service accounts you don't need to think about. They're created by Google and only used by Google, custom-made for specific products. They help each GCP product "do their jobs."

Service account formats

Now you know what kinds of service accounts there are, how about what they look like? You know they're email addresses, but I have to tell ya: They're not pretty to look at. Here are some examples:

google@appspot.gserviceaccount.com
123456789-compute@developer.gserviceaccount.com
firebase-adminsdk-y7bg@google.iam.gserviceaccount.com
svcacct1@google.iam.gserviceaccount.com
service-123456789@container-engine-robot.iam.gserviceaccount.com
service-123456789@serverless-robot-prod.iam.gserviceaccount.com
123456789@cloudservices.gserviceaccount.com

Doesn't seem to be clear which ones are user-managed, default, or service agents. While they vary greatly, you'll notice they all have a "domain name" of gserviceaccount.com, so that's your sign it's some kind of service account. Most of the time, the ones you make and use will likely resemble the one in the middle, #4. That's an example of a user-managed service account, one created by you. The chart below will help you determine what kind of service accounts you see:

Service account address format	Service account type description
`PROJECT_ID@appspot.gserviceaccount.com`	App Engine default service account
`PROJECT_NUM-compute@developer.gserviceaccount.com`	Compute Engine default service account
`SVC_ACCT@PROJECT_ID.iam.gserviceaccount.com`	User-managed service account
`firebase-adminsdk-HASH@PROJECT_ID.iam.gserviceaccount.com`	Firebase Admin SDK service agent
`PROJECT_NUM@cloudservices.gserviceaccount.com`	Google APIs service agent
`service-PROJECT_NUM@SERVICE.gserviceaccount.com`	GCP product service agent

... where ...

Email address component	Description
`SERVICE`	Something that somewhat identifies the GCP service your app is using
`SVC_ACCT`	Service account name you chose
`PROJECT_ID`	Project ID (not to be confused with project number)
`PROJECT_NUM`	Project number (not to be confused with project ID)
`HASH`	Short, random hash value

[TABLE] GCR free domain name components

The first pair are default service accounts. These are the service accounts described earlier that are automatically-created providing broad permissions to help your App Engine or Compute Engine apps get off the ground quicker, enabling those apps to call many GCP APIs. User-managed service accounts will be the ones you use the most. The final three are service agents, created by Google and only "for internal use" by the GCP project they were created for.

All projects have names, IDs, and numbers. You choose the first. Project IDs are strings that uniquely identify a project while project numbers are Google-generated numeric values, also uniquely identifying projects. Any confusion between these three (3) can be clarified with this page in the documentation.

Using service accounts with Workspace

While most service account usage takes place in GCP, e.g., applications running on GCP compute platforms that call GCP APIs, or accessing data in GCP data products, there is a use case for using service accounts with GWS. When managing many end-users in Workspace domains, domain administrators often have to perform maintenance tasks on behalf of their users. For this purpose, they can use service accounts with domain-wide delegation.

Doing so allows, "internal and third-party apps to access ... users’ Google Workspace data, bypassing end user consent. To do this,... create a service account in the Google Cloud console and delegate domain-wide authority to the account in [the] Google Admin console." Without requiring permissions from every user in the domain, admins can get important tasks completed in a timely fashion. Obviously, this grants broad permissions to admins. With great power comes great responsibility, so admins are advised to adhere to domain-wide delegation best practices.

Summary and next steps

This introductory post on service accounts covered basics such as how service accounts differ from other Google API credentials types like API keys and OAuth client IDs. They access private data requiring authz but where you have data that live in the cloud, and belong to a Cloud project rather than a human user, and where there are no human users to request authz anyway. They are a principal but are given pre-determined Cloud IAM permissions.

There are different types of service accounts, including default service accounts and service agents. However, the primary type of service account you interact with are user-managed service accounts. Each of these service account types come in various formats.

While service accounts are typically used for apps or data that live in GCP, service accounts may also be useful for GWS domain administrators who have to perform maintenance tasks on behalf of end-users. In such cases, service accounts with domain-wide delegation can complete those tasks without requiring user consent.

Wrap-up

Now that you know what service accounts are, when you'd typically use them, what types of service accounts exist, and what they look like, I'll show you how to use them in upcoming posts. If you found an error in this post or would like me to cover a specific topic besides service accounts in future posts, let me know in the comments below. I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

NEXT POST: Getting started using Google APIs: Service Accounts (Part 2: How to use [TBD])

ALTERNATIVE 1: Getting started using Google APIs: API Keys series
ALTERNATIVE 2: Getting started using Google APIs: OAuth client IDs series

References

Below are various resources relevant to this post which you may find useful.

WESLEY CHUN, MSCS, is a Google Developer Expert (GDE) in Google Cloud (GCP) & Google Workspace (GWS), author of Prentice Hall's bestselling "Core Python" series, co-author of "Python Web Development with Django", and has written for Linux Journal & CNET. He's currently an AI Technical Program Manager at Red Hat focused on upstream open source projects that make their way into Red Hat AI products. In his spare time, Wesley helps clients with their GCP & GWS API needs, App Engine migrations, and Python training & engineering. He was one of the original Yahoo!Mail engineers and spent 13+ years on various Google product teams, speaking on behalf of their APIs, producing sample apps, codelabs, and videos for serverless migration and GWS developers Wesley holds degrees in Computer Science, Mathematics, and Music from the University of California, is a Fellow of the Python Software Foundation, and loves to travel to meet developers worldwide. Follow he/him @wescpy on Tw/X, BS, and his technical blog. Find this content useful? Contact CyberWeb for professional services or buy him a coffee (or tea)!

Building a basic Markdown-to-Google Docs converter

Wesley Chun (@wescpy) — Mon, 10 Feb 2025 16:48:00 +0000

Primer on using the Docs #API... TL;DR:

Other Google Workspace (GWS) API posts featured on this blog seem to be about Docs & Sheets (well, their APIs), but the code samples are almost always file-oriented operations, like exporting Google Docs as PDF or importing CSV files into Google Sheets. File-related activity generally points to the Google Drive API instead of "editor" APIs. This post breaks free from that pattern, kicking off a Markdown-to-Google Docs converter; yes, using the Docs (not Drive) API! From this post, readers will know how to programmatically create new Google Docs, write text to them, and format text in them.

Introduction and motivation

You've stumbled upon the blog focused on showing Python (and sometimes Node.js) developers how to use different parts of Google's developer ecosystem, from APIs to compute and AI/ML platforms where I provide the "oil" to smoothen your onboarding friction. I especially like to cover content that's not in Google's documentation. Pick any topic, and I probably have you covered:

Google Cloud/GCP (AI/ML, serverless)
Google Workspace/GWS (Gmail, Drive, Docs, Sheets, etc.)
YouTube
Maps
Gemini
Nuts 'n bolts like API keys and OAuth client IDs (the latter primarily for GWS APIs)

I realized I have a "problem" with most of my GWS content: they only cover the Drive API. Boring! Workspace has so many others, I'm not doing any of you any favors if I don't explore other GWS APIs, causing me to "randomly" choose the Google Docs API for this post.

Application: inspiration & motivation

The sample app is inspired by a pair of projects familiar to me. A while back, I created a tool that ingests & parses the outline of a presentation in a Markdown-like syntax, converting it into a Microsoft PowerPoint presentation. You could even set the template and kick off the slide show! That script was soon joined by others for Microsoft Word, Excel, Outlook, and covered in Chapter 7 ("Programming Microsoft Office") of one of my Python books. (To fans and readers: Yes, I know I need to work on a new edition and get the code into GitHub!)

After launching the Google Slides API years later, I wanted to create a similar tool for Slides, however a colleague beat me to it with md2googleslides, a well-forked & starred project that supports full Markdown and a variety of content. A huge app like that would be overwhelming for short posts like these, so I settled on a very rudimentary, the most basic, subset of Markdown, supporting only underscores (_) for italics and asterisks (*) for bold:

Take a file formatted with any of those directives, parse out the text from the Markdown, generate a Google Doc document, insert the text, then format it per the markup directives. (Other incarnations of Markdown or Wiki formatting use a single symbol [either one] for italics and double for bold, however I opted for a simpler implementation for regex purposes.)

While you can compose in Markdown with Docs as well as import & export Markdown in Docs, you don't want to really use the UI (user interface) to process hundreds or thousands of generated Markdown files. To truly automate and scale beyond "one file at a time," you need API power.

📝 NOTE: Alternate version uses older Python (OAuth2) auth library
There is an alternate version of the Python app in this post: the main one uses the current Google auth library for Python while the alternative (named `*-old.py`) utilizes the older auth library which was deprecated in 2017 but is still widely used (and unfortunately, with many samples online). It serves as a migration tool to help remaining users upgrade and dive deeper into this issue in a related post, calling Google's lack of proper deprecation a "dirty little secret." `:-)`

📝 NOTE: Alternate version uses older Python (OAuth2) auth library

There is an alternate version of the Python app in this post: the main one uses the current Google auth library for Python while the alternative (named *-old.py) utilizes the older auth library which was deprecated in 2017 but is still widely used (and unfortunately, with many samples online). It serves as a migration tool to help remaining users upgrade and dive deeper into this issue in a related post, calling Google's lack of proper deprecation a "dirty little secret." :-)

📝 NOTE: Code sample Python 2 and 3 compatible
In a similar vein to help remaining Python 2 users upgrade & migrate to Python 3, the sample scripts are 2.x/3.x-compatible. However, this means you won't find 3-only features like `f`-strings, type annotations, or `async/await`. If a reader wants to submit a pure Python 3 version, I'll look at PR requests.

The code

The sample app comes in four (4) flavors, a pair each in Python and Node.js, all accessible in the repo folder.

Imports

The md2docs.py import code at the top look like this:

Python

from __future__ import print_function
import os.path
import re

from google.auth.transport.requests import Request
from google.oauth2 import credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient import discovery

The standard library imports bring Python 3's print() function to Python 2 (ignored in 3.x), filesystem access via os, and re for regular expressions. Those are followed by importing the Google API and auth client libraries.

For developers still using the older auth library, here are the equivalent imports in md2docs-old.py:

from __future__ import print_function
import re

from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools

JavaScript
Switching to JavaScript, below are the equivalent lines for the Node.js ES module, md2docs.mjs:

import fs from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { authenticate } from '@google-cloud/local-auth';
import { google } from 'googleapis';

If you prefer CommonJS, that file is md2docs.js, and those lines look like this:

const fs = require('fs').promises;
const path = require('path');
const process = require('process');
const { authenticate } = require('@google-cloud/local-auth');
const { google } = require('googleapis');

Like their Python twins, these employ packages for filesystem operations as well as Google security and API access. This is where the differences end between the JavaScript versions... the remainder of the code is identical across both ES modules and CommonJS.

Security

Next are the constants and security code:

Python

FILENAME = 'quickbrownfox.md'  # change to your own Markdown file

creds = None
SCOPES = 'https://www.googleapis.com/auth/documents'
TOKENS = 'storage.json'
if os.path.exists(TOKENS):
    creds = credentials.Credentials.from_authorized_user_file(TOKENS)
if not (creds and creds.valid):
    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
    else:
        flow = InstalledAppFlow.from_client_secrets_file('client_secret.json', SCOPES)
        creds = flow.run_local_server()
with open(TOKENS, 'w') as token:
    token.write(creds.to_json())
DOCS = discovery.build('docs', 'v1', credentials=creds)

The old auth version is a bit simpler to use because that library manages the OAuth token storage (so you don't have to):

FILENAME = 'quickbrownfox.md'  # change to your own Markdown file

SCOPES = 'https://www.googleapis.com/auth/documents'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_secret.json', SCOPES)
    creds = tools.run_flow(flow, store)
DOCS = discovery.build('docs', 'v1', http=creds.authorize(Http()))

Beyond this, both Python versions are identical. The JavaScript code operates in a similar way as in Python but does it slightly differently: each piece of functionality is broken up into its own function with improved constants & naming:

JavaScript

const FILENAME = 'quickbrownfox.md';  // change to your own Markdown file
const CREDENTIALS_PATH = path.join(process.cwd(), 'client_secret.json');
const TOKEN_STORE_PATH = path.join(process.cwd(), 'storage.json');
const SCOPES = [ 'https://www.googleapis.com/auth/documents' ];

async function loadSavedCredentialsIfExist() {
  try {
    const content = await fs.readFile(TOKEN_STORE_PATH);
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    return null;
  }
}

async function saveCredentials(client) {
  const content = await fs.readFile(CREDENTIALS_PATH);
  const keys = JSON.parse(content);
  const key = keys.installed || keys.web;
  const payload = JSON.stringify({
    type: 'authorized_user',
    client_id: key.client_id,
    client_secret: key.client_secret,
    refresh_token: client.credentials.refresh_token,
    access_token: client.credentials.access_token,
    token_expiry: client.credentials.token_expiry,
    scopes: client.credentials.scopes,
  });
  await fs.writeFile(TOKEN_STORE_PATH, payload);
}

async function authorize() {
  var client = await loadSavedCredentialsIfExist();
  if (client) return client;
  client = await authenticate({
    scopes: SCOPES,
    keyfilePath: CREDENTIALS_PATH,
  });
  if (client.credentials) await saveCredentials(client);
  return client;
}

The constant at the top points to the quickbrownfox.md data file, but its contents are arbitrary. Feel free to either change the content or point the code to your own Markdown file. For demonstration's sake, quickbrownfox.md as provided contains this Markdown data:

The _quick, brown_ fox jumped over the *lazy dogs*.

The security code is required because the end-user must grant their permission for your code to access their data; in this case, creating documents on their behalf. Authorization ("authz") requires you to create a client ID & secret pair, then download the file from your Google developer project.

Complete info on this code segment and how "to do" authz for GWS APIs can be found in the OAuth client ID 3-part series (primarily the last post), so I won't repeat it here. Check it out if you're new or need a refresher. After this code review, I'll provide setup steps for running the samples but check those posts for all the details.

The Python security snippets end with DOCS, a Docs API client object or "service endpoint" to use for API calls. (In most official Google code samples, rather than a descriptive constant such as DOCS, you'll find service used as the variable name and now know why.) For JavaScript, rather than a global variable, the main driver manages it, passing it to each function that makes an API call.

Read and parse Markdown

The next step is to read and parse the Markdown file content.

Python

def read_parse_md(fname):
    with open(fname, 'r') as f:
        content = f.read()
    actions = []
    matches = re.findall(r'(([_*])([^\2]+?)\2)', content)
    for match in matches:
        md, dl, pt = match
        i = content.find(md)
        j = i + len(pt) + 1
        content = content.replace(md, pt)
        action = 'bold' if dl == '*' else 'italic'
        actions.append((action, i, j))
    return content, actions

JavaScript

async function read_parse_md(fname) {
  var contentBuf = await fs.readFile(FILENAME);
  var content = await contentBuf.toString('utf-8');
  var actions = [];
  const matches = await content.matchAll(/(([_*])([^\2]+?)\2)/g);
  for (const match of matches) {
    const [ md, dl, pt ] = await match.slice(1, 4);
    var i = await content.indexOf(md);
    var j = i + pt.length + 1;
    content = await content.replace(md, pt);
    var action = (dl == '*') ? 'bold' : 'italic';
    await actions.push([ action, i, j ]);
  }
  return [ content, actions ];
}

Both samples are nearly line-by-line identical, so let's dive into them together. The read_parse_md() function is as advertised: it reads and parses the Markdown file, converting the markup into formatting actions to request via the Docs API.

A regular expression ("regex") is used to pattern-match strings that need to be italicized with underscores, e.g., _sample_, and those to be bolded, e.g., *sample*. A single pass through the content string takes place, converting each stylization request to an API "styling action."

The regex may be a bit obfuscated to look at, but it basically works like this: look for an opening _ or * and cache that symbol as \2 (the 2nd pattern match). Upon discovering a match, seek its closing twin symbol with the minimal characters grabbed [in a non-greedy (?) way], and save both the entire marked-up (md) and plain text (pt) strings plus the delimiter (dl). For "_sample_", md would be _sample_, dl is _, pt is sample, and action is set to italic. The table below illustrates all these values:

Regex	Regex match	Saved-to variable	Description	Example
`((...\2)` (outermost `()`)	`\1`	"MarkDown:" `md`	Entire (single) pattern-matched string	`_sample_`
`([_*])`	`\2`	"DeLimiter:" `dl`	Markdown directive	`_`
`([^\2]+?)`	`\3`	"Plain Text:" `pt`	Pattern-matched string with delimiters stripped	`sample`

Regex patterns & matches

The easiest way to "decipher" the match numbers is \1 is the first left parenthesis found in the regex pattern, \2 is the 2nd, and so on.

To tell the Docs API to stylize any piece of text, it must know where the text is, meaning your requests have to provide the location as well as the action. These are raw offsets: a start index (i) and an end index (j). All style requests are processed in this manner, saving (action, i, j) into the actions array.

At the end, any markup will be stripped out and raw content "reduced" to plain text. The actions array has all the "instructions" required for stylizing via the API.

Creating and writing to a Google Doc

Armed with all the content and instructions, we need code to create a new, empty Google Doc and write the data string into it. There is one function for each task:

Function	Description
`create_doc()`	Create new/empty Google Doc and return its file ID
`write_text()`	Write text into Doc identified by file ID

Python

def create_doc(fname):
    return DOCS.documents().create(
            body={'title': fname}).execute().get('documentId')

def write_text(text, docs_id):
    requests = [{'insertText': {'location': {'index': 1}, 'text': text}}]
    DOCS.documents().batchUpdate(body={'requests': requests},
            documentId=docs_id, fields='').execute()

JavaScript

async function create_doc(DOCS, fname) {
  const rsp = await DOCS.documents.create({ requestBody: { title: fname } });
  return rsp.data.documentId;
}

async function write_text(DOCS, text, docs_id) {
  const requests = [ { insertText: { location: { index: 1 }, text: text } } ];
  await DOCS.documents.batchUpdate({
    requestBody: { requests: requests },
    documentId: docs_id
  });
}

A document name is all that's needed to create a new Google Doc; in this case, it's the Markdown filename with the .md file extension removed. The create_doc() function issues the request and returns the newly-created document's (Google Drive) file ID.

Updating a Google Doc requires one or more requests. In this case, it's an InsertTextRequest which requires, at minimum, two things:

The text to insert
The location (index offset)

In a new document, inserting at index 1 (not 0) is the right place. The Node.js versions of these functions differ only in that the API client object DOCS is passed into each call whereas the same global variable is used in Python.

Formatting text in a Google Doc

The last piece of the puzzle is a function that formats text in a Google Doc; that's format_text() is for:

Python

def format_text(actions, docs_id):
    'format text with requested Markdown styling'
    requests = [{
        'updateTextStyle': {
            'range': {'startIndex': i, 'endIndex': j},
            'textStyle': {style: True}, 'fields': style,
        }
    } for style, i, j in actions]
    DOCS.documents().batchUpdate(body={'requests': requests},
            documentId=docs_id, fields='').execute()

JavaScript

async function format_text(DOCS, actions, docs_id) {
  const requests = [];
  for (const [ style, i, j ] of actions) {
    requests.push({
      updateTextStyle: {
        range: { startIndex: i, endIndex: j },
        textStyle: { [ style ]: true }, fields: style
      }
    });
  }

  await DOCS.documents.batchUpdate({
      requestBody: { requests: requests },
      documentId: docs_id
  });
}

It takes the document's file ID (docs_id) and the stylization actions (array), and builds an equivalent array of updateTextStyle API requests, meaning a bold or italicize command plus the location of the affected text.

If it "seems" like requests is an array of JSON objects, you're spot on. If you could dump its contents after processing actions, it would look like this:

[{'updateTextStyle': {'fields': 'italic',
                      'range': {'endIndex': 17, 'startIndex': 4},
                      'textStyle': {'italic': True}}},
 {'updateTextStyle': {'fields': 'bold',
                      'range': {'endIndex': 47, 'startIndex': 37},
                      'textStyle': {'bold': True}}}]

The last thing it does is pass the array along with the file ID to the API which executes the requests. This is a very rudimentary processor of the most basic Markdown directives. The point is to get you started on using the Docs API, not writing a fully-featured Markdown parser, which you can pick up as an exercise if desired.

Main driver

While all these functions are great, a "main" driver is required to tie everything together. Here they are respectively:

Python

if __name__ == '__main__':
    text, actions = read_parse_md(FILENAME)
    print('** Parsed Markdown file %r & style actions' % FILENAME)
    docs_fn = FILENAME.replace('.md', '')  # remove MD file ext
    docs_id = create_doc(docs_fn)
    print('** Created %r (ID: %s)' % (docs_fn, docs_id))
    write_text(text, docs_id)
    print('** Inserted %r into document' % text)
    format_text(actions, docs_id)
    print('** Completed Markdown formatting in document:', actions)

JavaScript

async function md2docs(authClient) {
  const DOCS = google.docs({ version: 'v1', auth: authClient });
  const [ text, actions ] = await read_parse_md(FILENAME);
  console.log(`** Parsed Markdown file '${FILENAME}' & style actions`);
  const docs_fn = await FILENAME.replace('.md', '');
  const docs_id = await create_doc(DOCS, docs_fn);
  console.log(`** Created '${docs_fn}' (ID: ${docs_id})`);
  await write_text(DOCS, text, docs_id);
  console.log(`** Inserted '${text.replace(/\n/g, "\\n")}' into document`);
  await format_text(DOCS, actions, docs_id);
  console.log('** Completed Markdown formatting in document:', actions);
}

authorize().then(md2docs).catch(console.error);

Both snippets are nearly identical in functionality, with the only differences being:

In JS, the DOCS API client object is local to this block where Python uses a global.
The last line of JS code runs authorize() and passes the returned authClient object to this main md2docs() function which can catch & log an exception.

Regardless of which language you're using, the recipe of this app is as follows:

Read and parse the Markdown contents
Create a new, empty Google Doc
Write the plain text string into the Doc
Make all the stylization requests in the Doc

Prerequisites/required setup

When running the scripts, the output follows that exact recipe. However, before you can run anything, take these required steps:

Create a new project from the Cloud/developer console or with the gcloud projects create . . . command; alternatively, reuse an existing project.
Enable the Google Docs API. Pick your preferred method of these three common ways to enable APIs:
- DevConsole manually -- Enable the API manually from the DevConsole by following these steps:
  1. Go to DevConsole
  2. Click on Library tab in the left-nav; search for "Docs", and enable
- DevConsole link -- You may be new to Google APIs or don't have experience enabling APIs manually in the DevConsole. If this is you...
  1. Check out the API listing page to learn more about the API and enable it from there.
  2. Alternatively, skip the API info and click this link for the enable button.
- Command-line (gcloud) -- Those who prefer working in a terminal can enable APIs with a single command in the Cloud Shell or locally on your computer if you installed the Cloud SDK which includes the gcloud command-line tool (CLI) and initialized its use.
  1. If this is you, issue this command to enable the API: gcloud services enable docs.googleapis.com
  2. Confirm all the APIs that have been enabled (by you or by default) with: gcloud services list
Create OAuth client ID & secret credentials and download to your local filesystem as client_secret.json. The code samples will not run without this file present.
Install Google APIs client library:
- NodeJS (16+): Install required packages with this command:
  - npm i (uses package.json)
  - Or install the packages manually: npm i googleapis @google-cloud/local-auth
- Python 2 or 3 (new auth): In your normal or virtualenv environment, run this command if using the current Python auth libraries (most everyone):
  - pip install -r requirements.txt (or pip3)
  - Or install the packages manually: pip install -U pip google-api-python-client google-auth-httplib2 google-auth-oauthlib
- Python 2 or 3 (old auth): If you have dependencies on the older Python auth libraries and/or still have old code lying around that do (see earlier sidebar), run this command to ensure you have the latest/last versions of these libraries:
  - pip install -r requirements-old.txt (or pip3)
  - Or install the packages manually: pip install -U pip google-api-python-client oauth2client (or pip3)
- For Python specifically, 2.x means 2.7, and if you're already planning to migrate to 3.x, you should definitely not be using anything older. For 3.x, it should work for nearly all releases, but 3.9 or newer are recommended.

Once you've done all of the above, you're ready to go. Oh, a quick word about costs running this app: there should be none.

⚠️ ALERT: Cost: "free" up to certain limits
While many Google products & APIs are free to use, not all of them are. While not totally "free," use of GWS APIs is covered completely by your monthly "subscription," whether you're a paid subscriber or have a free consumer Google account (with or without Gmail, which is optional), meaning a $0USD monthly subscription rate.

This "free" usage is not unlimited however... stay within the established quotas for each API. As expected, paid subscribers get more quota than free accounts. While not broadly published, you can get an idea of the limits on the Quotas page for Google Apps Script.

Running the script

Since we know the "recipe" of how this app operates, running them produce expected results, similar to what you see below, with some slight differences in the objects rendered by each language:

Python

$ python md2docs.py
** Parsed Markdown file 'quickbrownfox.md' & style actions
** Created 'quickbrownfox' (ID: bfENGvI9vCE2cabBCqv3Hq6qvFoL0nfDPfQZeZLY6ubQ)
** Inserted 'The quick, brown fox jumped over the lazy dogs.\n' into document
** Completed Markdown formatting in document: [('italic', 4, 17), ('bold', 37, 47)]

JavaScript

$ node md2docs.mjs
** Parsed Markdown file 'quickbrownfox.md' & style actions
** Created 'quickbrownfox' (ID: ATjQg2PqFQxqmiRNIi1TL9gjXBFWV7cw0i4ytGtddt7K)
** Inserted 'The quick, brown fox jumped over the lazy dogs.\n' into document
** Completed Markdown formatting in document: [ [ 'italic', 4, 17 ], [ 'bold', 37, 47 ] ]

If you could freeze the app and open the Google Doc at the exact moment after the plain text is added to the Doc, it would look something like this:

Plain text string inserted into Google Doc

However, unless you pause execution, it's an unlikely screenshot because formatting comes quickly thereafter, meaning you'll see the final result instead:

Stylization-formatted string in Google Doc

Summary and next steps

Now you know how to create a crudely-simplistic Markdown parser using regexes, but more importantly, learned how to use the Google Docs API to:

Create a new Google Doc
Write text to a Google Doc
Format text in a Google Doc

While the sample serves as a way to kickstart a very modest Markdown parser, the main goals are for readers to become familiar with the Docs API, which hasn't been around for that long (launched in 2017). If you wanted to support more complete Markdown syntax, you'd consider a package like markdown2 for Python or Showdown for Node.js.

If you pair the sample script demonstrated in this post and combine it with the sample in the exporting Google Docs as PDF files post, you'll have a solution that takes auto-generated Markdown files, produces formatted Google Docs, and exports corresponding PDFs for your organization or your customers.

You could also take things a step further: take valuable corporate data sitting in a massive set of CSV files, import them into Google Sheets, then leverage the Gemini API to produce summaries of the content, write out a collection of Google Docs, then produce PDFs for your boss/management, or perhaps even paying customers.

Those are just some ideas. The point of this imagination is to inspire you with what's possible, and what kinds of solutions you can build. I'll cover other GWS APIs in future posts. For fun, I'm also going to do a "codegen" (code generation) post where I ask LLMs ("large language models") like ChatGPT & Gemini to generate an app like this, discuss what I get, and compare/contrast.

Wrap-up

References

Below are various resources related to this post which you may find useful.

Code samples

Google Docs API

GWS APIs & OAuth2 information

Google APIs client libraries

Guide to modern app-hosting without servers on Google Cloud (Run)

Wesley Chun (@wescpy) — Tue, 14 Jan 2025 02:20:47 +0000

An in-depth intro to deploying apps on Cloud Run #serverless... TL;DR:

If you're looking to put code online today, you have many options, with virtual machines (VMs) or Kubernetes as the best choice for always-active apps with constant load. Apps with spiky, viral, unpredictable, and even no traffic tend to do better on serverless platforms, those where you don't need to know about nor manage servers. As far as app-hosting goes, Google Cloud (GCP) has App Engine and Cloud Run. App Engine is introduced elsewhere; this post explores its modern, contemporary sibling, Cloud Run.

[IMAGE] Serverless computing with Google

Introduction

Welcome to the blog focused on showing Python & Node.js developers how to integrate with Google technologies through its APIs and platforms. Here, you'll find content on GCP (AI/ML, serverless, Workspace (GWS; Docs/Drive, Sheets/Drive), Maps, Gemini, or YouTube, not to mention credentials basics like API keys and OAuth client IDs (primarily to access GWS APIs).

Before diving into this long-ish post, stop if you have apps getting constant traffic with predictable loads, because those app-hosting workloads generally do better with VMs on Kubernetes. Serverless tends to be a better fit for apps with unpredictable traffic such as social media, gaming, mobile backend services, startups/go-to-market solutions, student coursework or capstone projects, university research, enterprise intranet sites, and new apps or prototypes. If your apps are in the latter group, keep reading.

Google Cloud Run

If Google App Engine (GAE) is the "OG" serverless platform, Cloud Run (GCR) is its logical successor, crafted for today's modern app-hosting needs. GAE was the 1st generation of Google serverless platforms. It has since been joined, about a decade later, by 2nd generation services, GCR and Cloud Functions (GCF). GCF is somewhat out-of-scope for this post so I'll cover that another time.

📝 Google Cloud Functions is now Cloud Run functions
The 2nd generation GCF product was rebranded as Cloud Run functions in 2024, so expect to see this change if you start digging around for GVF documentation.

There is another post dedicated to introducing GAE, demonstrating how to deploy a "Hello World!" sample app to that platform, so check it out if interested. In this post, we're going to deploy the same app (but) to GCR, and the cumulative knowledge gives you the ability to deploy apps to both platforms.

⚠️ ALERT: Cost: billing required (but "free?!?")
While many Google products are free to use, GCP products are not. In order to run the sample apps, you must enable billing and a billing account backed by a financial instrument like a credit card (payment method depends on region/currency). If you're new to GCP, review the billing & onboarding guide. That said, deploying and running the sample app(s) in this post should not incur any cost because basic usage falls under the free tiers described below along with other important notes about billing:

Several GCP products (like GCR) have an "Always Free" tier, a free daily or monthly usage quota before incurring charges. See the GCR pricing and quotas pages for more information. Furthermore, deploying to GCP serverless platforms incur minor build and storage costs. (Also see similar content in the GAE docs.)

The Cloud Build system has its own free quota as does Cloud Storage (GCS), used to store build artifacts and built container images. The images themselves are also sent to the Cloud Artifact Registry (CAR) making them accessible to other GCP services. They eat into GCS & CAR (storage) quotas as does transferring images between services & regions. You may be in a region that does not have a free tier however, so monitor your usage to minimize any costs.

Use the cost calculator to get monthly estimates. You may qualify for credits to offset GCP costs: If you are a startup, consider the GCP for Startups program grants. If you are in education, check out the GCP education programs for students, faculty, and researchers.

Getting started

Deploying apps to GAE and GCR are similar, and the only differences lie with the configuration files. Both Python & Node.js apps can be found in this repo. I'll walk through each app, run it locally, then deploy to GCR after some setup, starting with Python.

Python

The Python repo features the main app source (main.py), a Python config file (requirements.txt), and the rest, config files for GCR/GCP:

File	Info	Purpose
`main.py`	(n/a)	Main Python application file
`requirements.txt`	info	3rd-party packages requirements
`Dockerfile`	info	Docker instructions on how to build container and start application
`Procfile`	info	Instructions on how to start application (without Docker)
`.dockerignore`	info	Filter files that should not go into container image
`.gcloudignore`	info	Filter files that should not be uploaded to GCP

[TABLE] GCR Python repo files

📝 Sample app Python 2 & 3 compatible
The sample app is Python 2 & 3 compatible. While Python 2 has been sunset by the community, many users have dependencies that haven't migrated to Python 3 (yet) or have apps they can't migrate for other reasons. GCR is one of the few remaining ways to deploy 2.x apps. The sample defaults to 3.x but contains a commented out directive to use a 2.x base image.

Application files

The requirements.txt file is to specify 3rd-party libraries. The only package listed is the Flask micro web framework, just like the GAE app'srequirements.txt file:

#gunicorn
flask

However, here and commented out but not available in the GAE app's requirements.txt, is Green Unicorn (gunicorn), an HTTP web server. GAE is pure PaaS (Platform-as-a-Service), but GCR, along with any container-based cloud service, is one step down, in-between PaaS and IaaS (Infrastructure-as-a-Service).

As a lower-level service, GCR doesn't provide a web server like GAE does... you have to bring your own. For the purposes of the demo, the Flask development server suffices, but Gunicorn can be easily selected once your app makes its way towards production.

Now let's look at main.py:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def root():
    return 'Hello World!'

# local-only
if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

It's line-by-line identical to the GAE main.py: The Flask library is imported, and the Flask app is instantiated. The only route is /, returning 'Hello World!' for GET requests. The last few lines run the Flask development server in debug mode on port 8080 if the PORT environment variable isn't set. It's only started when running main.py as a script (per the if block). (When starting a real server, this entire block is ignored.)

Running locally with Flask (optional)

It's a good idea to test apps locally before deploying to the cloud, so let's install any required packages. In your regular or virtual environment (virtualenv), execute: pip install -r requirements.txt (or pip3 if you also have Python 2 installed). Fresh installs result in output like this:

$ pip3 install -r requirements.txt
Collecting flask (from -r requirements.txt (line 2))
  Downloading flask-3.1.0-py3-none-any.whl.metadata (2.7 kB)
Collecting Werkzeug>=3.1 (from flask->-r requirements.txt (line 2))
  Downloading werkzeug-3.1.3-py3-none-any.whl.metadata (3.7 kB)
Collecting Jinja2>=3.1.2 (from flask->-r requirements.txt (line 2))
  Downloading jinja2-3.1.5-py3-none-any.whl.metadata (2.6 kB)
. . .
Downloading jinja2-3.1.5-py3-none-any.whl (134 kB)
Downloading werkzeug-3.1.3-py3-none-any.whl (224 kB)
Downloading MarkupSafe-3.0.2-cp313-cp313-macosx_10_13_universal2.whl (14 kB)
Installing collected packages: MarkupSafe, itsdangerous, click, blinker, Werkzeug, Jinja2, flask
Successfully installed Jinja2-3.1.5 MarkupSafe-3.0.2 Werkzeug-3.1.3 blinker-1.9.0 click-8.1.8 flask-3.1.0 itsdangerous-2.2.0

With dependencies installed, start the Flask "devserver" with python main.py (or python3):

$ python3 main.py
 * Serving Flask app 'main'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:8080
 * Running on http://192.168.1.147:8080
Press CTRL+C to quit
 * Restarting with watchdog (fsevents)
 * Debugger is active!
 * Debugger PIN: 872-970-164

With a running server, point a web browser to http://localhost:8080:

[IMAGE] "Hello World!" sample app running locally

In your terminal, you'll see log entries for each HTTP request:

127.0.0.1 - - [03/Jan/2025 22:34:45] "GET / HTTP/1.1" 200 -
127.0.0.1 - - [03/Jan/2025 22:34:45] "GET /favicon.ico HTTP/1.1" 404 -

To exit the devserver, issue a ^C (Control-C) on the command-line. In the next section, we'll look at another way to run the app locally.

Remaining configuration file(s)

The other config files specify how the app should be containerized, started, and deployed to the cloud. That's the reason why none of them were used to run the app locally just a moment ago. (There is another way to run it locally, with the help of Docker, and we'll take a look at that shortly.) The .*ignore files for this app filter out content that doesn't have anything to do with an app's functionality:

.dockerignore -- keeps out files that shouldn't go into a container image
.gcloudignore -- filters out files that do not need to be deployed to GCP

The .*ignore files have much in common; the main difference is that package & build files may be needed to build the container but don't need to be deployed to the cloud because they don't play a part in running the app.

The last pair of config files, Dockerfile and Procfile, are the most important: One is required to deploy this app to GCR, and how your containerized app should be built determines which you choose. Let's talk about your options, starting with the Dockerfile.

Using Docker

This is the Python app's Dockerfile:

FROM python:3-slim
#FROM python:2-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENTRYPOINT ["python", "main.py"]
#ENTRYPOINT exec gunicorn -b :$PORT -w 2 main:app

These instructions tell Docker how to build the container image and how to start the app within. Its contents are described in this table:

Directive	Explanation
`FROM`	Base image to build your container from, a minimal Python 3 installation
`FROM` (commented out)	Use minimal Python 2 base image
`WORKDIR`	Work directory for files going into your container
`COPY`	Copies 3rd-party package file, `requirements.txt` into work directory
`RUN`	Executes `pip install` command to install 3rd-party packages listed in `requirements.txt`
`COPY`	Copies all files into the work directory (including `requirements.txt` again)
`ENTRYPOINT`	Starts app via Flask devserver
`ENTRYPOINT` (commented out)	Starts app via Gunicorn server

[TABLE] Python app `Dockerfile` directives

Running locally with Docker (optional)

With Docker, you can build a container locally and run it, providing an alternative way to test locally before any cloud deployment. It also better simulates how GCR will run your app as well. Ignore the other configuration file, Procfile, for now. While it usually doesn't conflict with the Dockerfile, there are some situations in which a conflict may arise. To avoid this, temporarily rename, delete, or move Procfile elsewhere. With just the Dockerfile present, run these commands to build the container and run the app:

docker build -qt test .
docker run -p 8000:8080 -t test

The build command is as advertised: it builds your container image, naming it test (-t "tag" option) and outputs the unique hash for your container. Drop the optional -q ("quiet") flag to see all kinds of Docker output when building the image.

The run command runs the named container (via -t) and redirects the Flask devserver output to your terminal. It maps requests from port 8000 of your development machine to 8080 in the container (via -p).

Execute both commands as listed and expect output like below, including the Flask request logs like we saw earlier. Be sure to hit the app at http://localhost:8000 -- that's port 8000, not the Flask devserver's 8080 like when running Flask directly earlier:

$ docker build -qt test .
sha256:67b5062c93552271f0d334e3b7e8ef9a83244438cfdbe7a56b117a5d50da70f8

$ docker run -p 8000:8080 -t test
 * Serving Flask app 'main'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:8080
 * Running on http://172.17.0.2:8080
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 257-974-169
172.17.0.1 - - [02/Jan/2025 08:26:25] "GET / HTTP/1.1" 200 -
172.17.0.1 - - [02/Jan/2025 08:26:26] "GET /favicon.ico HTTP/1.1" 404 -

Use ^C (Control-C) to quit the devserver as before, exiting the container. Now you know two different ways to run your app locally. Now let's move beyond Docker & Dockerfile and look at the Procfile.

NOT using Docker

The other way to run a containerized app on GCR is to not use Docker explicitly. If the Dockerfile is missing, Cloud Build uses Buildpacks, a tool built on open standards that automatically inspects application files and dynamically determines the best way to build & containerize apps. This is clearly the option for those new to Docker, don't know Docker, want to avoid Docker, or don't even think about containers. More specifically, Buildpacks adopted by Google is how images can be built & deployed on GCR without Docker.

While you don't have to know anything about Docker when using Buildpacks, having a .dockerignore file is still useful in terms of filtering out files that make building a container inefficient, and most Buildpacks implementations honor the ignore file. The one caveat for Python apps is that without a Dockerfile's ENTRYPOINT directive, it doesn't know how to start your app, and that's why the Procfile is required when not using Docker.

To opt for Buildpacks instead of Docker, move, rename, or remove the Dockerfile. Look inside the Procfile to find the equivalent of Dockerfile's ENTRYPOINT directive describing how to start your app:

web: python main.py
#web: gunicorn -b :$PORT -w 2 main:app

Like the Dockerfile, there's a 2nd, commented-out alternative ENTRYPOINT for using Gunicorn instead of the Flask devserver.

You can install the Buildpacks pack tool to create a containerized app image, but without Docker, you can't run it locally. So for this app, your only local testing option is the Flask devserver.

Python app summary

Python users have a choice for testing apps locally: 1) use Flask devserver, or 2) build a container & run it with Docker.
To deploy this app to GCR, choose between using Docker (Dockerfile) and not using Docker (Procfile) (remember to move/remove the other config). Either way, keep the .dockerignore file to minimize container size and image build time.
When ready to go live, switch from the Flask devserver to something more production-worthy, such as Gunicorn, uWSGI, nginx, or uvicorn.

Node.js

Node developers, it's your turn. Here's what's in this repo:

File	Info	Purpose
`index.js`	(n/a)	Main Node app file (CommonJS)
`index.mjs`	(n/a)	Main Node app file (ESmodule)
`package.json`	info	3rd-party packages requirements
`Dockerfile`	info	Docker instructions on how to build container and start application
`.dockerignore`	info	Filter files that should not go into container image
`.gcloudignore`	info	Filter files that should not be uploaded to GCP

[TABLE] GCR Node repo files

Application files

Python has Flask, and similarly, Node has the Express micro web framework, the only 3rd-party package found in Node's 3rd-party packages requirements file, package.json:

{
  "name": "helloworld-nodejs",
  "version": "0.0.1",
  "description": "Node.js Cloud Run sample app",
  "main": "index.mjs",
  "scripts": {
    "start": "node index.mjs"
  },
  "author": "CyberWeb Consulting LLC",
  "license": "Apache-2.0",
  "dependencies": {
    "express": "^4.17.1"
  }
}

The app can be found in index.mjs:

import express from 'express';
const app = express();

app.get('/', (req, rsp) => {
  rsp.send('Hello World!');
});

const PORT = process.env.PORT || 8080;
app.listen(PORT, () =>
  console.log(`Listening on port ${PORT}`)
);
export default app;

There's also a CommonJS version, index.js for those who prefer it. With either version, app instantiation is followed by the GET handler returning "Hello World!". The rest sets up the server on the designated PORT and exports the app. Unlike Flask, the Express server is much more performant and can be used in production, perhaps with the help of tools like cluster and PM2.

Running locally with Express.js (optional)

As mentioned earlier, while running locally is optional, it's a good practice. Install the required packages first:

$ npm i

added 69 packages, and audited 70 packages in 2s

found 0 vulnerabilities

You'll see the expected node_modules folder and package-lock.json file. Now launch it with npm start:

$ npm start

> helloworld-nodejs@0.0.1 start
> node index.mjs

Listening on port 8080

Express doesn't log HTTP requests -- developers have to add middleware to them, so don't expect request output like Flask. What is the same is the "Hello World!" you see in your browser when you hit the app at http://localhost:8080. Exit the server with ^C (Control-C).

Remaining configuration file(s)

The remaining config files are: Dockerfile, .dockerignore, and .gcloudignore, identical in functionality to their Python cousins. There's no Procfile because package.json already contains app startup (npm start) instructions.

Running locally with Docker (optional)

You can also build a container and run the app locally with Docker and the Node Dockerfile:

FROM node:22-slim
WORKDIR /app
COPY package.json .
RUN npm i
COPY . .
ENTRYPOINT ["node", "index.mjs"]

It's basically equivalent to the Python version. The docker command-line instructions to build and run the container are also the same: docker build -qt test . and docker run -p 8000:8080 -t test.

$ docker build -qt test .

sha256:83741dbff139d5bdf09f28cde681e4455828102d75064f99c95708d37d8735e3

$ docker run -p 8000:8080 -t test
Listening on port 8080

After running both commands and starting your container, hit the server at http://localhost:8000. Again, don't expect any Express output on requests. Press ^C to exit as before.

Deploying apps to Cloud Run

Whether via the server or through Docker, you're in good shape to deploy to the cloud if you ran your app locally. The next step is to deploy it to the cloud so that it's accessible globally... let's start with some GCP setup.

📝 Container runtime contract
There are some restrictions your app must adhere to in order for GCR to run your container successfully; the most important pair:

Your app must be stateless. Don't use embedded databases. When your users hit your app again, they may be reaching another instance in a completely different state. Persist data in cloud-based storage like GCS, Cloud SQL, or Cloud Firestore.

Leave a port, say 8080 or another port, open so GCR can reach your app.

A basic web app may have architecture similar to this illustration:

[IMAGE] Sample web app architecture for GCR/GCP

For more information, see the Container runtime contract page in the documentation.

Google Cloud SDK

The gcloud command-line tool (CLI) can deploy apps to both GAE and GCR. Unlike GAE however, GCR also lets you deploy apps from the Cloud console once your code or container image are in known places.

The gcloud CLI comes with the Cloud SDK (software development kit). If it's already installed, skip to the next section. New to GCP? Follow the instructions to install the SDK and learn a few gcloud commands. If you just want to install the SDK, see these instructions. After installation, run gcloud init to initialize it.

Google Cloud projects

A GCP project is required to manage all the resources, e.g., APIs, compute, storage, etc., for an app. Create a new one or reuse an existing project. Then assign a billing account to that project if you haven't already. (Review the cost sidebar above for cost details if you missed it earlier.)

Project identifiers

Every project has an ID and a number. (Projects also have names, but that's out-of-scope for this post.) A project ID is a unique string identifier chosen by you at project creation or automatically assigned if you don't specify one; it cannot be updated once a project is created. A project number is a unique numeric identifier automatically assigned by GCP and cannot be updated.

These project identifiers can be found in the Cloud console at https://console.cloud.google.com/iam-admin/settings. You can also run the gcloud projects list to see all identifiers for all projects.

Most of the time, you use a project ID, such as when deploying your service. For your convenience, set the default project ID with this command: gcloud config set project PROJ_ID. If you don't set a default, pass it in with --project PROJ_ID with each gcloud command, else you'll be prompted for it. The project number is used much less frequently, such as in GCR service URLs we'll dive into next.

Service URL(s)

GAE refers to a running service as "apps" with a restriction that all projects can only have one app and only be based in one region. GCR calls apps "services" and has fewer restrictions. GCR can create any number of services, and on top of that, services are deployable to different regions. No such luxury with GAE! Like all GAE apps though, each GCR service comes with a free, default URL, SVC_NAME-PROJ_NUM.REGION.run.app, where:

URL component	Description
`SVC_NAME`	Name you chose for your service
`PROJ_NUM`	Project number (not to be confused with project ID)
`REGION`	Region you deployed your service to

[TABLE] GCR free domain name components

These deterministic URLs, based on these known components, are predictable enough that when going to production, allow you to map custom domains at them. GCR services have another service URL, less predictable and no longer recommended for use. (See the sidebar below for more details.)

📝 Deterministic vs. non-deterministic service URLs
Prior to 2024, GCR service URLs were not as deterministic: `SVC_NAME-HASH-REG_ABBR.run.app`. The service name (`SVC_NAME`) is the same as described above, but rather than a project number, a random `HASH` value is generated, and instead of a full region name, a somewhat cryptic region abbreviation (`REG_ABBR`) is used. While these URLs are stable once created, deterministic URLs are more predictable and easier to use. Deterministic URLs became generally available in Sep 2024 and became prioritized at that time.

📝 Deterministic vs. non-deterministic service URLs

Prior to 2024, GCR service URLs were not as deterministic: SVC_NAME-HASH-REG_ABBR.run.app. The service name (SVC_NAME) is the same as described above, but rather than a project number, a random HASH value is generated, and instead of a full region name, a somewhat cryptic region abbreviation (REG_ABBR) is used. While these URLs are stable once created, deterministic URLs are more predictable and easier to use. Deterministic URLs became generally available in Sep 2024 and became prioritized at that time.

Set your environment up for deployments

Confirm you've completed these setup tasks:

Install GCP SDK (includes gcloud CLI)
Create new or reuse existing GCP project
Enable billing & assign billing account
Run gcloud init
(optional) Run gcloud config set project PROJ_ID

Build & deploy: single, combination command options

To deploy an app to GAE, you'd use gcloud app deploy. The equivalent for GCR is gcloud run deploy, GCR deploy commands provide more options than GAE, so commands are typically longer. (If they're too long, you can put all build criteria inside a cloudbuild.yaml config file. A realistic deploy command looks like this: gcloud run deploy SVC_NAME --allow-unauthenticated --source . --region REGION

What does it all mean? Let's break it down:

Command-line entity	Description/purpose
`gcloud run deploy`	Base command
`SVC_NAME`	Choose a name for your service
`--allow-unauthenticated`	Make this a public service, else it'll be authenticated (restricted by IAM permissions)
`--source .`	Deploy from source code (vs. registered container image -- more on this below)
`--region REGION`	Choose a region to deploy your service to (where you anticipate most of your users are)

[TABLE] GCR deployment command components

The service name (SVC_NAME) is required.
The --allow-unauthenticated flag opens it up globally, making the app easy to try/test; turn on authentication when moving to production (if not a public website)
Provide the --region flag and region or else be prompted interactively for it.
You can deploy an app: 1) from source code (--source DIRECTORY) or 2) from an already built & registered container (--image IMG_NAME).

Most of the above are self-explanatory but the last pair can do with a bit more explanation:

Region: GAE allows only one app per project which is locked forever to a single region. In sharp contrast, you can deploy any number of GCR services and to any supported region, and regardless of which region it is hosted in, a GCR service is accessible globally.
Source builds: We're deploying this basic app directly from source code, but if you've got a good working build (image) and wish to deploy multiple services, likely to different regions, it's inefficient to build the same container image over and over again. You could also run into inconsistencies if somehow the code changed between those builds.

Build & deploy: multiple, separate commands and options

To avoid the inconsistent build scenarios, "build once and deploy at least once" can be accomplished by splitting up the single, combo gcloud run deploy command from above into a pair, one to build and the other to deploy:

gcloud builds submit --tag pkg.dev/PROJ_ID/REPO/IMG_NAME (Docker) or gcloud builds submit --pack image=pkg.dev/PROJ_ID/REPO/IMG_NAME (Buildpacks)
gcloud run deploy SVC_NAME --image pkg.dev/PROJ_ID/REPO/IMG_NAME

The first command builds a container image and registers it with CAR (*.pkg.dev registry "domain"). (If you run across gcr.io registry "domains", they're from CAR's deprecated predecessor, Container Registry.) The gcloud builds submit command builds a container image and registers it.

Registered container images can be deployed as new services, avoiding repeated builds. If you're familiar with Docker, gcloud builds submit is similar to docker build and docker push while gcloud run deploy would be docker run.

But, if you're just experimenting and don't plan to deploy multiple services with the same image, you can stick with the single combo, all-in-one gcloud run deploy command from the last section.

Deploy to the cloud

Formalities aside, let's deploy these sample apps to GCR. For brevity, I'm sticking with:

Source-only deployments (--source .)
A set default project ID (else use --project PROJ_ID or be prompted)
Allowing unauthenticated traffic (--allow-unauthenticated)
The service name of hello
The us-west1 region (--region; else be prompted)

These result in the following deployment command: gcloud run deploy hello --allow-unauthenticated --source . --region us-west1

Now I'll use that command to deploy the app in these configurations:

Python with Docker
Node.js with Docker
Node.js (without Docker) with Buildpacks

Pick your own service name and region if you wish; adjust your command-line options accordingly.

Python with Docker

The Dockerfile didn't conflict with the Procfile in my build-and-deploy below but feel free to rename or remove Procfile temporarily if you have issues. Go to the python folder and run the gcloud run deploy command... your output will look similar to:

$ gcloud run deploy hello --allow-unauthenticated --source . --region us-west1
Building using Dockerfile and deploying container to Cloud Run service [hello] in project [PROJ_ID] region [us-west1]
✓ Building and deploying... Done.
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/c2ab2b1a-cec0-4686-bc77-d6a809fd7c3d?project=PROJ_NUM].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [hello] revision [hello-00004-ds8] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-PROJ_NUM.us-west1.run.app

Node.js with Docker

If you switching to the nodejs folder, issue the same command:

$ gcloud run deploy hello --allow-unauthenticated --source . --region us-west1
Building using Dockerfile and deploying container to Cloud Run service [hello] in project [PROJ_ID] region [us-west1]
✓ Building and deploying new service... Done.
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/a4f4ceda-abe8-4116-a30a-8aa5f5cc4279?project=PROJ_NUM].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [hello] revision [hello-00001-9r2] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-PROJ_NUM.us-west1.run.app

Notice there's no difference to the commands at all: Everything the build system needs is in the Dockerfile. Both result in the app deployed (regardless of language) and available globally at the same URL.

Node.js with Buildpacks

Let's say you're not familiar with Docker or prefer not to use it. Delete, move, or remove Dockerfile and issue the same command... the app also deploys successfully, thanks to Buildpacks:

$ gcloud run deploy hello --allow-unauthenticated --source . --region us-west1
Building using Buildpacks and deploying container to Cloud Run service [hello] in project [PROJ_ID] region [us-west1]
✓ Building and deploying... Done.
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/0140d524-ecc1-4b97-9079-5695c03d9e01?project=PROJ_NUM].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [hello] revision [hello-00002-z6n] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-PROJ_NUM.us-west1.run.app

Browse Cloud Build log via the link to see how your service was built and deployed. Our Node.js Dockerfile specifies a Node 22 slim base image, but without it, you're dependent on Buildpacks default runtime versions at build-time. In the last deployment above, Buildpacks used Node 20 because the default hasn't moved up to version 22 yet. So if you're targeting a specific release, using Docker (and Dockerfile) is your best bet.

Globally-accessible and scalable on GCR

For any of the deployments above, hitting the "Service URL" shown at the end of your build command with a browser should look just like your locally-deployed version(s) but are now globally-accessible:

[IMAGE] "Hello World!" sample app running on GCR/GCP

Not only are your GAE apps & GCR services available around the world, they autoscale as well. GCP serverless platforms spin up more instances on-demand based on traffic then winds them down as things subside, all without explicit action on your part.

Congrats on successfully deploying the demo app(s) to GCR!

Summary and next steps

Now that you've taken a working Python or Node sample app, tested it locally, and successfully deployed it to GCR/GCP, continue to experiment by updating the code and redeploying, uploading one of your "real" apps, or check out the equivalent GAE post to see how to deploy the same app to that platform. While GCR is newer and has fewer restrictions, that post points out some of the reasons why you may still consider GAE. Regardless of next steps, you now have a new option for running apps in the cloud, and nowhere did you consider allocating, configuring, or paying for a server 24x7.

Billing epilogue

If you want to keep the demo GCR service around, great. Even though it's not a free service, there's a monthly free quota you have to consume in order to incur billing. However, if no one is accessing your app, one of the benefits of serverless is that you're not paying. If someone discovers your app's URL though, or you continue to deploy new versions, this will eventually lead to billable usage. If you're not ready to continue experimenting with GCR or the deployed app, you have several options (from least-to-most "severe"):

Stop GCR service option	Description
Disable service	Temporarily disable service to avoid incurring additional charges; can be re-enable any time.
Delete service	Delete & remove service; cannot be "un-deleted", but you can redeploy again later.
Shutdown project	Delete service, billing, and all project resources if you don't want to continue using it with GCR or other GCP services; cannot restore a project 30 days after it has been shut down.

The first pair of options help you avoid charges from a running service, but bear in mind the storage costs for GCS and AR as described earlier may still apply, so delete enough build artifacts to fall under any limits you may be exceeding. The last option "wipes the slate clean" where you no longer have to worry about billing at all.

Other GCR features

GCR has other features worth exploring... subjects of future posts. Preview to get a head start:

GCR feature	Description
HTTP & event-driven triggers	Services can be event-driven in addition to being "triggered" with HTTP requests; learn other ways to kick off work on GCR
Jobs	Run tasks start-to-finish outside of HTTP/S requests, e.g., batch processing; can run for up to 24 hours
Functions	Don't have an entire app? Got snippets of code to run that doesn't involve a "full stack"? Functions are great for microservices, mobile backends, etc.

Wrap-up

If you found an error in this post, a bug in the code, or have a topic I should cover, drop a note in the comments below or file an issue at the repo.

If you have older GAE apps and considering a move/port to GCR, want to upgrade from Python 2 to 3 or migrate off GAE bundled services, I may be able to help... check out https://appenginemigrations.com and submit a request there.

I enjoy meeting users on the road... see if I'll be visiting your community in the travel calendar on my consulting page.

References

Below are various resources related to this post which you may find useful.

Blog post code samples

GCR resources & historical references

Generating audio clips with Gemini 2.0 Flash

Wesley Chun (@wescpy) — Mon, 16 Dec 2024 17:20:00 +0000

TL;DR:

Happy holidays! Google recently "gifted" us the new Gemini 2.0 Flash model, expanding on what's available in the original 1.x models. One of the new features is the ability to generate text-based audio clips. Sure good ol' fashioned predictive AI's text-to-speech (TTS) functionality is certainly useful, but this takes it to the next level, giving genAI users "idea-to-speech" capabilities. Learn how to access this new feature from Python today!

UPDATE (Jun 2025): this post uses the Gemini 2.0 Flash Experimental model, but since publication, Google has launched additional models that can generate audio. See this chart for the capabilities of all Gemini models, including several Gemini 2.5 models featuring TTS output.

Introduction

Welcome to the blog focusing on using Google APIs from Python (and sometimes Node.js). Today's post focuses on Gemini, but you'll find plenty of content beyond Gemini in other posts:

Google Cloud/GCP: serverless, and AI/ML
Google Workspace/GWS (Drive, Docs, Sheets, Gmail, etc.)
YouTube
Google Maps/GMP
Credentials (API keys, OAuth client IDs, service accounts)

Today, we're taking a break from the flow of the previous posts in this series covering the Gemini API by exploring one new feature. While some users may be content using ChatGPT or Gemini online or via app, the Gemini API brings generative AI abilities to your apps, so if you're new or exploring, check out the other posts on how to get started as well as see some of its basic capabilities. This post only looks at one feature from the Gemini 2.0 Flash model: text-based audio clip generation.

Prerequisites

New client library improves user experience (UX)

You need a client library to talk to Gemini from code. While several client libraries already exist for Gemini, Google has recently introduced a new one. The new library features an improved UX, so I have to give Google some credit. In the first Gemini post in the series, I lamented that making the API available from two different platforms confuses developers:

Differing client libraries, numerous code samples, documentation in different locations under different web domains, etc., all add to a less-than-optimal UX. A replacement client library with the ability to work across platforms allows users to get started and experiment on Google AI then "upgrade" to Vertex AI, when ready for production, without changing their code.

💡 Yes, it's an "ifdef"
If you're like me and like to dig around in code, you may be curious about how the new client library works across both Google AI and Vertex AI. It's not magic, so you'll find if-else blocks where it matters, like a C/C++ ifdef. In the new client library, any time you see mldev, think Google AI, and as expected, vertex is Vertex AI.

One example is found the Live API code while another is in the models code. (NOTE: these links will probably be wrong when a new version is pushed, but I'll update them once the library has an official release)

You'll find the new client library on the Gemini API SDKs page. Today's sample app is only available in Python^.

^{^} -- Python 3 only; Python 2 support is not available for the Gemini API

Installation and setup

As we're exploring this new feature, the app will run on Google AI. In an upcoming post, we'll explore how to run the same app on Vertex AI. So follow these steps to install the client library and get set up:

Install the new client library: pip install -U google-genai
Create an API key (if you don't already have one)
Save API key as a string to settings.py as API_KEY = 'YOUR_API_KEY' (and follow the suggestions in the sidebar below to protect it)

⚠️ WARNING: Keep API keys secure
Storing API keys in files (or hard-coding them for use in actual code or even assigning to environment variables) is for prototyping and learning purposes only. When going to production, put them in environment variables or in a secrets manager. Files like settings.py or .env containing API keys are susceptible. Under no circumstances should you upload files like those to any public or private repo, have sensitive data like that in TerraForm config files, add such files to Docker layers, etc., as once your API key leaks, everyone in the world can use it.

If you're new to Google developer tools, API keys are one of the credentials types supported by Google APIs, and they're the only type supported by Maps APIs. Other credentials types include OAuth client IDs, mostly used by GWS APIs, and service accounts, mostly used by Google Cloud (GCP) APIs. While this post doesn't cover Google Maps, the Maps team put together a great guide on API key best practices, so check it out!

The app

The sample app gem20-audio.py sends a prompt of Describe a cat in a few sentences to Gemini and requests an audio clip in response, so the app's functionality is pretty brief: make the request, get the response, and save the audio file.

The code

import asyncio
import contextlib
import wave

from google import genai
from settings import API_KEY

GENAI = genai.Client(api_key=API_KEY, http_options={'api_version': 'v1alpha'})
MODEL = 'gemini-2.0-flash-exp'
CONFIG = {'generation_config': {'response_modalities': ['AUDIO']}}
PROMPT = 'Describe a cat in a few sentences'
FILENAME = 'whatacatis.wav'

@contextlib.contextmanager
def wave_file(filename, channels=1, rate=24000, sample_width=2):
    'set up .wav file writer'
    with wave.open(filename, 'wb') as wf:
        wf.setnchannels(channels)
        wf.setsampwidth(sample_width)
        wf.setframerate(rate)
        yield wf

async def request_audio(prompt=PROMPT, filename=FILENAME):
    'request LLM generate audio file given prompt'
    print(f'\n** LLM prompt: "{prompt}"')
    async with GENAI.aio.live.connect(model=MODEL, config=CONFIG) as session:
        with wave_file(filename) as f:
            await session.send(prompt, end_of_turn=True)
            async for response in session.receive():
                if response.data:
                    f.writeframes(response.data)
    print(f'** Saved audio to "{filename}"')

asyncio.run(request_audio())

[CODE] gem20-audio.py: Audio "Hello World!" sample

App components

There are 4 major chunks to this script:

Imports
Constants
Audio file writer
Core functionality

Imports

From the Python standard library, asyncio is required because the Multimodal Live API (feature and usage) is only available asynchronously. The contextlib.contextmanager decorator is needed so we can wrap and use the audio file-writer with Python's with statement. The last "stdlib" package used is wave, which processes WAVE audio files. This is followed by importing Google's new "genAI" client library.

Like in previous code samples in this series, the API key is saved to settings.py. Alternatively, you can save your API key to the GEMINI_API_KEY environment variable (and avoid having .env or settings.py files. If Python users want it in a file but want to store it in .env instead of settings.py, use the python-dotenv package which more closely mirrors a Node.js environment. There's also the GCP Secret Manager as yet another option.

Constants and audio file writer

Constants for the API client, generative large language model (genAI LLM), and model configuration follow. The last pair of constants are the user's prompt and filename to save the generated audio to.

The WAV file (wave_file()) writer just sets up the basic parameters as a generator and wraps it in a context manager, allowing it to be used with the with statement. You'll find nearly-identical code in various samples and Notebooks in the Gemini 2.0 cookbook repo.

Core functionality

All of the "real work" takes place in request_audio(). It's a single session using the Live API, kicking it off by opening the WAV file for write and sending the prompt to the LLM. The rest of it continuously waits for a server response, writing the chunks of audio data received until it's been exhausted, terminating the session.

This is minimal code required to do the job. In other examples from Google, you'll find reference to server_content, inline_data and writing out parts. Most of this relates to supporting a multi-turn conversation, but for a single request-response "cycle," less code is less confusing.

Running the script

Running the script produces an audio file along with the expected output:

$ python3 gem20-audio.py

** LLM prompt: "Describe a cat in a few sentences"
** Saved audio to "whatacatis.wav"

Your mileage may vary, but this is the audio track I got from Gemini:

Summary

Developers are eager to jump into the world of AI/ML, especially GenAI & LLMs, and accessing Google's Gemini models via API is part of that picture. The previous posts in the series got your foot in the door, and today, we explore a new feature available from Gemini 2.0 Flash. In upcoming posts, we'll continue this journey by describing how to run it from Vertex AI.

If you want to see Gemini API code for both platforms, check out the intro (1st) post in this series. In another future post, we'll pick up the basic genAI web app from the previous (3rd) post (link also below) and show you how to deploy it to Google Cloud.

If you find errors or have suggestions on content you'd like to see in future posts, also leave a comment below, and if your organization needs help integrating Google technologies via its APIs, reach out to me by submitting a request at https://cyberwebconsulting.com. Thanks for reading, and I hope to meet you if I come through your community... you'll find my travel calendar at the bottom of that page as well. Season's greetings and see you next year!

PREV POST: Part 3: Gemini API 102a... Putting together basic GenAI web apps
NEXT POST: Part 5: Generating images with Gemini 2.0 Flash

References

Below are various links relevant to this post:

Code samples

Gemini API (Google AI)

Gemini 2.0 Flash

Other Generative AI and Gemini resources

What is the world's "easiest" Google API?!?

Wesley Chun (@wescpy) — Mon, 02 Dec 2024 06:43:55 +0000

TL;DR:

While I generally cover Google API usage from a functionality perspective, at some point, I wondered which one of them was the easiest to use. Could it be easy enough where developers can use it without a computer, client library, OAuth2, SDK, or even code? It's Fall 2024, and I find myself on the road again, for work and for the holidays. This means some of us are thinking about Google Maps, so it's no coincidence the one I found meeting the aforementioned requirements and gets the title of the world's easiest Google API goes to the Maps Static API. To use it, you only need HTTP and an API key... wow(!), stick around to learn more!

Introduction

Welcome to the blog covering use of Google APIs, generally from Python and sometimes Node.js (but not today because you can use this API without code)! Here, I show developers how to use a variety of Google APIs and share tips-n-tricks not documented by Google, covering a broad variety of topics like:

Google Cloud/GCP (serverless, AI/ML)
YouTube
Google Workspace/GWS (Drive, Docs, Sheets, Gmail, etc.)
Generative AI with Gemini
Google Maps (this series)
Credentials (API keys, OAuth client IDs, service accounts)

Regardless of which Google APIs you look at, one of them has got to be the "easiest" to use, right?

Google Maps Static API

A few years back, I wrote an interesting app that uses four different Google APIs to address a fictitious but possible business use case. Earlier this year, I upgraded it by adding use of two more Google APIs, one of them being the Maps Static API. I soon realized it was unlike any other Google API I've ever used: no client library import, no instantiating an API client object, no OAuth2, and no API function calls in my code. "API calls" are URL-based HTTP GET requests.

The only "security" required is an API key (true for all Maps APIs). Check the documentation on how to get & use API keys if needed. But, before using the API, let's discus what it is first!

Background

At its heart, the Maps Static API returns a map image (default: PNG) in response to an HTTP request via a URL. The service creates a map based on URL parameters sent via the HTTP request and returns the map image as the response. For each request, specify the location to show, the image size, and optionally, the zoom level, type of map, and placement of optional markers at locations on the map.

Because all of the "action" happens via URL, you can use the API to embed a Google Maps image on a web page, without requiring JavaScript or dynamic page loading. You can also temporarily store the image binary and render it later.

However, you cannot distribute the map image, sell it, transfer it to any 3rd-party service, cache or store it for more than 30 days or in an insecure way, manipulate it, or modify its attribution in any way. These and other restrictions can be found in the Maps API Terms of Service. Now that you know what it is, let's look at a few examples of how to use the Maps Static API.

Parameters

The following pair of parameters are required for all Maps Static API requests:

Parameter	Description
`key`	Your API key (string); ex: `UfwmmjcXOgfV9TviafMPUjYXVP-iQAWbqRmZ7WE` (not a real one)
`size`	Image dimensions (string); ex: `480x480`

Maps Static API required parameters

The location parameters in the table below are pseudo-required. If you wish to put a specific location (or locations) on a map with a marker, then the markers parameter is required. Otherwise, both center and zoom parameters are required.

Parameter	Description
`markers`	Location by which to center the map image highlighted with a marker (string); exs:`Googleplex`, `1600 Amphitheatre 94043`, "`37.4226277,-122.0841644`", etc.
`center`	Location by which to center the map image with (string); exs: (same as `markers` above)
`zoom`	Magnification of generated map (integer from 1-20, inclusive); ex: `16`

Maps Static API pseudo-required parameters

For center or markers, you need to provide a minimal string for the Maps service to find the location. Examples include a landmark name, street address, city & state, postal code, or latitude-longitude pair, to name a few.

The zoom level is an integer representing the magnification of the generated map. It must be an integer between 1 and 20. A zoom level is optional if markers is provided, defaulting to a zoom level of 16. The table below illustrates zoom levels and representative magnification views:

Zoom level	Representative view
1	World
5	Landmass/continent
10	City
15	Streets
16	(default)
20	Buildings

Maps Static API zoom levels

Examples

Below are numerous examples of using the API, demonstrating its capabilities as well as how to use the parameters above.

Example set 1: Basic location with markers

Let's say you wanted a map of Google's headquarters, known as the "Googleplex" (or other landmarks or locations)

Map with marker on landmark: Issue the following request with the key, size, and markers parameters: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex Map pinned to landmark
Map with marker on street address: If you prefer using street addresses instead: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=1600+Amphitheatre+94043 Map pinned to street address
Map with marker on geolocation: If you prefer using geolocation (latitude-longitude pairs): https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=37.4226277,-122.0841644 Map pinned to geolocation

Notice that the three markers don't land on exactly the same spot even though the destination is the same. In certain situations, you may prefer not to use markers, so let's explore that.

Example set 2: Basic location without markers

Because markers is used on all the above examples, the zoom level is optional, defaulting to 16. If you want the same maps as the above but without markers on maps, provide both center and zoom:

Map of landmark: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&zoom=16&center=Googleplex Map of landmark
Map of street address: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&zoom=16&center=1600+Amphitheatre+94043 Map of street address
Map of/from geolocation: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&zoom=16&center=37.4226277,-122.0841644 Map of geolocation

Example set 3: Types & Sizes

While size is required, there's no reason to always use 480x480 or for it to be a square. Want a wider, thinner map "strip" instead? Change size accordingly. What a different type of map? Use the maptype parameter. Here are some examples:

Change size dimensions to reshape map https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x128&markers=Googleplex Wider, thinner map strip around the Googleplex
terrain map type: The maptype parameter has roadmap as its default value, so use it to specify a different map type, like this example of the Googleplex in a terrain map: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex&maptype=terrain Terrain map around the Googleplex
satellite map type: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex&maptype=satellite Satellite map around the Googleplex
hybrid map type: The hybrid map type combines roadmap and satellite: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex&maptype=hybrid Hybrid map around the Googleplex

Example set 4: Zoom level

Desire a different zoom level? Change it with the zoom parameter... increasing it increases the magnification and vice versa:

Zooming in: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&zoom=18&markers=Googleplex Zooming in on the Googleplex
Zooming out: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&zoom=14&markers=Googleplex Zooming out from the Googleplex

Example set 5: Combos & Colors

Markers have some flexibility. You can place more than one marker and/or change their colors.

Additional markers: In the zoom-out map above, you see another landmark nearby, "Google Visitor Experience." Want to put a marker on that landmark as well? Provide an additional markers parameter or better yet, have a single parameter with locations separated by a pipe (|) symbol: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex|Google+Visitor+Experience Multiple markers on a map
Change marker colors: Want to change the default color? Provide markers with a secondary parameter, color:COLOR, also separated with a pipe, before the locations. Here's an example featuring blue markers: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=color:blue|Googleplex|Google+Visitor+Experience Changing map marker color
Different marker colors: Changing the default marker color sets all markers to that color. To have different markers with different colors, multiple markers parameters are required. Here's an example where the Googleplex gets a default red marker while the Google Visitor Experience gets a green one: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex&markers=color:green|Google+Visitor+Experience Different marker colors
Image formats: Don't like PNG, the default image format? Request other formats like GIF or JPG. Here's an example that outputs a JPG map with red & brown markers: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex&markers=color:brown|Google+Visitor+Experience&format=jpg Colored marker JPG map image

The color parameter is either a 24-bit value, e.g., color=0xFFFFCC, or one of the predefined colors: black, brown, green, purple, yellow, blue, gray, orange, red, white.

The above are just some of the ways you can use the Maps Static API. There are plenty of other customizations available. For more information on stylizing maps, see the styling guide. The complete developers' guide outlines what else the Maps Static API can do.

While it's simple to call the Maps Static API as a URL, more than likely, you'll have an application generate the required parameters to render the desired map in your web application, and we'll address that in the next post. Want to try the examples above? Let's get you an API key!

Google developer project setup

These are the steps necessary before creating an API key:

Designate a developer project -- either create a new project or reuse an existing one
Enable billing -- Google Maps Platform usage isn't free, so you need an active billing account (more on this below)
Enable Maps Static API -- all Google APIs must be enabled before they can be used. If you already enabled billing by the time you get here, the API will be enabled quickly. Otherwise, you will be prompted to enable billing when you enable the Maps Static API.

❗ Billing account required
While many Google APIs are free to use, Maps APIs are not. However, all users are granted a free monthly quota of $200USD of usage before incurring billing. Review the Maps Platform billing page to understand all the terms and conditions, then create a billing account backed by a credit card or other financial instrument as described. Once you have a billing account, assign it to your project.

Let's walk through the steps above one-at-a-time:

Create a new project from the Cloud/developer console or with the gcloud projects create . . . command; alternatively, reuse an existing project.
Enable billing from the Cloud/developer console. Refer to the Cloud billing documentation to learn more. After creating the billing account, link it to your project.
Enable Maps Static API. With a project and linked billing account, it's time to enable the Maps Static API. Choose your preferred method from these three common ways to enable Google APIs:
- DevConsole manually -- Enable API manually from DevConsole with these steps:
  1. Go to DevConsole
  2. Click on Library tab in the left-nav; search for "Maps Static"
  3. Click on Maps Static API then click the blue Enable button (see image below)
- DevConsole link -- You may be new to Google APIs or don't have experience enabling APIs manually in the DevConsole. If this is you...
  1. Go directly to API listing page to read more about it and click Enable from there (same image below)
  2. Alternatively, skip the API info and click this link for an enable-only button.
- Command-line (gcloud) -- Those who prefer working in a terminal can enable APIs with a single command in the Cloud Shell or locally on your computer if you installed the Cloud SDK which includes the gcloud command-line tool (CLI) and initialized its use.
  1. If this is you, issue this command to enable the API: gcloud services enable static-maps-backend.googleapis.com
  2. Confirm all the APIs you've enabled with this command: gcloud services list

Maps Static API listing page

Create API key

With the prerequisites complete, it's time to create the API key to use with your Maps Static API requests. Follow these steps:

Go to the DevConsole credentials page
Click + Create Credentials up top
Select API key and wait a few seconds for completion
Copy and save API key somewhere safe you can refer to

⚠️ WARNING: Keep API keys secure
Storing API keys in files (or hard-coding them for use in actual code or even assigning to environment variables) is for prototyping and learning purposes only. When going to production, put them in environment variables or in a secrets manager. Files like settings.py or .env containing API keys are susceptible. Under no circumstances should you upload files like those to any public or private repo, have sensitive data like that in TerraForm config files, add such files to Docker layers, etc., as once your API key leaks, everyone in the world can use it.

If you're new to Google developer tools, API keys are one of the credentials types supported by Google APIs, and they're the only type supported by Maps APIs. Other credentials types include OAuth client IDs, mostly used by GWS APIs, and service accounts, mostly used by Google Cloud (GCP) APIs. The Maps team put together a great guide on API key best practices, so check it out!

Summary and next steps

Now armed with an API key, give it a shot, and take a look at a map of the Googleplex by substituting in your API key into the YOUR_API_KEY placeholder: https://maps.googleapis.com/maps/api/staticmap?key=YOUR_API_KEY&size=480x480&markers=Googleplex as well as the other sample API calls from earlier. In the next post, we'll look at Python and Node.js code using the API so look for that!

Google provides a variety of APIs for developers across most of its product lines. But of all its 480+ APIs, I think the Maps Static API is the easiest to use: no client library, no API client objects, no API function/method calls, and no code required either! A URL with parameters and an API key is all that's needed. What do you think? If you can think of an easier Google API to use, let me know in a comment below!

NEXT POST: Explore the world with Google Maps APIs

References

Here is a summary table of the Maps Static API parameters:

Maps Static API parameters

Parameter	Description
`key`	(required) Your API key (string); ex: `UfwmmjcXOgfV9TviafMPUjYXVP-iQAWbqRmZ7WE` (not a real one)
`size`	(required) Image dimensions (string); ex: `480x480`
`markers`	(required without `center` and `zoom`) Location by which to center the map image highlighted with a marker (string); exs:`Googleplex`, `1600 Amphitheatre 94043`, "`37.4226277,-122.0841644`", etc.
`center`	(required without `markers`) Location by which to center the map image with (string); exs: (same as `markers` above)
`zoom`	(required without `markers`) Magnification of generated map (integer from 1-20, inclusive); ex: `16`
`maptype`	Type of map to return; ex: `terrain`

Google Maps Static API parameters

Links relevant to the contents of this post:

Maps Static API

Google Maps APIs

Google Maps Platform

Hosting apps in the cloud today with Google App Engine

Wesley Chun (@wescpy) — Tue, 22 Oct 2024 08:12:56 +0000

TL;DR:

If you're looking to put code online today, you have many options, with a VM or Kubernetes as the best choice for some. Others with less code may consider (AWS) Lambda. There are also options where developers don't have to consider traditional servers... these are known as serverless (compute) platforms. Google Cloud (GCP) offers several serverless options, and while Google (and I) will encourage developers to go straight to Cloud Run, it would be remiss not to start the conversation with their "OG" serverless platform, App Engine, as it still does a few things that Cloud Run can't or won't do. Cloud Run will be covered in future posts.

[IMAGE] Serverless computing with Google

Introduction

Welcome to the blog focused on using Google APIs, developer tools, and platforms, primarily from Python, but also sometimes Node.js. Here, you'll see me cover everything from to AI/ML on Google Cloud/GCP to Google Maps to YouTube to Gemini, and also nut-n-bolts like API key, and OAuth client ID credentials, especially for Workspace/GWS APIs. The aim is to provide something for everyone.

The purpose of this post is to directly address the question, "Where can I host my app in the cloud?" More specifically, "How can I do so with the least amount of setup and friction?" The answers to both will almost always point to serverless, a subset of cloud computing focused on logic-hosting.

Serverless computing and logic-hosting

"Logic" means any code, whether a short code snippet to a web app to a container running a service. So "logic-hosting" is an all-encompassing term that includes app-hosting (hosting your apps in the cloud), function-hosting (hosting your functions in the cloud; FaaS), and container-hosting (hosting your containers in the cloud; CaaS).

All of that hosting can be accomplished with serverless computing, the ability to host that logic without thinking about or being concerned with servers, virtual machines or bare-metal. It's a bit of a misnomer because of course there are servers, but they've been abstracted away from users. Developers only need to focus on building their solutions, not what they run on. Learn more in the serverless post I'm about to introduce below.

Introduction

Google offers various serverless platforms for developers, and I introduce four (4) of them in the "Broader Perspective of Serverless" post. The majority of the platforms covered are offered by GCP, and I want to dive into each. Setting aside the use cases of functions and microservices for Cloud Functions (GCF) and Cloud Run Functions (GCRF), the platforms most suitable for applications (web apps primarily) are Google App Engine (GAE) and Cloud Run (GCR).

While Google and I encourage developers to start with GCR, GAE may still be the right tool for a certain class of users who prefer a bit less sophistication and core "building blocks" for building apps. GAE still has some features not available in GCR and is a pure PaaS solution while GCR falls between the PaaS and IaaS categories of cloud computing, meaning you have to do a few more things (like bundle a web server and tell GCR how to start your app) whereas it's taken care of by GAE.

With this in mind, I feel it's a better approach to start with GAE before diving into GCR, so here we are. The intention of the rest of the post is to show Python (3) and Node.js developers how to get a "Hello World!" app up-and-running on GAE with the least amount of friction. I'll then do the same with GCR and the functions/FaaS platforms in upcoming posts.

⚠️ ALERT: Cost: billing required (but free?!?)

While many Google products are free to use, GCP products are not. In order to run the sample apps, you must enable billing and have active billing supported by a financial instrument like a credit card (payment method depends on region/currency). If you're new to GCP, review the billing and onboarding guide. Billing wasn't mandatory to use GAE in the past but became a requirement in 2019.

The good news is that GAE (and other GCP products) have an "Always Free" tier, a free daily or monthly usage before incurring charges. The GAE pricing and quotas pages have more information. Furthermore, deploying to GCP serverless platforms incur minor build and storage costs.

Cloud Build has its own free quota as does Cloud Storage (GCS). For greater transparency, Cloud Build builds your application image which is than sent to the Cloud Container Registry (CR) or Artifact Registry (AR), its successor. Storage of that image uses up some of that GCS quota as does network egress when transferring that image to the service you're deploying to. However you may live in a region that does not have a free tier, so monitor storage usage to minimize potential costs. (Check out storage use and delete old/unwanted build artifacts via the GCS browser.)

With the above said, you may qualify for credits to offset any costs of using GCP. If you are a startup, consider applying for the GCP for Startups program grants. If you are a higher education student, faculty member, researcher, or are an education technology ("edtech") company, explore all the GCP for education programs.

Getting started

Let's see how easy it is to get started with GAE. The shortest/smallest app or "MVP" (minimally-viable product) requires just three (3) files:

GAE configuration
3rd-party requirements
Main application

Both samples are available in the repo for this post. Let's walk through each code sample, run locally, then do some GCP setup and deploy to GAE; Python first.

Python

The GAE configuration file is (always) named app.yaml (repo link), and while many options are available, an MVP only requires specifying the language runtime ID. In this sample app, I set it to Python 3.12:

runtime: python312

Python's requirements.txt file (repo link) is used for specifying all 3rd-party libraries, and in this case, it's just the Flask micro web framework:

flask

Name the main application file anything you want; I settled on main.py (repo link), shown here:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def root():
    return 'Hello World!'

# local-only
if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

The Flask library is imported, then the Flask app instantiated. The only route in this app is to '/' which returns 'Hello World!' from the (default) GET request (browser, curl, etc.). You can name route functions anything you like, such as main() or index() -- I often use root(). The last few lines are only for running this app locally... drop this section entirely if only deploying to the cloud. It uses the os module to read the PORT environment variable and fires up the Flask "devserver" (development server) on port 8080 if PORT isn't set.

Now run the script to test the app locally; your (terminal) output should look something like this:

$ python3 main.py
 * Serving Flask app 'main'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:8080
 * Running on http://172.20.20.20:8080
Press CTRL+C to quit
 * Restarting with watchdog (fsevents)
 * Debugger is active!
 * Debugger PIN: 135-387-333

With a running server, point a web browser to http://localhost:8080:

[IMAGE] "Hello World!" sample app running locally (Mac)

In your terminal, you'll see log entries for each HTTP request:

127.0.0.1 - - [05/Dec/2023 15:42:55] "GET / HTTP/1.1" 200 -

To exit the devserver, issue a ^C (Control-C) on the command-line.

Node.js

Now, let's turn to the Node.js version, which looks quite similar, starting with the config file, same name: app.yaml (repo link) but specifying Node 20:

runtime: nodejs20

The Node.js 3rd-party requirements are found in the package.json file (repo link). The Python sample relies on the Flask web framework, and similarly, this Node.js app uses the Express.js framework. The package.json file looks like this:

{
  "name": "helloworld-nodejs",
  "version": "0.0.1",
  "description": "Node.js App Engine sample app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "author": "@wescpy",
  "license": "Apache-2.0",
  "dependencies": {
    "express": "^4.17.1"
  }
}

Like with Python, call your main application anything you like. Typically with Node.js, they're named app.js, main.js, or what I picked: index.js (repo link). Here are its contents:

const express = require('express');
const app = express();

app.get('/', (req, rsp) => {
  rsp.send('Hello World!');
});

const PORT = process.env.PORT || 8080;
app.listen(PORT, () =>
  console.log(`Listening on port ${PORT}`)
);
module.exports = app;

App instantiation is followed by the main (GET) handler returning "Hello World!" regardless of request content. The rest sets up the server on the designated PORT and exports the app. Unlike Python which automatically spawns a web server on GAE, Node.js requires you to run your own, hence why this code isn't enclosed in an if block like Python.

Run npm install to install all the required packages, resulting in the expected node_modules folder and package-lock.json file. Express doesn't log individually-received requests -- developers have to add middleware to see HTTP requests, so after starting the app with npm start to test the app locally, the only output you'll see until you quit the server looks like this (unlike Flask which dumps user requests to the console):

$ npm start

> helloworld-nodejs@0.0.1 start
> node index.js

Listening on port 8080

Hit this app with your web browser at http://localhost:8080 and observe similar "Hello World!" output like with the Python app. Press ^C (Control-C) to quit the Express server.

If you prefer to work with modern ECMAScript modules, quick require-to-import and module export tweaks result in the equivalent index.mjs (repo link) ESM file:

import express from 'express';
const app = express();

app.get('/', (req, rsp) => {
  rsp.send('Hello World!');
});

const PORT = process.env.PORT || 8080;
app.listen(PORT, () =>
  console.log(`Listening on port ${PORT}`)
);
export default app;

Deploying apps to App Engine

Now that you have something working locally, a more exciting next step is to run the app in the cloud and observe how it's accessible globally. Let's start with some GCP setup.

Google Cloud SDK

The gcloud command-line tool (CLI) is required to deploy apps to GAE. It comes with the Google Cloud SDK (software development kit). If you already have it installed, skip to the next section. If you're new to GCP, follow the instructions to install the SDK and learn a few gcloud commands to get comfortable using it. If you simply want to install the SDK, see these instructions instead. After installation, run gcloud init to initialize it -- you may be prompted to login.

Google Cloud project

A cloud project is required to manage all the resources, e.g., APIs, compute, and storage, used for an app. Create a new one or reuse an existing project. Then assign a billing account to that project if you haven't already.

Each project can create at most one GAE app, and it gets a free domain name: PROJECT_ID.REG.appspot.com where PROJECT_ID is the project ID (duh) while REG is an abbreviation for the assigned region.

For your convenience, set a default project with this command: gcloud config set project PROJECT_ID. If you don't set a default, you'd have to pass it in with --project PROJECT_ID each time you run a gcloud command. Otherwise you'll be prompted for the project ID.

📝 Optional Python-related installs
Python developers have a few additional, optional installations if they're of interest to you.

App Engine SDK (Python 3): If you have an existing Python 2 app using the GAE bundled services and considering a migration to Python 3, this is for you. The App Engine (services) SDK (not to be confused with the GCP SDK described above) gives Python 3 apps access to those bundled services bridging Gen1 apps to Gen2. Install it with: pip install appengine-python-standard (or pip3).

GCP App Engine "extras": There are a pair of additional, (very) optional GCP components. The app-engine-python component contains the local GAE devserver (not to be confused with the Flask or Express devservers) if you want to simulate bundled services locally. Another one is app-engine-python-extras, which has code for Python 2 apps using built-in libraries. Since 2.x apps can no longer be deployed, you wouldn't use this. Regardless, install one or both components with a command like this: gcloud components install app-engine-python-extras app-engine-python

Final setup

Once you've confirmed you've completed these basic tasks, you should be ready to deploy your app:

Install GCP SDK (includes gcloud CLI)
Create new or reuse existing GCP project
Enable billing & assign billing account
Run gcloud init
(optional) Run gcloud config set project PROJECT_ID
(optional) Any additional installs (see sidebar above)

Deploy app to App Engine

Before deploying your sample Python or Node.js sample app, a few words on regions. Here are the key points all developers should know:

Every GAE app is hosted in a GCP region.
Regardless of which region it is hosted in, your app is accessible globally.
When deploying an app the first time, you'll be prompted to set your GAE app's region.
You'll only set the region once because it's a permanent choice (see sidebar below).

❗ App Engine region cannot be modified!
Every Cloud project can only have one App Engine app, and that app can only ever belong to one region. When assigned, that decision is permanent and cannot be changed, so choose wisely. Rest assured however that regardless of where your app is hosted, it's still reachable globally. Choose a region where you expect most of your users to be. If you insist on another region, you'll have to create another GAE app with another project. One advantage of newer GCP serverless platforms like GCR is that you can have more than one and they can serve different regions.

❗ App Engine region cannot be modified!

Every Cloud project can only have one App Engine app, and that app can only ever belong to one region. When assigned, that decision is permanent and cannot be changed, so choose wisely. Rest assured however that regardless of where your app is hosted, it's still reachable globally. Choose a region where you expect most of your users to be. If you insist on another region, you'll have to create another GAE app with another project. One advantage of newer GCP serverless platforms like GCR is that you can have more than one and they can serve different regions.

Let's take a look at the deployment process... run: gcloud app deploy. If you didn't set your project ID with gcloud earlier, pass it in with --project PROJECT_ID here or enter when prompted. You'll then be prompted to select a region. Your output will resemble this:

$ gcloud app deploy
Reauthentication required.
Please enter your password:
You are creating an app for project [PROJECT_ID].
WARNING: Creating an App Engine application for a project is irreversible and the region
cannot be changed. More information about regions is at
<https://cloud.google.com/appengine/docs/locations>.

Please choose the region where you want your App Engine application located:

 [1] asia-east1    (supports standard and flexible)
 [2] asia-east2    (supports standard and flexible and search_api)
 [3] asia-northeast1 (supports standard and flexible and search_api)

. . .

 [21] us-west2      (supports standard and flexible and search_api)
 [22] us-west3      (supports standard and flexible and search_api)
 [23] us-west4      (supports standard and flexible and search_api)
 [24] cancel
Please enter your numeric choice:  19

Creating App Engine application in project [PROJECT_ID] and region [us-east4]....done.

Because your region choice is permanent, you'll never be prompted for it again. The rest of the output shown below is what you'll see next for your first and all subsequent deployments:

Services to deploy:

descriptor:                  [/private/tmp/app.yaml]
source:                      [/private/tmp]
target project:              [PROJECT_ID]
target service:              [default]
target version:              [20231205t154433]
target url:                  [https://PROJECT_ID.REG.appspot.com]
target service account:      [PROJECT_ID@appspot.gserviceaccount.com]

Do you want to continue (Y/n)?

Beginning deployment of service [default]...
╔════════════════════════════════════════════════════════════╗
╠═ Uploading 3 files to Google Cloud Storage                ═╣
╚════════════════════════════════════════════════════════════╝
File upload done.
Updating service [default]...done.
Setting traffic split for service [default]...done.
Deployed service [default] to [https://PROJECT_ID.REG.appspot.com]

You can stream logs from the command line by running:
  $ gcloud app logs tail -s default

To view your application in the web browser run:
  $ gcloud app browse

On the first deployment, all three files are new, so that is what the build system uploads. On subsequent deployments, only new and modified files are uploaded. Once deployed, visit the app at: https://PROJECT_ID.REG.appspot.com, a real online address, and you'll see the same "Hello World!" page as before:

[IMAGE] "Hello World!" sample app running globally (PC)

Now that you've successfully deployed a sample Python or Node.js app and have seen it running on Google Cloud, continue to experiment by changing the sample app and redeploying, or uploading one of your "real" apps. Regardless of next steps, you've now learned one place you can run your apps in the cloud, and nowhere in the discussion above did you consider allocating, configuring, or paying for a server.

Summary and next steps

Congratulations on taking your first step in learning about Google's original serverless platform, App Engine. In addition to web apps, GAE can also host mobile backends. A web UI is optional, and GAE only needs to receive HTTP GET and POST requests, as long as your app has the appropriate handlers for such requests. Overall, is serverless right for you? And what other platforms does GCP offer?

Where should you run your app?

Serverless is the right solution for developers who want their CSP (cloud services provider) to do most of the heavy-lifting in terms of app-hosting and deployment. It is suitable for apps where the traffic is unpredictable or infrequent (say for student projects, small business websites, mobile backends, etc.), including short-lived apps with extreme traffic, say for a royal wedding!

Apps that get steady, continuous traffic, requiring it be available 24x7, are likely best served with VM-based solutions like Google Compute Engine (GCE) or Google Kubernetes Engine (GKE) because the cost of serverless will outgrow its benefits. However, if you're just getting off the ground, serverless helps you get there first, or at least, faster. More on serverless non-use cases can be found in the other serverless post.

Newer serverless platforms > GAE

If serverless sounds right for you, GAE is one option, but GCP has two others: GCF and GCR, both newer than GAE and part of a "Serverless 2.0" generation of products. In late summer 2024, the 2nd-generation of Cloud Functions was rebranded as Cloud Run Functions (GCRF). The newer platforms extend from GAE's original app-hosting mission to include functions/microservices and containers.

When you don't have an entire app or don't want/need to worry about full-stack or (LAMP, MEAN, etc.) stacks at all, function-hosting is likely the tool for you. These scenarios cover shorter snippets of code to perform specific tasks or microservices in a multi-tiered application, or basic cloud-based mobile backend functionality.

Modern software applications are now shipped as containers. Organizing app code and resources helps isolate dependencies, coordinate versions, and serves the purpose of providing a "shopping bag" for what apps depends on. In the past, developers had to decide between the flexibility of containers versus the convenience of serverless. This "problem" is directly addressed by GCR which runs containers in a serverless way. Furthermore, those with modern AI/ML workloads will be happy to know that GCR supports GPUs serverlessly.

Overall, the newer platforms are generally more flexible and have newer features than GAE, giving you the ability to have multiple (GCF) functions or (GCR) services vs. one GAE app per project. Both GCF and GCR can be deployed to different regions too, which can be critical for some applications.

GAE > Newer serverless platforms

With all of the advantages of GCF, GCR, and GCRF, what can GAE still do better? The bundled services are a big part of the picture. Don't most apps need a database, caching server, external task execution, large blob/file storage, etc? And what if they're (mostly) free and highly-scalable? Yep, that's the promise that the original App Engine team envisioned. The newer serverless platforms require use of standalone GCP services, each of which has their own pricing, or your own best-of-breed options if you prefer or if GCP doesn't have an exact replacement.

Additionally, GAE infrastructure features an automatic static file-serving and front-end/response caching. This free pseudo-CDN (content delivery network) gives you edge-caching without having to set up your own CDN, critical to rendering assets to your users much faster than if served by your application. It's also more cost-effective than a true CDN service like Cloud CDN. These are just a few things GAE still does better, so if they're less important for your app(s), you'll likely be better served by the newer serverless platforms.

Billing epilogue

If you want to keep the sample GAE app up and working-as-intended to continue learning and experimenting, great. However, recall it's not a free service, and while you're not likely to incur any charges, the longer you run it, and the more you deploy new versions, this will eventually lead to billable usage. There are several options to minimize getting charged.

One option is to "pause" your app so as to not get billed for inadvertent usage, especially if robots, hackers, or other online scanners discover your app. To do this, disable your app. When you're ready to continue playing with GAE, re-enable it. While your app is disabled and won't incur charges, be aware other resources used in your Cloud project may accrue charges.

Let's say you deployed your app numerous times, with accrued images and other build files exceeding the free tier on GCS or the registries (CR/AR). (In my experience, the registries accrue costs faster than GCS.) These will continue to bill you even with a disabled app, so be sure to tidy both up in addition to disabling your app to avoid (bad) surprises. (Also review the earlier sidebar on costs if you haven't already!)

On the other hand, if you're not going to continue with GAE or this GCP project, delete everything forever to avoid possible billing. To do that, shutdown your project.

Conclusion

Summary

If you're a Python, Java, Go, PHP, Ruby, or Node.js developer curious about GAE and made it this far, you now know what the platform is all about and how to deploy a sample app to the cloud. While new features are primarily going into the newer serverless platforms, GAE is still fulfilling its purpose of providing a serverless app-hosting service with autoscaling properties. GAE apps using bundled services can now migrate from Gen1 to Gen2 with much less friction and upgrade to more recent language versions.

When ready to migrate off the bundled services, developers have additional options of staying on GAE (Gen2), breaking up large apps into multiple microservices for GCF or GCRF, or containerizing their apps for GCR. Furthermore, apps that don't use GAE bundled services can also be migrated to "serverful"/VM-based platforms like GCE or GKE.

Next steps

As mentioned earlier, GCP has several serverless platforms. While it's great to learn about the background and remaining use cases for GAE, developers are most likely to use GCR for today's modern apps. Therefore, the next place for you to go from here is directly to the GCR intro post, or, take a step back to gain a broader perspective of serverless... links to both:

NEXT POST: Guide to modern app-hosting without servers on Google Cloud (Run)
PREV POST: A broader perspective of serverless

Wrap-up

If you found an error in this post, bug in the code, or have a topic you want me to cover in the future, drop a note in the comments below or file an issue at the repo. If you have an older GAE app and need advice on possible next steps, whether upgrading from Python 2 to 3, migrating off the bundled services, or shifting to other serverless platforms (GCF/GCRF or GCR), I may be able to help... check out https://appenginemigrations.com and submit a request there.

Thanks for checking out my blog... I hope you find this content useful. I enjoy meeting users on the road, so check if I am visiting your community soon... see the travel calendar on my consulting page.

References

Below are various resources related to this post which you may find useful.

Blog post code samples

Google App Engine (GAE) resources

GCP compute platforms (serverless and VM-based)

Google App Engine (GAE)
Google Cloud Functions (Gen1) and Cloud Run Functions (Gen2) (GCF/GCRF)
Google Cloud Run (GCR)
Google Compute Engine (GCE)
Google Kubernetes Engine (GKE)

GCP serverless content by the author

Pick a GCP serverless platform video
How to design serverless apps video
Exploring serverless with a nebulous app: Deploy the same app to App Engine, Cloud Functions, or Cloud Run blog post, video, code repo, socials

Google App Engine (GAE) historical references

GAE 2008 original (Gen1) launch post and video
GAE 2009 Java launch post
GAE 2009 GAE general availability (GA) announcement
GAE 2012 Go(lang) launch post
GAE 2013 PHP launch post
GAE 2014 Flexible launch post
GAE 2018 Gen2 launch post
GAE 2021 bundled services on Gen2 launch post

DEV Community: Wesley Chun (@wescpy)

Simplifying basic (genAI) web app deployment with serverless

TL;DR:

Introduction

Background

Architectural components

Gemini API

Requirements(s)

Languages

Requirements(s)

Serverless platforms

Requirements(s)

The app

The code

Node.js: from original web app

Node.js: new for serverless deployments

Python: from original web app

Python: new for serverless deployments

Run locally

Node.js

Python

Deploy to the cloud

Wrap-up

References

Code samples

Gemini API (Google AI) general

Gemini models

Other Gemini API content by the author

GCP serverless platforms

Other GAE content by the author

Other GCR content by the author

Other GCP serverless content by the author

Inspiring Google Developers video retrospective

TL;DR:

Introduction and motivation

Featured videos & content

1. (BEST "ROAD SHOW") Creating events in Google Calendar

2. (BEST INTERN) Expediting expense reports with Gmail add-ons

3. (BEST "ACTING") Automating YouTube stats with Google Apps Script

4. (BEST "FIGHT [SCENE]") File Storage in the Cloud

5. (MOST "INTEROPERABLE") Deploy the same app to App Engine, Cloud Functions & Cloud Run

6. (MOST INTERESTING PORT) Migrate App Engine Users service to Cloud Identity Platform

7. (MOST VIEWED) Google Drive API: Uploading & Downloading Files

8. (MOST ASPIRATIONAL) Change the world in 10 lines of code

9. (HONORABLE MENTION) Building an AI-enhanced enterprise image processing workflow

Summary

References

Miscellaneous

GWS APIs

GCP APIs

Serverless

(Predictive) AI/ML

Storage

Other GCP

Gmail API developer intro: spotting chatty threads

Primer on using the Gmail #API... TL;DR:

Introduction and motivation

Background

Updated (permission) scopes

Scopes background

Gmail API scopes

Updated code samples (from original)

Configuration

Python requirements.txt

Python requirements-old.txt

Node package.json

Application source code

Python (current auth)

Rest of Application

Python (old auth)

Python 3-only

JavaScript/Node.js

Prerequisites/required setup

Running the script

Summary

References

Code samples

Related code samples & content

Gmail API

GWS APIs & OAuth2 information

Python `requirements.txt`

Python `requirements-old.txt`

Node `package.json`