pybirdbuddy

pybirdbuddy is an asynchronous Python client for the undocumented GraphQL API behind the Bird Buddy smart bird feeder. Sign in with a Bird Buddy account to read your feeders and their state, browse your collections and media, and finish the "postcard" sightings the feeder captures.

It is an unofficial client for an undocumented API that can change without notice, and is not affiliated with or endorsed by Bird Buddy.

Installation

pip install pybirdbuddy

Python 3.10–3.14 is supported.

Usage

import asyncio
import pprint

from birdbuddy.client import BirdBuddy

bb = BirdBuddy("user@email.com", "Pa$$w0rd")

# Using coroutines with async/await:
async def async_test():
    await bb.refresh()
    pprint.pprint(bb.feeders)

# Without async/await, including from a top-level module:
result = asyncio.run(bb.refresh())
pprint.pprint(result)
pprint.pprint(bb.feeders)

Note: only password login is supported currently. Google and other SSOs are not supported. If you've already set up your Bird Buddy with SSO, one option could be to register a new account with a password, and then redeem an invite code to your Bird Buddy under the new account. Some fields will be missing (such as firmware versions and off-grid status).

The feeders property will be an array of feeders with the following fields:

fragment ListFeederFields on FeederForPrivate {
  battery {
    charging    # Boolean
    percentage  # Int (93)
    state       # String (enum: "HIGH")
  }
  food {
    state       # String (enum: "LOW")
  }
  id            # String (UUID)
  name          # String
  signal {
    state       # String (enum: "HIGH")
    value       # Int (rssi: -41)
  }
  state         # String (enum: "READY_TO_STREAM")
  temperature {
    value       # Int
  }
}

Translations

API responses can return translated strings by setting the client's language_code property. Language codes are parsed using langcodes.

from birdbuddy.client import BirdBuddy

async def main():
    bb = BirdBuddy("user@email.com", "Pa$$w0rd")
    bb.language_code = "de"

    collections = await bb.refresh_collections()
    birds = [c.species.name for c in collections.values()]
    print(birds)

Development

Install pyenv and the pinned interpreter, then use the Makefile — every target runs inside the project venv automatically:

pyenv install 3.10.20   # matches .python-version
make deps               # create the venv and install the [dev] extra

make test     # ruff + ruff format --check + markdownlint + pyright + pytest
make check    # alias for `make test`
make format   # auto-fix ruff issues and reformat
make schema   # refresh schema.json from the live API

Alternatively, install the tooling into an existing environment with pip install -e '.[dev]'.

Releasing

The package is published to PyPI. To cut a release:

1. Bump version in pyproject.toml (if needed).
2. make build — build the sdist and wheel into dist/.
3. make publish — rebuild, run twine check, then upload to PyPI.

make publish uses Twine, which reads credentials from ~/.pypirc or the TWINE_USERNAME / TWINE_PASSWORD environment variables; use __token__ as the username and a PyPI API token (the value includes its pypi- prefix) as the password.

License

Released under the MIT No Attribution license (MIT-0).