{"id":21334449,"url":"https://github.com/ampless/adsignificamus","last_synced_at":"2026-02-03T03:37:11.587Z","repository":{"id":119095918,"uuid":"280530114","full_name":"Ampless/Adsignificamus","owner":"Ampless","description":"Unofficial documentation for the various APIs of heinekingmedia's DSB/DSBMobile and Untis substitution plans.","archived":false,"fork":false,"pushed_at":"2022-04-16T15:41:49.000Z","size":55,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-22T14:23:05.919Z","etag":null,"topics":["amplissimus","api","documentation","dsb","dsbmobile","dsbuntis","heinekingmedia","untis"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ampless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-17T21:40:42.000Z","updated_at":"2023-10-13T11:35:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"6393aa1a-2513-4e53-b478-0bdae7c440a7","html_url":"https://github.com/Ampless/Adsignificamus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ampless%2FAdsignificamus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ampless%2FAdsignificamus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ampless%2FAdsignificamus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ampless%2FAdsignificamus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ampless","download_url":"https://codeload.github.com/Ampless/Adsignificamus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243812126,"owners_count":20351833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amplissimus","api","documentation","dsb","dsbmobile","dsbuntis","heinekingmedia","untis"],"created_at":"2024-11-21T23:21:55.838Z","updated_at":"2026-02-03T03:37:11.578Z","avatar_url":"https://github.com/Ampless.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Adsignificamus\n\nThese are some docs for heinekingmedia's DSBMobile APIs. Additionally, we will\nsoon document Untis's HTML.\n\n# Licensing\n\nYou can license the files in this repository under the terms of the\n[CC BY-ND license](https://creativecommons.org/licenses/by-nd/4.0/).\n\n# 0 An overview\n\nThere are many different DSBMobile API implementations and most of them…are the\nsame. This is because of pydsb (1), which can be considered the reference\nimplementation of the Android API. But there are still four different APIs known\nto us, and two more with only one implementation each.\n\n## The APIs\n\n- [Mobile API (Section 1)](#1-the-mobile-api)\n- [Android API (Section 2)](#2-the-android-api)\n- [Web API (Section 2.1)](#21-the-web-api)\n- iOS API (Section 3, TBD)\n\n## The implementations\n\nThis is an incomplete list of DSBMobile API implementations:\n\n\u003c!--TODO: split between DSB and Untis implementations--\u003e\n\n### Mobile API\n\n| Implementation | Language | Data types | Extra features | Bundle ID | App Version | OS Version |\n| -------------------------------------------------------------------------- | ---------- | ------------------------ | -------------------------------------- | --------------------------- | ------------------ | ------------------ |\n| [dsbuntis ≥3](https://github.com/Ampless/dsbuntis) | Dart | Plans, News, Documents\\* | Sorting, Searching, DSB-based Previews | de.heinekingmedia.dsbmobile | 36 (configurable) | 30 (configurable) |\n| [dsb-api](https://github.com/CinePlays/dsb-api) | Dart | Plans, News, Documents | Probably violates Ampless Copyleft | de.heinekingmedia.dsbmobile | 36 | 30 |\n| [pydsb (1) ≥2.2](https://github.com/sn0wmanmj/pydsb) | Python | Plans, News, Documents | DSB-based Previews | de.heinekingmedia.dsbmobile | 35 | 22 |\n| [dsbmobile.js](https://github.com/Tch1b0/dsbmobile.js) | TypeScript | Plans, News, Documents | ? | ? (probably empty) | ? (probably empty) | ? (probably empty) |\n| [vertretungsplan.io](https://codeberg.org/vertretungsplan/integration-dsb) | TypeScript | Plans, News, Documents | | (empty) | (empty) | (empty) |\n| [DSBDirect](https://notabug.org/fynngodau/DSBDirect) | Java | Plans, News, Documents | | (empty) | (empty) | (empty) |\n\n\\* dsbuntis supports every other data type that might exist through a very\nlow-level API.\n\n### Android API\n\n\u003c!--TODO: check whether postings are the same as documents--\u003e\n\n| Implementation | Language | Data types | Extra features \u0026 drawbacks | Bundle ID | Device | App Version | OS Version | Language |\n| ------------------------------------------------------------------------------- | ---------- | --------------------- | --------------------------- | --------------------------------------- | -------- | ----------- | ---------- | ----------------- |\n| [dsbuntis \u003c3](https://github.com/Ampless/dsbuntis) | Dart | Plans | Sorting and Searching | de.heinekingmedia.dsbmobile | SM-G950F | 2.5.9 | 29 10.0 | de (configurable) |\n| [pydsb (1) 2.0-2.1](https://github.com/sn0wmanmj/pydsb) | Python | Plans, News, Postings | DSB-based previews | de.heinekingmedia.dsbmobile | Pixel 3 | 2.5.9 | 27 8.1.0 | de |\n| [OpenDSBMobile](https://github.com/KaiJan57/OpenDSBmobile) | Java | Plans, News, Postings | reimplementation of the app | de.heinekingmedia.dsbmobile | (empty) | 2.5.9 | (empty) | your os language |\n| [DSBMobile-API](https://github.com/Sematre/DSBmobile-API) | Java | Plans, News | User-Agent spoofing | de.heinekingmedia.dsbmobile | Nexus 4 | 2.5.9 | 27 8.1.0 | de |\n| [DSBApi](https://github.com/nerrixDE/DSBApi) | Python | Plans | | de.heinekingmedia.dsbmobile | SM-G930F | 2.5.9 | 27 8.1.0 | de |\n| [DSBAPI](https://github.com/TheNoim/DSBAPI) | JavaScript | raw json | User-Agent spoofing | de.digitales-schwarzes-brett.dsblight | iPhone | 2.5.6 | 13.2.2 | en-DE |\n| [dsb-go](https://github.com/irgendwr/dsb-go) | Go | Plans, News | User-Agent \"dsb-go\" | de.heinekingmedia.dsbmobile | Nexus 4 | 2.5.9 | 27 8.1.0 | de |\n| [Vertretungsplangak\\_Bot](https://github.com/MakerStuff/Vertretungsplangak_Bot) | Python | ? | no parsing | de.heinekingmedia.dsbmobile | SM-G935F | 2.5.9 | 28 9 | de |\n| [dsbmobile-php-api](https://github.com/irgendwr/dsbmobile-php-api) | PHP | Plans, News | faked Referer header | de.heinekingmedia.inhouse.dsbmobile.web | WebApp | 2.3 | (empty) | de |\n| [dsbmobile\\_api](https://github.com/spnda/dsbmobile_api) | Dart | ? | ? | de.heinekingmedia.dsbmobile | Nexus 4 | 2.5.9 | 27 8.1.0 | de (configurable) |\n\n### Web API\n\n| Implementation | Language | Drawbacks | Supported requests | Bundle ID | Device | Version | OS Version | Language |\n| ----------------------------------------------------------------------------------- | -------- | ---------------------------------------- | ------------------ | --------------------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------- | -------- |\n| [Vertretungsplangak\\_Bot (2)](https://github.com/MakerStuff/Vertretungsplangak_Bot) | Python | no parsing, constant Date and LastUpdate | 1 (GetData) | de.heinekingmedia.inhouse.dsbmobile.web | WebApp | 2.3 | Mozilla/5.0 (X11; Linux x86\\_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.70 Safari/537.36 | de |\n\n### iOS API\n\n| Implementation | Language | Data types | Extra features |\n| ----------------------------------------------------------------- | ---------- | --------------------- | ------------------ |\n| [pydsb (1) 1.x](https://github.com/sn0wmanmj/pydsb) | Python | Plans, News, Postings | DSB-based previews |\n| [pydsb (2)](https://github.com/ScholliYT/pydsb) | Python | Plans, News | |\n| [DSBMobileBot](https://github.com/ScholliYT/DSBMobileBot) | Python | Plans | |\n| [myplan](https://github.com/jrheiner/myplan) | Java | Plans | a custom app |\n| [DSB - Abrage](https://forum.iobroker.net/topic/19140/dsb-abrage) | JavaScript | Plans, News | |\n| [Untitled](https://pastebin.com/ds0AjK6T) | Python | Plans | |\n\n### Other\n\n| Implementation | Language | API | Data types | Drawbacks |\n| -------------------------------------------- | ------------ | ------------------------------------------------------------------------ | -------------------------------- | ---------- |\n| [DSBot](https://github.com/sargantana/DSBot) | Shell (wget) | Unknown (looks like Web at first glance, but is significantly different) | plans (not 100% sure about that) | no parsing |\n\n### Other interesting URLs\n\nThese are some resources for learning things, you might need while building DSB\nAPI implementations:\n\n- https://pastebin.com/7XZD38V5\n- https://light.dsbcontrol.de/DSBlightWebsite/(S(kvgpcwcoqorwq3xxgbx42u2b))/Homepage/IFrame.aspx\n\n# 1 The Mobile API\n\n\u003e ![NOTE]\n\u003e The Mobile API is also extensively documented on\n\u003e [the DSBDirect wiki](https://notabug.org/fynngodau/DSBDirect/wiki/mobileapi.dsbcontrol.de),\n\u003e which is unavailable and not archived as of December 2025.\n\nThis is the simplest known API of DSBMobile. It **does** require the use of\nsessions/tokens. Like the other APIs it uses HTTPS for what could be referred to\nas Layer 4 or 5 in the OSI Model. All requests are `GET` requests.\n\n## Requests\n\n### Auth\n\nAuth is sent to `https://mobileapi.dsbcontrol.de/authid` with the arguments\nappended to it.\n\n#### Arguments\n\nThe arguments are\n`?bundleid=BUNDLE\u0026appversion=VER\u0026osversion=OSVER\u0026pushid\u0026user=USERNAME\u0026password=PASSWORD`.\n\n`USERNAME` and `PASSWORD` are kinda obvious.\n\n`BUNDLE` is the bundle id, usually `de.heinekingmedia.dsbmobile`.\n\n`VER` is the DSBMobile app version.\n\n`OSVER` is the OS version, for example on Android the API Version.\n\n\u003c!--TODO: pushid--\u003e\n\n#### Response\n\nThe server then responds with a new session/token in double quotes. (or `\"\"` if\nthe credentials are invalid)\n\nThe tokens are UUIDs that are always the same for the same `USERNAME` (and\n`PASSWORD`), which means that (a) they can be cached indefinitely and (b) could\nbe generated on the client side somehow, if it was known, which exact algorithms\nare used.\n\n### Plans, News, Documents, ...\n\nAll other endpoints use a JSON-based format and very similar requests, too.\n\nPlans are gotten from\n`https://mobileapi.dsbcontrol.de/dsbtimetables?authid=TOKEN`, News from\n`https://mobileapi.dsbcontrol.de/newstab?authid=TOKEN`, and Documents from\n`https://mobileapi.dsbcontrol.de/dsbdocuments?authid=TOKEN`, where `TOKEN` is\nalways the token from Auth.\n\n#### Response\n\nFrom all of these, JSON lists are returned. They contain `Item`s, each of which\nmight represent a Plan, Document, News item, etc. `Item`s look like this:\n\n```ts\n{\n // a (supposedly random) UUID\n \"Id\": string,\n\n // `%d.%m.%Y %H:%M` (e.g. `13.12.2016 18:00`)\n // **might** have been displayed as \"Last Updated\" in old DSBMobile versions\n \"Date\": string,\n\n // as displayed in the DSBMobile app\n \"Title\": string,\n\n // payload (see below)\n \"Detail\": string,\n\n // usually empty\n \"Tags\": string,\n\n \"ConType\": number,\n\n // usually 0\n \"Prio\": number,\n\n // usually 0, might be another number (might be useful for sorting?)\n \"Index\": number,\n\n // payload (see below)\n \"Childs\": object[],\n\n // the path of the preview PNG hosted on the preview endpoint (usually\n // \u003chttps://light.dsbcontrol.de/DSBlightWebsite/Data/\u003e)\n \"Preview\": string,\n}\n```\n\n\u003c!--TODO: check--\u003e\n\n`ConType` determines, how and where data is encoded:\n\n| `ConType` | Where? | What? |\n| --------- | -------- | ------------------------------------- |\n| `2` | `Childs` | child `Item`s, like pages of the plan |\n| `4` | `Detail` | link to an HTML web page |\n| `5` | `Detail` | string of text |\n| `6` | `Detail` | link to a PNG/GIF image |\n\nIf it doesn't contain data, `Childs` is an empty list (`[]`), `Detail` an empty\nstring (`\"\"`).\n\n##### Example\n\nThe list of timetables might look something like this\n(`accemus -T 187801 public`):\n\n```json\n[\n {\n \"Id\": \"67b3035c-51ff-4106-a2ec-b50f8680e0c4\",\n \"Date\": \"31.03.2020 17:33\",\n \"Title\": \"Vertretungen-heute\",\n \"Detail\": \"\",\n \"Tags\": \"\",\n \"ConType\": 2,\n \"Prio\": 0,\n \"Index\": 0,\n \"Childs\": [\n {\n \"Id\": \"67b3035c-51ff-4106-a2ec-b50f8680e0c4_76\",\n \"Date\": \"31.03.2020 17:33\",\n \"Title\": \"Vertretungen-heute\",\n \"Detail\": \"https://light.dsbcontrol.de/DSBlightWebsite/Data/13ccccbb-e6a8-466a-addc-00bba830c6cf/67b3035c-51ff-4106-a2ec-b50f8680e0c4/Vertretungen-heute.htm\",\n \"Tags\": \"\",\n \"ConType\": 6,\n \"Prio\": 0,\n \"Index\": 76,\n \"Childs\": [],\n \"Preview\": \"13ccccbb-e6a8-466a-addc-00bba830c6cf/67b3035c-51ff-4106-a2ec-b50f8680e0c4/preview.png\"\n }\n ],\n \"Preview\": \"\"\n },\n {\n \"Id\": \"4f301632-7422-4186-96a2-2b7911f54bc5\",\n \"Date\": \"31.03.2020 17:34\",\n \"Title\": \"Vertretungen-Woche\",\n \"Detail\": \"\",\n \"Tags\": \"\",\n \"ConType\": 2,\n \"Prio\": 0,\n \"Index\": 0,\n \"Childs\": [\n {\n \"Id\": \"4f301632-7422-4186-96a2-2b7911f54bc5_76\",\n \"Date\": \"31.03.2020 17:34\",\n \"Title\": \"Vertretungen-Woche\",\n \"Detail\": \"https://light.dsbcontrol.de/DSBlightWebsite/Data/13ccccbb-e6a8-466a-addc-00bba830c6cf/4f301632-7422-4186-96a2-2b7911f54bc5/Vertretungen-Woche.htm\",\n \"Tags\": \"\",\n \"ConType\": 6,\n \"Prio\": 0,\n \"Index\": 76,\n \"Childs\": [],\n \"Preview\": \"13ccccbb-e6a8-466a-addc-00bba830c6cf/4f301632-7422-4186-96a2-2b7911f54bc5/preview.png\"\n }\n ],\n \"Preview\": \"\"\n }\n]\n```\n\n# 2 The Android API\n\nThis was the most-used API of DSBMobile. Most implementations used it until it\nwas shut down in early 2021. It does **not** require any kind of session. Like\nthe other APIs it uses HTTPS for what could be referred to as Layer 4 or 5 in\nthe OSI Model.\n\n## Requests\n\nThere are seven known requests:\n\n- DataUnknown (0)\n- GetData (1)\n- MailType (2)\n- FeedbackType (3)\n- SubjectsType (4)\n- ErrorType (5)\n- PushSettings (6)\n\nBut only one of them, GetData (1), is actually used.\n\n## GetData\n\nGetData is sent as an HTTP POST request to\n`https://app.dsbcontrol.de/JsonHandler.ashx/GetData`.\n\n### Request\n\nThe body of the request looks like this:\n\n```js\n{\"req\": {\"Data\": \"DATA\", \"DataType\": 1}}\n```\n\nDATA is the actual data compressed with GZIP and encoded as Base64. The actual\ndata is a JSON-encoded string of the following schema:\n\n```ts\n{\n // username\n \"UserId\": string,\n\n // password\n \"UserPw\": string,\n\n // the version of the DSBMobile app you're pretending to run\n \"AppVersion\": string,\n\n // usually \"de\", some implementation allow for other languages\n \"Language\": string,\n\n // Android API Level + \" \" + Android Version\n // usually a static string (e.g. \"29 10.0\")\n \"OsVersion\": string,\n\n // original purpose unclear, probably a unique UUID for each DSBMobile install\n // most implementations generate a random UUIDv4 for each request\n \"AppId\": string,\n\n // model of the device running the app\n // usually a static string (e.g. \"SM-G950F\")\n \"Device\": string,\n\n // the bundle id of the app\n // most implementations pretend to be \"de.heinekingmedia.dsbmobile\"\n \"BundleId\": string,\n\n // the current datetime in JS Date.toISOString format, i.e. ISO 8601 with \"Z\"\n // at the end to indicate UTC timezone\n \"Date\": string,\n // the same as Date\n \"LastUpdate\": string,\n}\n```\n\n### Response\n\nThe body of the response looks like this:\n\n```js\n{\"d\": \"DATA\"}\n```\n\nFor the response the actual data is a really big JSON, which we will not care to\nfully document here. But for getting the plans this is enough:\n\n```dart\nif (actualData['Resultcode'] != 0)\n throw Error(actualData['ResultStatusInfo']);\n\nfor (var p in actualData['ResultMenuItems'][0]['Childs'][0]\n ['Root']['Childs']) {\n var url = p['Childs'][0]['Detail'];\n var title = p['Title'];\n outputPlan(title, url);\n}\n```\n\nParsing the plans from the HTML depends on the format of them, which usually is\nlike Untis always does HTML. But the HTML format is not documented here, because\nit does not depend on the DSB API used.\n\n## 2.1 The Web API\n\nThis is the API used mainly by the DSBMobile Webapp. It **does** require a\nsession kept in HTTP cookies. This API's requests are quite horrible and\nofficially implemented in hundreds of lines of weirdly obfuscated JavaScript.\nIts similarities to the Android API, however, are quite obvious.\n\n\u003c!-- vim: set wrap! : --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fampless%2Fadsignificamus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fampless%2Fadsignificamus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fampless%2Fadsignificamus/lists"}