# Python wrapper for Kiosker API
This Python library provides a comprehensive wrapper for the Kiosker API, enabling developers to programmatically control and manage Kiosker devices. Kiosker is a professional web kiosk application for iOS that transforms iPads into secure, full-screen web browsers perfect for public displays, interactive kiosks, and digital signage solutions.
The kiosker-python-api package allows you to:
- **Remote Control**: Navigate web pages, refresh content, and control browser functions
- **Device Management**: Monitor device status, battery levels, and system information
- **Content Control**: Manage blackout screens for maintenance or emergency messaging
- **Screen Management**: Control screensaver behavior
- **System Maintenance**: Clear cookies, cache, and perform system operations
- **Network Discovery**: Automatically discover Kiosker devices on your network using ZeroConf
Whether you're managing a single kiosk or deploying a fleet of devices across multiple locations, this library provides the tools needed to integrate Kiosker devices into your existing infrastructure and workflows.
---
### Installation
```shell
pip install kiosker-python-api
```
---
### Setup
```python
KioskerAPI(host, token, port = 8081, ssl = False, verify = False)
```
```python
from kiosker import KioskerAPI
from kiosker import Status, Result, Blackout, ScreensaverState
api = KioskerAPI('10.0.1.100', 'token')
```
#### Constructor Parameters
- **host** (str): IP address or hostname of the Kiosker device
- **token** (str): Authentication token for API access
- **port** (int, optional): Port number (default: 8081)
- **ssl** (bool, optional): Use HTTPS instead of HTTP (default: False)
- **verify** (bool | ssl.SSLContext, optional): SSL certificate verification. Set to False to disable SSL verification for self-signed certificates (default: False)
---
### Device Discovery with ZeroConf
Kiosker devices advertise themselves on the local network using ZeroConf (Bonjour/mDNS) autodiscovery. This allows you to automatically discover Kiosker devices without needing to know their IP addresses beforehand.
#### Service Information
Kiosker devices broadcast the following service:
- **Service Type**: `_kiosker._tcp`
- **TXT Records**:
- `version`: App version (e.g., "25.1.0 (230)")
- `app`: App name (e.g., "Kiosker Pro")
- `uuid`: Unique device identifier (e.g., "2904C1F2-93FB-4954-BF85-FAAEFBA814F6")
---
### Functions
#### Get Status
```python
status = api.status()
print('Status:')
print(f'Device ID: {status.device_id}')
print(f'Model: {status.model}')
print(f'OS version: {status.os_version}')
print(f'Battery level: {status.battery_level}%')
print(f'Battery state: {status.battery_state}')
print(f'Last interaction: {status.last_interaction}')
print(f'Last motion: {status.last_motion}')
print(f'App name: {status.app_name}')
print(f'App version: {status.app_version}')
print(f'Last status update: {status.last_update}')
```
**Description**: Retrieves the current status of the kiosk.
#### Ping the API
```python
result = api.ping()
print(f"Ping successful: {result}")
```
**Description**: Checks if the API is reachable. Returns `True` if successful, otherwise raises an error.
#### Navigate to a URL
```python
result = api.navigate_url('https://example.com')
print(f"Navigation result: {result}")
```
**Description**: Navigates the kiosk to the specified URL.
#### Refresh the Page
```python
result = api.navigate_refresh()
print(f"Refresh result: {result}")
```
**Description**: Refreshes the current page on the kiosk.
#### Navigate Home
```python
result = api.navigate_home()
print(f"Home navigation result: {result}")
```
**Description**: Navigates the kiosk to the home page.
#### Navigate Forward
```python
result = api.navigate_forward()
print(f"Navigate forward result: {result}")
```
**Description**: Navigates forward in the browser's history.
#### Navigate Backward
```python
result = api.navigate_backward()
print(f"Navigate backward result: {result}")
```
**Description**: Navigates backward in the browser's history.
#### Print
```python
result = api.print()
print(f"Print result: {result}")
```
**Description**: Sends a print command to the kiosk.
#### Clear Cookies
```python
result = api.clear_cookies()
print(f"Cookies cleared: {result}")
```
**Description**: Clears all cookies stored on the kiosk.
#### Clear Cache
```python
result = api.clear_cache()
print(f"Cache cleared: {result}")
```
**Description**: Clears the cache on the kiosk.
#### Interact with Screensaver
```python
result = api.screensaver_interact()
print(f"Screensaver interaction result: {result}")
```
**Description**: Simulates user interaction with the screensaver to prevent it from activating.
#### Set Screensaver State
```python
result = api.screensaver_set_disabled_state(disabled=True)
print(f"Screensaver disabled: {result}")
```
**Description**: Enables or disables the screensaver.
#### Get Screensaver State
```python
state = api.screensaver_get_state()
print(f"Screensaver state: {state}")
```
**Description**: Retrieves the current state of the screensaver (enabled or disabled).
#### Set Blackout
```python
from kiosker import Blackout
blackout = Blackout(
visible=True, # Required: show blackout screen
text="Maintenance in progress", # Optional: text to display
background="#000000", # Optional: background color (hex)
foreground="#FFFFFF", # Optional: foreground/text color (hex)
icon="warning", # Optional: icon name (SF Symbol)
expire=60, # Optional: time in seconds before blackout expires
dismissible=True, # Optional: allow user to dismiss blackout with a button
buttonBackground="#FF0000", # Optional: button background color (hex)
buttonForeground="#FFFFFF", # Optional: button text color (hex)
buttonText="OK", # Optional: button label
sound="1003" # Optional: sound to play (SystemSoundID)
)
result = api.blackout_set(blackout)
print(f"Blackout set: {result}")
```
**Description**: Sets a blackout screen with customizable text, colors, expiration time, and optional button/sound options.
#### Get Blackout State
```python
blackout_state = api.blackout_get()
print(f"Blackout state: {blackout_state}")
```
**Description**: Retrieves the current state of the blackout screen.
#### Clear Blackout
```python
result = api.blackout_clear()
print(f"Blackout cleared: {result}")
```
**Description**: Clears the blackout screen.
---
### Objects
#### `Status`
Represents the current status of the kiosk.
**Attributes**:
- `battery_level` (int): Battery percentage.
- `battery_state` (str): Current battery state (e.g., charging, discharging).
- `model` (str): Device model.
- `os_version` (str): Operating system version.
- `app_name` (str): Name of the currently running app.
- `app_version` (str): Version of the currently running app.
- `last_interaction` (datetime): Timestamp of the last user interaction.
- `last_motion` (Optional[datetime]): Timestamp of the last detected motion.
- `last_update` (datetime): Timestamp of the last status update.
- `device_id` (str): Unique identifier for the device.
#### `Result`
Represents the result of an API operation.
**Attributes**:
- `error` (bool): Indicates if an error occurred.
- `reason` (Optional[str]): Reason for the error, if any.
- `function` (Optional[str]): Name of the function that caused the error.
#### `Blackout`
Represents a blackout screen configuration.
**Attributes**:
- `visible` (bool): Whether the blackout screen is visible.
- `background` (Optional[str]): Background color in hex format.
- `foreground` (Optional[str]): Foreground/text color in hex format.
- `expire` (Optional[int]): Time in seconds before the blackout screen expires.
- `text` (Optional[str]): Text to display on the blackout screen.
- `icon` (Optional[str]): Icon to display on the blackout screen.
- `dismissible` (Optional[bool]): Allow user to dismiss blackout with a button.
- `buttonBackground` (Optional[str]): Button background color (hex).
- `buttonForeground` (Optional[str]): Button text color (hex).
- `buttonText` (Optional[str]): Button label.
- `sound` (Optional[str]): Sound to play (SystemSoundID).
#### `ScreensaverState`
Represents the state of the screensaver.
**Attributes**:
- `visible` (bool): Whether the screensaver is currently visible.
- `disabled` (bool): Whether the screensaver is disabled (cannot activate).
---
### Development
1. Clone the project
2. Create a virtual environment
```shell
python3 -m venv venv
```
3. Activate the virtual environment
```shell
source venv/bin/activate
```
4. Install dependencies
```shell
pip install wheel setuptools twine pytest httpx
```
5. Run tests
```shell
HOST="0.0.0.0" TOKEN="" pytest -s
```
6. Build the library
```shell
python -m build
```
7. Upload to test
```shell
twine upload --repository testpypi dist/*
```
8. Upload to prod
```shell
twine upload dist/*
```
---
### API Documentation
- [Docs](https://docs.kiosker.io/#/api)
- [Definition](https://swagger.kiosker.io)
---
### Get Kiosker for iOS on the App Store
- [Kiosker](https://apps.apple.com/us/app/kiosker-fullscreen-web-kiosk/id1481691530?uo=4&at=11l6hc&ct=fnd)
- [Kiosker Pro](https://apps.apple.com/us/app/kiosker-pro-web-kiosk/id1446738885?uo=4&at=11l6hc&ct=fnd)
Raw data
{
"_id": null,
"home_page": null,
"name": "kiosker-python-api",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "api, kiosk, kiosker, kiosker pro",
"author": null,
"author_email": "Martin Claesson <martin@topnorth.se>",
"download_url": "https://files.pythonhosted.org/packages/73/dc/353085ecf7b0cdde0faba774e4678843e7d25fe15aa51e4626d76239254a/kiosker_python_api-1.2.6.tar.gz",
"platform": null,
"description": "# Python wrapper for Kiosker API\n\nThis Python library provides a comprehensive wrapper for the Kiosker API, enabling developers to programmatically control and manage Kiosker devices. Kiosker is a professional web kiosk application for iOS that transforms iPads into secure, full-screen web browsers perfect for public displays, interactive kiosks, and digital signage solutions.\n\nThe kiosker-python-api package allows you to:\n- **Remote Control**: Navigate web pages, refresh content, and control browser functions\n- **Device Management**: Monitor device status, battery levels, and system information\n- **Content Control**: Manage blackout screens for maintenance or emergency messaging\n- **Screen Management**: Control screensaver behavior\n- **System Maintenance**: Clear cookies, cache, and perform system operations\n- **Network Discovery**: Automatically discover Kiosker devices on your network using ZeroConf\n\nWhether you're managing a single kiosk or deploying a fleet of devices across multiple locations, this library provides the tools needed to integrate Kiosker devices into your existing infrastructure and workflows.\n\n---\n\n### Installation\n\n```shell\npip install kiosker-python-api\n```\n\n---\n\n### Setup\n\n```python\nKioskerAPI(host, token, port = 8081, ssl = False, verify = False)\n```\n\n```python\nfrom kiosker import KioskerAPI\nfrom kiosker import Status, Result, Blackout, ScreensaverState\napi = KioskerAPI('10.0.1.100', 'token')\n```\n\n#### Constructor Parameters\n\n- **host** (str): IP address or hostname of the Kiosker device\n- **token** (str): Authentication token for API access\n- **port** (int, optional): Port number (default: 8081)\n- **ssl** (bool, optional): Use HTTPS instead of HTTP (default: False)\n- **verify** (bool | ssl.SSLContext, optional): SSL certificate verification. Set to False to disable SSL verification for self-signed certificates (default: False)\n\n---\n\n### Device Discovery with ZeroConf\n\nKiosker devices advertise themselves on the local network using ZeroConf (Bonjour/mDNS) autodiscovery. This allows you to automatically discover Kiosker devices without needing to know their IP addresses beforehand.\n\n#### Service Information\n\nKiosker devices broadcast the following service:\n- **Service Type**: `_kiosker._tcp`\n- **TXT Records**:\n - `version`: App version (e.g., \"25.1.0 (230)\")\n - `app`: App name (e.g., \"Kiosker Pro\")\n - `uuid`: Unique device identifier (e.g., \"2904C1F2-93FB-4954-BF85-FAAEFBA814F6\")\n\n---\n\n### Functions\n\n#### Get Status\n```python\nstatus = api.status()\n\nprint('Status:')\nprint(f'Device ID: {status.device_id}')\nprint(f'Model: {status.model}')\nprint(f'OS version: {status.os_version}')\nprint(f'Battery level: {status.battery_level}%')\nprint(f'Battery state: {status.battery_state}')\nprint(f'Last interaction: {status.last_interaction}')\nprint(f'Last motion: {status.last_motion}')\nprint(f'App name: {status.app_name}')\nprint(f'App version: {status.app_version}')\nprint(f'Last status update: {status.last_update}')\n```\n**Description**: Retrieves the current status of the kiosk.\n\n#### Ping the API\n```python\nresult = api.ping()\nprint(f\"Ping successful: {result}\")\n```\n**Description**: Checks if the API is reachable. Returns `True` if successful, otherwise raises an error.\n\n#### Navigate to a URL\n```python\nresult = api.navigate_url('https://example.com')\nprint(f\"Navigation result: {result}\")\n```\n**Description**: Navigates the kiosk to the specified URL.\n\n#### Refresh the Page\n```python\nresult = api.navigate_refresh()\nprint(f\"Refresh result: {result}\")\n```\n**Description**: Refreshes the current page on the kiosk.\n\n#### Navigate Home\n```python\nresult = api.navigate_home()\nprint(f\"Home navigation result: {result}\")\n```\n**Description**: Navigates the kiosk to the home page.\n\n#### Navigate Forward\n```python\nresult = api.navigate_forward()\nprint(f\"Navigate forward result: {result}\")\n```\n**Description**: Navigates forward in the browser's history.\n\n#### Navigate Backward\n```python\nresult = api.navigate_backward()\nprint(f\"Navigate backward result: {result}\")\n```\n**Description**: Navigates backward in the browser's history.\n\n#### Print\n```python\nresult = api.print()\nprint(f\"Print result: {result}\")\n```\n**Description**: Sends a print command to the kiosk.\n\n#### Clear Cookies\n```python\nresult = api.clear_cookies()\nprint(f\"Cookies cleared: {result}\")\n```\n**Description**: Clears all cookies stored on the kiosk.\n\n#### Clear Cache\n```python\nresult = api.clear_cache()\nprint(f\"Cache cleared: {result}\")\n```\n**Description**: Clears the cache on the kiosk.\n\n#### Interact with Screensaver\n```python\nresult = api.screensaver_interact()\nprint(f\"Screensaver interaction result: {result}\")\n```\n**Description**: Simulates user interaction with the screensaver to prevent it from activating.\n\n#### Set Screensaver State\n```python\nresult = api.screensaver_set_disabled_state(disabled=True)\nprint(f\"Screensaver disabled: {result}\")\n```\n**Description**: Enables or disables the screensaver.\n\n#### Get Screensaver State\n```python\nstate = api.screensaver_get_state()\nprint(f\"Screensaver state: {state}\")\n```\n**Description**: Retrieves the current state of the screensaver (enabled or disabled).\n\n#### Set Blackout\n```python\nfrom kiosker import Blackout\n\nblackout = Blackout(\n visible=True, # Required: show blackout screen\n text=\"Maintenance in progress\", # Optional: text to display\n background=\"#000000\", # Optional: background color (hex)\n foreground=\"#FFFFFF\", # Optional: foreground/text color (hex)\n icon=\"warning\", # Optional: icon name (SF Symbol)\n expire=60, # Optional: time in seconds before blackout expires\n dismissible=True, # Optional: allow user to dismiss blackout with a button\n buttonBackground=\"#FF0000\", # Optional: button background color (hex)\n buttonForeground=\"#FFFFFF\", # Optional: button text color (hex)\n buttonText=\"OK\", # Optional: button label\n sound=\"1003\" # Optional: sound to play (SystemSoundID)\n)\nresult = api.blackout_set(blackout)\nprint(f\"Blackout set: {result}\")\n```\n**Description**: Sets a blackout screen with customizable text, colors, expiration time, and optional button/sound options.\n\n#### Get Blackout State\n```python\nblackout_state = api.blackout_get()\nprint(f\"Blackout state: {blackout_state}\")\n```\n**Description**: Retrieves the current state of the blackout screen.\n\n#### Clear Blackout\n```python\nresult = api.blackout_clear()\nprint(f\"Blackout cleared: {result}\")\n```\n**Description**: Clears the blackout screen.\n\n---\n\n### Objects\n\n#### `Status`\nRepresents the current status of the kiosk.\n\n**Attributes**:\n- `battery_level` (int): Battery percentage.\n- `battery_state` (str): Current battery state (e.g., charging, discharging).\n- `model` (str): Device model.\n- `os_version` (str): Operating system version.\n- `app_name` (str): Name of the currently running app.\n- `app_version` (str): Version of the currently running app.\n- `last_interaction` (datetime): Timestamp of the last user interaction.\n- `last_motion` (Optional[datetime]): Timestamp of the last detected motion.\n- `last_update` (datetime): Timestamp of the last status update.\n- `device_id` (str): Unique identifier for the device.\n\n#### `Result`\nRepresents the result of an API operation.\n\n**Attributes**:\n- `error` (bool): Indicates if an error occurred.\n- `reason` (Optional[str]): Reason for the error, if any.\n- `function` (Optional[str]): Name of the function that caused the error.\n\n#### `Blackout`\nRepresents a blackout screen configuration.\n\n**Attributes**:\n- `visible` (bool): Whether the blackout screen is visible.\n- `background` (Optional[str]): Background color in hex format.\n- `foreground` (Optional[str]): Foreground/text color in hex format.\n- `expire` (Optional[int]): Time in seconds before the blackout screen expires.\n- `text` (Optional[str]): Text to display on the blackout screen.\n- `icon` (Optional[str]): Icon to display on the blackout screen.\n- `dismissible` (Optional[bool]): Allow user to dismiss blackout with a button.\n- `buttonBackground` (Optional[str]): Button background color (hex).\n- `buttonForeground` (Optional[str]): Button text color (hex).\n- `buttonText` (Optional[str]): Button label.\n- `sound` (Optional[str]): Sound to play (SystemSoundID).\n\n#### `ScreensaverState`\nRepresents the state of the screensaver.\n\n**Attributes**:\n- `visible` (bool): Whether the screensaver is currently visible.\n- `disabled` (bool): Whether the screensaver is disabled (cannot activate).\n\n---\n\n### Development\n1. Clone the project\n\n2. Create a virtual environment\n```shell\npython3 -m venv venv\n```\n\n3. Activate the virtual environment\n```shell\nsource venv/bin/activate\n```\n\n4. Install dependencies\n```shell\npip install wheel setuptools twine pytest httpx\n```\n\n5. Run tests\n```shell\nHOST=\"0.0.0.0\" TOKEN=\"\" pytest -s\n```\n\n6. Build the library\n```shell\npython -m build\n```\n\n7. Upload to test\n```shell\ntwine upload --repository testpypi dist/*\n```\n\n8. Upload to prod\n```shell\ntwine upload dist/*\n```\n\n---\n\n### API Documentation\n- [Docs](https://docs.kiosker.io/#/api)\n- [Definition](https://swagger.kiosker.io)\n\n---\n\n### Get Kiosker for iOS on the App Store\n- [Kiosker](https://apps.apple.com/us/app/kiosker-fullscreen-web-kiosk/id1481691530?uo=4&at=11l6hc&ct=fnd)\n- [Kiosker Pro](https://apps.apple.com/us/app/kiosker-pro-web-kiosk/id1446738885?uo=4&at=11l6hc&ct=fnd)",
"bugtrack_url": null,
"license": null,
"summary": "A python wrapper for the Kiosker API",
"version": "1.2.6",
"project_urls": {
"Documentation": "https://docs.kiosker.io",
"Homepage": "https://kiosker.io",
"Issues": "https://github.com/Top-North/kiosker-python/issues",
"Repository": "https://github.com/Top-North/kiosker-python.git"
},
"split_keywords": [
"api",
" kiosk",
" kiosker",
" kiosker pro"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d758928af41b81a6387238e946669ac2843ad0c651a55e78cc966fb2fe99f69f",
"md5": "a0f8bd3a1f99773fea794dffd7ca281b",
"sha256": "6d281077253bd4fc0e7398f688de1d0095bc1a565a42e7634521fbabecf48236"
},
"downloads": -1,
"filename": "kiosker_python_api-1.2.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0f8bd3a1f99773fea794dffd7ca281b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 7260,
"upload_time": "2025-08-31T19:44:43",
"upload_time_iso_8601": "2025-08-31T19:44:43.610969Z",
"url": "https://files.pythonhosted.org/packages/d7/58/928af41b81a6387238e946669ac2843ad0c651a55e78cc966fb2fe99f69f/kiosker_python_api-1.2.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "73dc353085ecf7b0cdde0faba774e4678843e7d25fe15aa51e4626d76239254a",
"md5": "a2c32563eba76bf773ea2dd25f72736f",
"sha256": "d1ced662d9ba77ba11e168724479aa454650f9347637987d33244a0c9154d4d5"
},
"downloads": -1,
"filename": "kiosker_python_api-1.2.6.tar.gz",
"has_sig": false,
"md5_digest": "a2c32563eba76bf773ea2dd25f72736f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9517,
"upload_time": "2025-08-31T19:44:44",
"upload_time_iso_8601": "2025-08-31T19:44:44.895182Z",
"url": "https://files.pythonhosted.org/packages/73/dc/353085ecf7b0cdde0faba774e4678843e7d25fe15aa51e4626d76239254a/kiosker_python_api-1.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 19:44:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Top-North",
"github_project": "kiosker-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kiosker-python-api"
}
JSON
