Photo by Yasin Hasan on Unsplash

What is the Google Home SDK?

Google Home API is the official SDK that allows developers to access information about smart devices and control them.
Previously, such functionality was only available through the Google Assistant SDK, but now there is a convenient and officially supported API for direct integration into mobile applications.

It’s worth noting that you can control devices that have already been added to Google Home (via the official app) or add new ones (Matter-based).

Let’s briefly go over what the SDK offers, how to integrate it, how to work with the core artifacts, and some known issues I encountered.
Keep in mind that each part of this SDK deserves its own dedicated article — there’s a lot to cover — so treat this as a Google Home SDK 101.

Feature overview

At the moment, the following functionality is available:

• authorization — obtaining user consent for app access to their smart home data via OAuth2;
• adding Matter devices;
• retrieving artifacts: home, rooms, devices;
• controlling individual devices;
• automation via DSL.

Each of these areas has its own set of APIs (Device & Structure APIs, Commissioning API, Automation API, etc.) that together cover the full range of integration with the Google Home ecosystem.

https://developers.googleblog.com/en/home-apis-enabling-all-developers-to-build-for-the-home/

Minimum project requirements

To start working with the Google Home API in your Android app, you need to meet several basic requirements — both technical and organizational. Here’s a list of prerequisites that must be fulfilled before integration:

• minimum Android API level: Android 8.1 (API level 27). Officially, Google recommends Android 10 (API 29) or higher, since the Home API requires modern Google Play services.

Personally, I noticed that the SDK doesn’t work on an emulator; also, it seems to depend on the Google Home App — on devices without it, authorization fails

• a Google account (obviously)
• a Google Cloud Project
• an SHA-1 signature for OAuth 2.0
• test users — the maximum number of users who can access the Home API in your app during beta is 100.

Gradle setup

Availability of Google Home APIs for Android

The Google Home APIs are currently in open beta, which means the APIs are available to developers, but they may change without notice.
They are not part of the standard Android SDK or Google Play Services libraries (com.google.android.gms.*), and they are not yet available in Maven Central or Google repositories.
Therefore, getting started requires a somewhat non-standard integration process.

How to get the SDK: manual download

The official SDK for the Google Home API is not distributed via Maven Central or Google Maven and is only available through the Google Home developer portal.
To get started, you need to:

1. Sign in to the Google Cloud Console with your Google account.
2. Download the ZIP archive containing the latest Android SDK artifacts.

Local Maven repository: how to manually connect the SDK

After downloading the SDK, you need to install it locally as a Maven repository so that Gradle can locate and link the dependencies.

Find or create the .m2/repository directory on your system. This is the standard path used for local Maven repositories.

The location depends on your operating system:

• Linux:
  /home/<User_Name>/.m2/repository
• macOS:
  /Users/<User_Name>/.m2/repository
• Windows:
  C:\Users\<User_Name>\.m2\repository

If .m2 doesn’t exist — create it manually:

• Create a .m2 folder in your home directory
• Inside .m2, create a subfolder called repository

Unpack the SDK:

• The archive will contain a folder structure starting with com.
• Copy that com folder into ~/.m2/repository/.

Expected result:

Note:

• .m2 is a hidden directory. Enable hidden file visibility in your file manager or use the command line.
• You’ll need to repeat this process manually every time the SDK is updated, until Google officially publishes it to a Maven repository.

Adding Google Home API dependencies to your Android project

Once you’ve prepared your local Maven repository with the Google Home SDK, the next step is to add the dependencies in your Android module (:app or another where you plan to use the API).

Google split the SDK into two separate libraries to make it more modular and convenient:

• play-services-home — the main library that provides API interfaces, device control, authorization, and other services.
• play-services-home-types — a helper library that includes models for device types, traits, command parameters, and more.

If needed, you can move the dependency declarations to your tomlfile.

Connecting a local Maven repository

If the SDK was manually downloaded and placed in .m2/repository, you need to add mavenLocal() in the repositories block so that Gradle can locate the libraries:

Mine settings.gradle.kts:

Google Cloud setup

Getting the SHA-1 for configuring OAuth 2.0 in Google Cloud Console

To allow your app to authorize users via Google (OAuth 2.0), you need to tell Google Cloud Console how to identify your specific application.
Google uses a combination of:

• Application ID
• SHA-1 of the signing certificate (digital signature certificate)

Without a valid SHA-1, OAuth authorization simply won’t work — you’ll get errors like
“The OAuth client was not found” or “Error 403: access_denied”.

How to get SHA-1 in Android Studio

Open the Terminal at the root of your Android project.

Run the command:

You’ll see output similar to this:

Copy the SHA-1 value (not SHA-256 or MD5) and paste it in:
Google Cloud Console → OAuth consent screen → Credentials → Create OAuth 2.0 Client ID → Android type.

The SHA-1 shown above is from the debug certificate, which Android Studio automatically generates for all local builds.
This is your personal certificate — meaning the SHA-1 will differ for your colleagues running the same project on their machines.
If you want to test a release build or have a static SHA-1, you’ll need to generate your own signing keys and store them with the project (but preferably not in version control).

Artifacts

The Google Home API allows interaction with both physical devices and home metadata — such as rooms, structures, automations, and more.

• Structure is a model of a house or apartment that combines all rooms and devices belonging to the same physical space.
  A single Google account can have multiple structures — for example, a primary home, a summer house, or an office.
• Room is a logical zone within a structure. It helps group devices by function or location.
  This isn’t necessarily a physical division of space, but rather a grouping for convenience.
  A device can belong to only one room.
• Devices are physical or virtual objects integrated into the Google Home ecosystem. They may support different features and commands.
  Each device is described using several key concepts:
  – Type (DeviceType) — classification of the device, such as DimmableLightDevice, ContactSensorDevice, etc;
  – Traits – functional capabilities of the device, such as OnOff, LevelControl, and more.
  You can find the list of supported devices here.

At the moment, the Google Home SDK does not support the full range of devices available in the Google Home App. This means that even if a user adds a device to their home and can see it in the app, it does not guarantee that you’ll be able to control it via the API.
The reason is that the SDK supports only a limited set of device types and traits (as defined in the Kotlin Sample App).

• Automations are scripts that define reactive behavior for devices based on events, time, states, and so on.

https://developers.home.google.com/apis/android/overview

Examples

Initialization

To start interacting with the API, you need to correctly initialize the Home instance. Below are the key steps and rules:

Only one Home instance may exist at a time. Do not create multiple instances — doing so will lead to lifecycle issues and broken access to the API.

1. Create a FactoryRegistry – this is a registry of all traits and device types your app plans to support.
2. Create a HomeConfig – use Dispatchers.IO as the coroutine context.
3. Create the Home instance – this is your main entry point to all API capabilities.

Authorization

To integrate authorization via the Google Home API, you’ll need the Project Number from the Google Cloud Console.
Important: Do not confuse it with the Project ID or project name — the Project Number is a numeric unique identifier used for authorization and API requests.

How to get the Project Number:

• Go to Google Cloud.
• Select your active project (or create a new one)
• In the top menu or on the project dashboard, look for:
  Project number: 123456789012

In the context of the Google Home API, the Project Number is used as the client_id when requesting permissions, registering the SDK, and initializing the HomeClient.

Best practices:

• Do not hardcode this value in your source code
• Store it securely in local.properties, .env, or secret.properties — and exclude those files from version control (VCS)

Next, add the buildConfigField to your build.gradle.kts:

Final step — register the permission callback:

This mechanism ensures your app has the user’s explicit permission to access their home data.

Structure list

To retrieve structures (homes), call structures() — this returns a HomeObjectsFlow.

HomeObjectsFlow is a specialized subclass of Kotlin’s Flow with some built-in helper methods and properties:

• flow – the original Flow<T>.
• list – returns the latest known complete set of objects as Set<T>.
• itemFlow(id) – returns a flow that emits updates for a specific object by ID.
• itemFlow(T) – same as above, but takes the object instance instead of its ID.
• get(id) – returns a single object with the specified ID from the current set (no streaming).
• stream() – returns a stream of change events (added, removed, updated) for objects of type T.

How to get the list:

Sample output (toString(), UUIDs are fake):

Note:

• id is a value class that wraps a single String field named id.
• Rooms are linked to a structure via the structureId field.

Device list

To retrieve the list of devices:

Example output:

Device control

First, retrieve the device entity by its ID — there are many ways to do this.
In this example, the device is an LED lamp:

Read its current state:

Turn on the light:

Device control reference

Known issue

Although the Google Home API opens up new possibilities for controlling devices without relying on Google Assistant, integration into a real-world product is still far from “intuitive.”

At the moment, the Google Home SDK does not support the full range of devices available in the Google Home App. This means that even if a user adds a device to their home and can see it in the app, it does not guarantee that you’ll be able to control it via the API.
The reason is that the SDK supports only a limited set of device types and traits (as defined in the Kotlin Sample App).

If you’re expecting to just call something like turnOn(deviceId) — forget it. In the Google Home API, every action on a device (e.g., turning on/off, setting levels) requires a multi-step validation process:

• retrieve the list of devices and the specific device
• check the DeviceType
• verify the supported Traits
• only then — send the command

This process is highly flexible, but not suitable for quick and simple use cases.

Another issue is the unclear status of cloud-connected devices (e.g., brands like Tuya, TP-Link, Govee, Meross, etc.).
Even if such a device appears in the Google Home app, it may still be inaccessible via the API.

Conclusions

By opening up the Home API, Google has taken a significant step toward the smart home developer community. Third-party apps can now interact directly with the Google Home ecosystem: retrieving device lists, controlling them, adding new gadgets, creating automations, and much more. All of this comes with a high level of security and privacy ensured by Google’s infrastructure.

Of course, the current SDK isn’t quite plug-and-play — it requires a fair amount of setup, manual library integration, and compliance with specific requirements (OAuth, test accounts). Executing each command demands careful checking of device types and capabilities. Moreover, not all devices listed in the Google Home App are currently accessible through the SDK. Hopefully, over time, higher-level abstractions or wrapper libraries will emerge to simplify these aspects.

Despite the initial friction, the potential of the Google Home API is enormous. Developers gain access to a unified toolset for working with devices from various manufacturers and protocols, without worrying about low-level details (Google hides the complexity of Matter, Thread, OAuth, etc., behind a clean SDK interface).

Google Home is becoming a platform not only for hardware vendors but also for software developers — unlocking new opportunities for all of us.

Personally, I plan to continue exploring the Google Home APIs — from device control and automation to building a pet project or a KMP-based wrapper library.
So, let’s stay in touch!

LinkedIn

GitHub

References

• Home APIs: enabling all developers to build for the home (Android Developers Blog, May 2024)
• Build the future of home with Google Home APIs (Developers Blog)
• Home APIs on Android Developers Blog
• Google Home API Overview (official docs)
• Google Home API: Get Started (official guide)

This article was previously published on proandroiddev.com.