The Google Home APIs for Android provide a unified API surface to enable
developers to interact with the state of entities in a user's home. These
entities can describe devices and non-device information associated with a
user's structure and rooms.

The Home APIs define the following entities that a user can interact with:

- **Structures** represent a home that contains rooms and devices.
- **Rooms** are part of a structure and contain devices.
- **Devices** implement traits containing attributes, conform to types, emit events, and respond to commands.
- **Automations** are part of a structure and use home metadata and devices to automate tasks in the home.

Figure 1 illustrates this architecture:
![Diagram depicting the Home APIs architecture for an Android app](https://developers.home.google.com/static/apis/android/images/apis-architecture-android.svg) *Figure 1: Architecture of the Home APIs for an Android
app* **Key Point:** These concepts are similar to those already found in [Google Home Graph](https://developers.home.google.com/cloud-to-cloud/primer/home-graph), which provides contextual data about the home and its devices in the Google Home ecosystem.

Home API device types may be backed by
[Matter](https://developers.home.google.com/matter), an open standard for
the smart home, or be a Cloud-to-cloud device in the Google Home
ecosystem. Some device types may incorporate functionality from both. See
[Supported device types on Android](https://developers.home.google.com/apis/android/supported-device-types)
for more information.

In Matter, device functionality is grouped by clusters,
which are represented in the Home APIs as Matter
standard traits. The Home APIs support the standard set of
Matter clusters as defined in the current
Matter specification.

In the Google Home ecosystem, device functionality is grouped by smart home
traits, which are represented in the Home APIs as Google smart home traits.
The Home APIs support the set of smart home traits as defined in the
[Cloud-to-cloud](https://developers.home.google.com/cloud-to-cloud/traits)
program.

Other traits, such as Manufacturer-specific clusters and Platform traits, are
also available. To learn more, see
[Data model on Android](https://developers.home.google.com/apis/android/data-model).

## Ecosystem

The Google Home ecosystem provides a streamlined foundation for building,
managing, securing and integrating smart home experiences. Figure 2 shows how
the components all work together.
![Diagram depicting the Home APIs ecosystem for an Android app](https://developers.home.google.com/static/apis/android/images/apis-architecture-complete-android.svg) *Figure 2: The Home APIs ecosystem for an Android
app*

The ecosystem includes the **Google Automation Engine** which stores and
runs [automations](https://developers.home.google.com/apis/android/automation) which provide a way to
automate tasks and device settings in a home.

The Home APIs uses
[**OAuth 2.0**](https://developers.google.com/identity/protocols/oauth2)
to grant access to devices in the structure. OAuth allows a user to grant
permission to an app or service without having to expose their login
credentials.

The **Google Home Developer Console** is used to manage all stages of a Home APIs
project, from brand verification, to developing, testing, and certifying to
ultimately launching. It streamlines the development process while delivering
robust tools and distribution through the Google Home ecosystem.
| **Important:** The Google Home Developer Console is not yet available for registration.

## Language

The Home APIs for Android are written in
[Kotlin](https://kotlinlang.org/docs/android-overview.html)
and provide an idiomatic Kotlin interface that uses
[Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/) to manage state and subscription. This provides
a number of advantages over a standard subscription API.

We recommend getting familiar with the Kotlin documentation on coroutines, flow,
and Jetpack Compose, if you are not already:

<br />

- [Develop Android apps with Kotlin](https://developer.android.com/kotlin)
- [Learn Kotlin for Androids](https://developer.android.com/kotlin/campaign/learn)
- [Kotlin coroutines on Android](https://developer.android.com/kotlin/coroutines). These specific codelabs may be useful:
  - [Codelab --- Use Kotlin Coroutines in your Android
    App](https://developer.android.com/codelabs/kotlin-coroutines)
  - [Codelab --- Learn advanced coroutines with Kotlin Flow
    and LiveData](https://developer.android.com/codelabs/advanced-kotlin-coroutines)
- [Kotlin flows on
  Android](https://developer.android.com/kotlin/flow) and more specifically, [StateFlow](https://developer.android.com/kotlin/flow/stateflow-and-sharedflow).
- [State and Jetpack Compose](https://developer.android.com/jetpack/compose/state#use-other-types-of-state-in-jetpack-compose), specifically the `collectAsStateWithLifecycle()` function. This function automatically manages subscribing and unsubscribing from the flows based on whether the UI showing that state is actually in the foreground or not.
  - [Codelab --- State in Jetpack](https://developer.android.com/codelabs/jetpack-compose-state)
- If you're working with the Automation API, reading about [Kotlin type-safe builders](https://kotlinlang.org/docs/type-safe-builders.html) is useful in understanding how the Automation DSL works.

<br />

## Entity identifiers

Each entity in the Home APIs has an ID which represents its primary
identifier. This ID is a unique and stable identifier that will never change
for the lifetime of the entity. This ID can be used to cache objects or check
for equality as the metadata of an entity can change.

See the [`HasId`](https://developers.home.google.com/reference/kotlin/com/google/home/HasId) interface to learn
what entities have an ID.

## Terminology mapping

Entities in the Home APIs map to Matter and
Cloud-to-cloud concepts as follows:

| Home APIs |  Matter   |          Cloud-to-cloud          |
|-----------|-----------|----------------------------------|
| Trait     | Cluster   | Trait                            |
| Attribute | Attribute | Attribute, State                 |
| Command   | Command   | Command                          |
| Event     | Event     | Follow up response, Notification |