wiliot-hologram-api 0.2.0

Python client and CLI for the Hologram REST API (devices, SIMs, messaging, usage, billing).

hologram-api

A Python client and CLI over the most-used Hologram REST API endpoints. Import it in scripts and Databricks notebooks, or use the hologram command line.

• Package (import name): hologram_api
• Distribution (pip name): wiliot-hologram-api
• CLI: hologram

Install

pip install wiliot-hologram-api

In a Databricks notebook:

%pip install wiliot-hologram-api
dbutils.library.restartPython()

Use it as a library

from hologram_api import HologramClient, build_report_rows

# Pass credentials directly...
c = HologramClient(apikey="xxxxxxxx", orgid="12345")

# ...or read HOLOGRAM_API_KEY / HOLOGRAM_ORG_ID from the environment / a .env
c = HologramClient.from_env()

devices = c.request("GET", "/devices", {"orgid": c.orgid})   # single page
all_sims = list(c.paginate("/links/cellular", {"orgid": c.orgid, "limit": 1000}))

rows = build_report_rows(c)                 # full active-SIM inventory (list of dicts)

c.rename_device(123456, "Fleet truck 12")   # PUT /devices/{id}
c.rename_sim(999, "Fleet truck 12")          # resolves the link's deviceid, then renames it

A cellular link's devicename is derived from its device — there's no link-level rename. rename_sim(linkid, name) looks up the link's deviceid and renames that device, raising HologramError if the SIM isn't bound to a device yet. The report's new Device ID column gives you that id directly.

build_report_rows(client, orgid=None, active_only=True, deep=False, max_usage_pages=40, limit=None) returns rows in the order of SIM_REPORT_COLUMNS — wrap them in a DataFrame, write CSV, or display() in Databricks.

Public API

HologramClient, HologramError, HologramClient.from_env, load_dotenv, split_csv, build_report_rows, resolve_plan_names, SIM_REPORT_COLUMNS, BASE_URL.

Use it as a CLI

Credentials resolve in priority order: --apikey/--orgid flags → HOLOGRAM_API_KEY/HOLOGRAM_ORG_ID env vars → the nearest .env (searched from the current directory upward).

hologram <command> [options]
hologram --help                 # every command
hologram list_devices --help    # help for one command

Common flags (place them after the command): --apikey, --orgid, --table, --fields id,name,...

Commands by category

Category	Commands
Devices	list_devices count_devices get_device device_names device_locations update_device device_state
SIM configuration	list_sims sim_report get_sim rename_sim sim_state sim_history sim_changeplan sim_overage sim_threshold sim_smslimit activate_sim
Bulk actions	bulk_device_state bulk_device_changeplan bulk_sim_changeplan bulk_sim_overage bulk_sim_threshold bulk_sim_smslimit bulk_activate
Tags	list_tags create_tag tag_link tag_unlink delete_tag
Data usage	usage_data usage_daily usage_monthly usage_billing usage_sms
Cloud messaging	send_sms send_message send_rdm list_messages
Billing / account	whoami list_orgs get_org balance add_balance balance_history list_plans get_plan

Examples

hologram list_devices --table
hologram list_devices --tagname Fleet --all --table
hologram get_device 123456
hologram device_state 123456 pause
hologram send_sms --deviceids 123,456 --body "reboot"
hologram send_message --deviceids 123 --port 4010 --data "ping"
hologram sim_changeplan 999 --planid 73 --zone 1
hologram rename_sim 999 --name "Fleet truck 12"   # renames the device behind the SIM
hologram update_device 123456 --name "Fleet truck 12"
hologram bulk_device_state --deviceids 1,2,3 live
hologram usage_data --linkid 999 --limit 10
hologram balance
hologram sim_report                 # active SIMs -> sim_report.csv (fast, ~40s)
hologram sim_report --deep -o all.csv   # authoritative last-session (slow)
hologram sim_report --all-states        # include paused/inactive SIMs

sim_report — full SIM inventory to CSV

Joins /links/cellular, /devices, /usage/data(/billing), and /plans into one CSV with columns: name, SIM status, last closed session (UTC), Data usage (MB), Enabled profile ICCID, Profile name, Last known IMEI, SIM ID, Device ID, Data plan, Activation date (UTC).

• Default: active (LIVE) SIMs only; --all-states for everything.
• Fast mode (default): bulk usage scan (~40s for ~900 SIMs). A blank last-session means the SIM never connected or has been idle beyond the scan window.
• --deep: adds a per-SIM fallback so a blank definitively means "never connected" (slow — one API call per idle SIM; minutes for large fleets).
• Output CSVs are git-ignored (they contain account data).

sim_report_databricks.py — Databricks notebook version

Same report, rendered as an interactive display() DataFrame. It %pip install wiliot-hologram-api and calls build_report_rows, so there's no duplicated logic. Import the .py into Databricks (it's notebook source with cell markers). Credentials come from a secret scope + widget:

databricks secrets create-scope hologram
databricks secrets put-secret hologram api_key    # your Hologram API key

Set the org_id widget; toggle active_only / deep / max_usage_pages via widgets. Builds a pandas DataFrame → Spark DataFrame → display(), with an optional Delta-table write at the bottom. Runs locally too (prints a preview) for testing.

Publishing to PyPI

The project builds with hatchling using a src/ layout.

python -m pip install --upgrade build twine
python -m build                 # -> dist/hologram_api-<version>-py3-none-any.whl + .tar.gz
python -m twine upload dist/*    # needs a PyPI account + API token

Bump version in both pyproject.toml and src/hologram_api/__init__.py for each release (PyPI rejects re-uploads of an existing version). Test against TestPyPI first with twine upload --repository testpypi dist/* if you like.

Notes

• Auth: HTTP Basic — username apikey, password = your API key. Handled automatically.
• Account ID = orgid; required for activation, billing, and bulk claims. Set once via HOLOGRAM_ORG_ID.
• Rate limits (HTTP 429) are retried automatically with backoff.
• List commands support --limit; several support --all for full pagination.
• Output is pretty JSON by default; add --table (with optional --fields) for a compact view.