Google Family Link for Home Assistant

Monitor and control Google Family Link from Home Assistant: screen time, device lock, bedtime and school time schedules, daily limits, communication restrictions, app blocking, time bonuses, and optional GPS location. Multiple children and multiple devices are supported out of the box.

Disclaimer. This integration uses unofficial, reverse-engineered Google Family Link endpoints. There is no official API: Google can change or break things at any time, and using this integration may violate Google's Terms of Service and could result in account suspension. Use at your own risk. This project is not affiliated with, endorsed by, or connected to Google LLC.

The dashboard cards that ship with the integration: nothing else to install. Configuration, dialogs and the YAML of this dashboard are in examples/.

⭐ Enjoying this integration? Star it on GitHub: it gives the project visibility and helps other parents discover it.

Also supervising Windows or Xbox?

Microsoft Family Safety for Home Assistant is the companion integration for Windows, Xbox and mobile devices. With both installed, all of your child's screen time can be followed in one place, in Home Assistant. This also makes a time budget shared across devices possible, something Google and Microsoft cannot do across each other's devices. It is not built in: an automation adds up sensor.<child>_daily_screen_time and sensor.{prefix}_screen_time, then locks the devices once the budget is spent.

How it works

The project ships two components that work together. The integration (custom_components/familylink/) polls Google's Family Link endpoints (every 60 seconds by default) and exposes entities and services. The auth service (familylink-playwright/) is a separate container running Chromium via Playwright: it performs the interactive Google login (2FA included) and hands the resulting session cookies to the integration, because Home Assistant's own container cannot run a browser. On Home Assistant OS / Supervised it installs as an add-on; everywhere else it runs as a standalone Docker container. When the Google session expires, you log in again in the auth service's web UI and the integration picks up the fresh cookies automatically.

The endpoints and payload shapes the integration relies on are documented in GOOGLE_FAMILY_LINK_API_ANALYSIS.md.

Features

Area	What you can do
Device control	Lock and unlock devices, ring a device to locate it, see exactly why a device is currently blocked
Time management	Toggle bedtime, school time and daily limits, edit the weekly bedtime and school time schedules (school day breaks included) or post a today-only override, add 15/30/60 minute bonuses
Web	Read and edit the child's Chrome site lists, sync the blocked list with a published list, switch the web filter between the approved sites only and Google's filter
Screen time monitoring	Daily screen time per child, remaining time per device (bonuses included), top 10 apps, per-app usage breakdown
App management	Block or unblock apps, per-app daily limits (blocked, limited, unrestricted or "unlimited time"), one-call school mode that blocks everything except an essentials whitelist
Location (opt-in)	GPS device tracker with saved places and address, battery level of the source device, on-demand refresh
Strict mode (opt-in)	Home Assistant reverts what is changed from the Family Link side: bonuses are cancelled, a device unlocked with no time left is locked again, bedtime and the daily limit are switched back on. One switch per child, rules chosen in the options
Dashboard cards	Built in, no Marketplace card, helper or script needed: a card per phone or tablet (lock with confirmation, bonuses, restriction tiles, apps and their rules, websites, weekly limits), screen time of several devices together with hourly and daily charts (shared with Microsoft Family Safety), and a location map. See examples/
Robustness	Cached data on transient API errors, automatic session refresh, persistent notification when re-authentication is needed

Translations: English, French, Hebrew.

Quick start

The auth service must be running before you configure the integration.

1. Set up authentication.

   • Home Assistant OS / Supervised: add this repository as an add-on repository, install and start the Google Family Link Auth add-on, then complete the Google login through its web UI.

     

   • Home Assistant Core / Container (no Supervisor): run the standalone auth container instead. See DOCKER_STANDALONE.md.

2. Install the integration from the Marketplace (recommended) or manually.

   

3. Add it: Settings > Devices & Services > Add Integration > search for "Family Link". Auto-detect finds the add-on by itself; standalone users choose manual URL configuration and enter the container's URL.

The full walkthrough (prerequisites, both auth routes, configuration options, re-authentication) is in INSTALL.md.

Entities

Each child appears as a hub device named <child> (Family Link), with every physical device attached to it. <child> and <device> below stand for the slugified child and device names. Recent Home Assistant versions build the id of a newly created entity from its device's area as well, so a phone placed in an area named "Kids" gets sensor.kids_<device>_… ids; the display names are unchanged.

Entity	Scope	Shows / does
sensor.<child>_daily_screen_time	Child	Today's screen time in minutes, all devices together; per-app breakdown and a by_device split in attributes
sensor.<child>_screen_time_formatted	Child	The same value as HH:MM:SS text
sensor.<child>_installed_apps, _blocked_apps, _apps_with_time_limits, _apps_without_limits, _always_allowed_apps	Child	App counts, with the matching app lists in attributes
sensor.<child>_top_app_1 to _top_app_10	Child	Today's most-used apps, usage in minutes
sensor.<child>_device_count	Child	Number of supervised devices
sensor.<child>_child_info	Child	Profile: name, email, birthday, age band
sensor.<child>_battery_level	Child (GPS opt-in)	Battery of the device providing the location (see sensor.<device>_battery_level for each device)
device_tracker.<child>_family_link	Child (GPS opt-in)	GPS location: zone, saved place, address, battery
switch.<child>_bedtime, _school_time, _daily_limit	Child	Toggle restrictions. State reflects today's effective setting (weekly rule merged with same-day overrides); the school time switch also exposes school_time_enabled_weekly and school_time_scheduled_today attributes
switch.<child>_unlimited_apps_during_downtime	Child	Family Link's "Allow apps with unlimited time during downtime": ON keeps the apps set to unlimited time usable during downtime, OFF blocks them too. Applies to all of the child's devices. Unknown until the setting is first changed, in the app or here: Google reports nothing for a child where it was never touched
sensor.<child>_blocked_sites, _approved_sites	Child	Chrome site lists (Family Link "Google Chrome and Web"): count, the sites and the Chrome filter level in attributes; read every 15 minutes and right after a change made from Home Assistant
sensor.<child>_play_purchase_approvals, _play_apps_games_rating	Child	Google Play settings (Family Link "Controls" > "Google Play"), read-only: which purchases and downloads need a parent's approval (all_content, paid_content, in_app_purchases, never) and the highest apps & games rating allowed, as Google labels it for the account's region (e.g. PEGI 16); Google's own value and the list of choices in attributes; read every 15 minutes, two Google calls per child
select.<child>_play_purchase_approvals, _play_apps_games_rating	Child	The same two Google Play settings, to change from Home Assistant: the approval mode, and the apps & games rating among the ones Google offers the child. A change is kept only once Google's answer confirms it
select.<child>_allowed_calls_texts	Child	Choose who can call and text the child: anyone, only contacts you add, or contacts you add and limited groups
select.<child>_web_filter	Child	Chrome web filter mode: only the approved sites, or every site with Google's explicit-content filter
switch.<child>_strict_mode	Child	Strict mode on or off for this child (see below). Attributes: rules in force, last corrective action, count
number.<child>_<weekday>_limit	Child	Screen time quota of that weekday in minutes, as the weekly limits screen of the app shows it (the weekly value, or today's override when Google applies one; see the source and applied_override attributes). Setting it writes the weekly quota of that weekday, as the weekly limits screen of the app does; today's entity also posts today's override on every device so the change applies at once
time.<child>_<weekday>_bedtime_start, _bedtime_end	Child	Start and end of that weekday's bedtime in the weekly schedule. Setting one rewrites the slot (the other bound is kept)
time.<child>_<weekday>_school_time_start, _school_time_end	Child	Start and end of that weekday's school time in the weekly schedule. Setting one rewrites the slot (the other bound is kept). Unavailable for a weekday that has no school time window in Family Link
sensor.<device>_screen_time_remaining	Device	Remaining minutes today, accounting for bonuses and used time
sensor.<device>_next_restriction	Device	Next restriction at a fixed time ("Bedtime at 22:00", "School time (ends at 16:30)"); restriction_type, minutes_until (countdown, not recorded) and window timestamps in attributes
sensor.<device>_daily_limit	Device	Configured daily quota in minutes
sensor.<device>_active_bonus	Device	Active bonus minutes (0 when none)
sensor.<device>_daily_screen_time	Device	Today's screen time on this device in minutes, per-app breakdown in attributes; unknown while the data is missing
sensor.<device>_battery_level	Device	Battery of this device in percent, no GPS needed; unavailable while Google reports no level
binary_sensor.<device>_bedtime_active, _school_time_active	Device	Currently inside the bedtime / school time window
binary_sensor.<device>_daily_limit_reached	Device	Daily limit used up (ignores bonus time)
switch.<device>	Device	Device usability: ON means usable, OFF means manually locked, bedtime active, or daily limit reached. An active bonus overrides bedtime, school time and daily-limit restrictions, but not a manual lock. The restriction_reason attribute tells you why, and lock_override_code gives Google's raw override on the device (1 lock, 7 lock with the allowed apps reachable, 4 unlock, empty when none). A lock from Home Assistant keeps the apps marked "always allowed" in Family Link reachable through an "Available apps" button on the lock screen; the Device lock keeps the always allowed apps reachable option, on by default, switches that off for a plain lock
button.<device>_15min, _30min, _60min, _reset_bonus	Device	Add or cancel a time bonus
button.<device>_ring	Device	Ring the device to locate it

GPS entities are only created when location tracking is enabled in the integration options (off by default; each location poll may notify the child's device).

Strict mode

Why it exists. There is a gap on Google's side that many children know how to use: from the Family Link app or the Google interface, a supervised child can give themselves a time bonus, lift the lock of a device that has no time left, or switch bedtime and the daily limit off. Parents were closing it with a set of automations that watched the entities and reverted the change. Strict mode does this natively.

What it does. With strict mode on, Home Assistant becomes the single point of control. After every refresh the integration compares what Google reports with what Home Assistant wants and reverts the difference, overriding the Family Link settings:

Warning. While strict mode is on, manage Family Link from Home Assistant only. Changes made in the Family Link app or on the Google interface are undone at the next refresh, whoever made them. Turn the child's Strict Mode switch off to hand control back to Google. With the option off (the default), nothing changes: the integration behaves exactly as before, the switch is just there, off.

The child's Home Assistant account. Strict mode closes the Google side, not the Home Assistant side. A child who has a Home Assistant user can find these entities and give themselves a bonus or switch a restriction off. The familylink.* actions refuse a non-admin user unless the call targets an entity that user may control (see Who may call a service), so give the child a non-admin user and tick the parents in the integration option Users allowed to control Family Link: the child is then refused on every Family Link button, switch, limit, time and select, and on the actions (details in Who may call a service).

Rule	What is reverted
Time bonuses: those added from Family Link are cancelled	Any active bonus on a device is cancelled (bonuses given from Home Assistant are kept)
Device lock: locking and unlocking reserved to Home Assistant	A device you locked from Home Assistant and unlocked on the Google side is locked again, and the reverse. Without a Home Assistant decision, an unlock done on the Google side that bypasses an active bedtime, school time or reached daily limit is locked again, and strict mode lifts that lock itself when the restriction ends, as Google's schedule would have done. A bonus given from Home Assistant suspends the relock for its duration, then the lock is put back
Bedtime: switching on and off reserved to Home Assistant	Bedtime switched off on the Google side is switched back on. Switched on there, it is left on: that is more protection, not a bypass
Daily limit: switching on and off reserved to Home Assistant	Same for the daily limit
School time: switching on and off reserved to Home Assistant	Same for school time. Nothing is switched off by strict mode: if you keep Google's school time off and drive school hours from Home Assistant, a school time switched on in the app stays on until you switch it off from Home Assistant
Bedtime hours and weekly quotas: values reserved to Home Assistant	The weekly bedtime hours (seven days) and the daily quota are put back to the values chosen in Home Assistant (set_bedtime, set_daily_limit, the number and time entities). Hours are rewritten in the weekly schedule. For the quota, the reference is the weekly value of each weekday when strict mode starts (or what Home Assistant set since): a weekday changed in the app's weekly screen is written back, and the minutes applied today are put back with today's override

Enable it with the Strict mode option of the integration (default for every child, rules to apply) and toggle it per child with switch.<child>_strict_mode. The option and the switches mirror each other: changing the option applies to every child at once (no reload), and toggling a switch writes the option back once every child agrees. Nothing is switched on by force. When strict mode starts (and again at the first refresh of each day), the state in force becomes the reference; only Home Assistant can change it afterwards. What you change from Home Assistant is the parent's decision and stays in force for the day: a bonus given with the buttons or the add_time_bonus action is kept for its duration, a device you unlock is not locked again, bedtime, the daily limit or school time you switch off are not switched back on. The bedtime, daily limit and school time references are the parent's standing choice and are kept until Home Assistant changes them or strict mode is switched on again; a lock or unlock done from Home Assistant is a decision for the day and expires at midnight. All of it is remembered across restarts. Turning the Strict Mode switch off hands control back to Google. The decisions in force are visible in the ha_decisions_today and ha_device_decisions_today attributes of the switch. Each corrective action is logged, kept in the switch attributes and fired as a familylink_strict_mode_action event (child_id, child_name, device_id, device_name, action, reason, success, plus day, minutes, start, end and observed when the action carries them, so a notification can be worded in your language, and created_by, the family member or account that created the bonus or unlock override countered) for your own notifications. A given action is not repeated within 90 seconds, and a correction still needed after 3 tries is given up until the state changes or the next day, so a change Google refuses does not turn into a request storm.

Services

Service	Purpose
familylink.block_app / familylink.unblock_app	Block or unblock a single app by package name
familylink.set_app_daily_limit	Per-app daily limit: minutes, blocked, limit off, or unlimited time
familylink.pause_app / familylink.resume_app	Pause apps with a 1-minute daily limit instead of blocking them (a paused Google Messages keeps the texts that arrive), then put each app's earlier setting back
familylink.block_device_for_school	Block every app except an essentials whitelist (dialer, messages, settings, maps, ...) plus your own additions
familylink.unblock_all_apps	Unblock every hidden app
familylink.add_time_bonus	Add 1 to 1440 bonus minutes to a device
familylink.set_daily_limit	Set today's quota on a device, or a weekday's weekly quota with day (0 disables the device for the day)
familylink.enable_daily_limit / familylink.disable_daily_limit	Toggle the daily screen time limit
familylink.enable_bedtime / familylink.disable_bedtime	Toggle bedtime, effective tonight (weekly toggle plus a same-day override)
familylink.set_bedtime	Edit the recurring weekly bedtime for a day, or post a today-only override (scope: today)
familylink.set_downtime_unlimited_apps	Allow or block the apps with unlimited time during downtime (allow: true / false), like the child's switch
familylink.set_school_time	Edit the recurring weekly school time (start and finish) for a day, set, add or remove the break of a day (windows, one or two), switch a day off or on (enabled), or post a today-only window (scope: today)
familylink.enable_school_time / familylink.disable_school_time	Toggle school time
familylink.get_sites, familylink.block_site, familylink.allow_site, familylink.remove_site	Read and edit the child's Chrome site lists (approved and blocked sites, wildcards allowed)
familylink.sync_site_list	Keep the blocked sites in step with a published list of domains (https, administrators only); removes only what the list added, stop: true takes it all back
familylink.set_filter_level	Switch the Chrome web filter between the approved sites only and every site with Google's filter (approved_only / filtered); also select.<child>_web_filter
familylink.refresh_location	Force a fresh GPS fix (uses more battery than the regular polling)
familylink.ring_device	Make a device ring so it can be found
familylink.set_update_interval	Change the polling interval until the next restart (e.g. slower at night)

Targeting: every service accepts an optional entity_id or explicit child_id / device_id. Without a target, refresh_location applies to all supervised children; the app services (block_app, unblock_app, set_app_daily_limit, block_device_for_school, unblock_all_apps) fail unless all_children: true is passed. Full field reference, defaults and examples: SERVICES.md.

Troubleshooting

Setup and authentication problems (no entities, 403 on the cookie endpoint, session expired) are covered in INSTALL.md; add-on specifics (web UI, VNC) in familylink-playwright/DOCS.md, including its Security section: the browser view shows a live Google session, unmap port 6080 and stop the add-on when you are not authenticating.

Changelog

All notable changes are tracked in CHANGELOG.md and published on GitHub Releases.

Contributing

Contributions are welcome: fork the repository, create a feature branch, make your changes with clear commit messages, run the Home Assistant test suite documented in tests/README.md, test user-facing changes against a disposable Home Assistant instance, and open a pull request.

This integration is free and maintained in my spare time. If it helped you or saved you time, you can buy me a beer:

Credits

• Developed by @noiwid
• Based on the original work by @tducret (Python package documenting Family Link API endpoints)
• Inspired by @Vortitron's HAFamilyLink repository
• noVNC integration inspired by @jnctech's fork
• Home Assistant community for integration examples and best practices
• Reverse engineering insights from browser DevTools analysis

Support

• Report issues
• Feature requests
• Discussions

License

This project is licensed under the MIT License. See the LICENSE file for details.

This is an unofficial integration, not affiliated with, endorsed by, or connected to Google LLC. All product names, logos, and brands are property of their respective owners.