Google Home Local API

This is an unofficial documentation of the local API used by the Home app to communicate with GH devices. GitHub Repo

Getting Started

Requests must be made over HTTPS, port 8443, so the base URL for these endpoints is: https://<google-home-ip>:8443/setup/

Get the IP of Google Home from the Google Home app (Device Settings -> End of the list) or from your router.

GET requests are simple, in the browser kind.
POST requests need to set the header (when there’s a body): content-type: application/json

Authentication

Since June 2019, most requests (with exceptions like /setup/eureka_info) need a local authorization token.

There are 3 kinds of tokens involved here:

Local Authorization Token

This token must be sent in all requests in the header cast-local-authorization-token. It is short-lived (~1 day) and may change unexpectedly (with a sync, change in homegraph, etc.)

Get this token

• With access to an android device, get this token directly by either method.
• Without a device, or to integrate it with a script, use an access token to get the homegraph and extract the token. To get an access token, read the next section. Check the example section for more info.

Access Token

This is a standard google oauth2 access token. It is in the form ya29.***. This gives access to the Google Home Foyer API. These expire in an hour. Use this to get the homegraph (and then the local authorization token above).

Get this token

To get this access token, either a Google account username/password or a Google Master Token is needed. More info in the gist. Use the script from this gist.

Master Token

This is in the form aas_et/*** and can be used to request access tokens.

Get this token

The same script in the gist that gets the access token can also get the master token. Needs Google account creds.

Example

Here’s the whole flow from just a pair of username/password to using the local API.

Prerequisites:

• grpcurl
• Proto files (preserve folder structure)

1. Get an access token with the script

• Download get_tokens.py
• Fill in username and password

python3 get_tokens.py
# Note down the access token printed.

2. Use the access token and get home graph

• This prints the json and uses jq to parse and filter out the fields deviceName and localAuthToken
• This will give a list of all devices and their local auth tokens

./grpcurl -H 'authorization: Bearer ya29.a0Af****' \
	-import-path /path/to/protos \
	-proto /path/to/protos/google/internal/home/foyer/v1.proto \
	googlehomefoyer-pa.googleapis.com:443 \
	google.internal.home.foyer.v1.StructuresService/GetHomeGraph | jq '.home.devices[] | {deviceName, localAuthToken}'
# Note down the local auth token for the device you want.

3. Make the call to the local device using the local auth token

curl -H "cast-local-authorization-token: LOCAL_AUTH_TOKEN" --verbose --insecure https://192.168.0.18:8443/setup/bluetooth/status

Use this page to mock Google Home in your testing and development.

Run our mock API sample using the open source WireMock library, or in the free edition of WireMock Cloud. You'll have a working API server simulating the behavior of Google Home, which will allow you to keep building and testing even if the actual API you isn't currently available.