> For the complete documentation index, see [llms.txt](https://developer.aiodds.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.aiodds.com/explore/data-format.md). # Data Format ## JSON Most of our API responses are in JSON format. It's a structured data "text" format, maturely used in internet data transmission. Its advantages include excellent readability and versatility; virtually all high-level programming languages ​​support it by default, requiring no additional extensions. If you are unfamiliar with JSON, please refer to: * [https://www.json.org](https://www.json.org/) *** ## protobuf For the [snapshot](/bookmaker-odds/bookmaker-odds/snapshot.md) API and MQTT data stream push phase, we use the protobuf format instead of the JSON structure. While JSON, as a human-readable text exchange format, has unparalleled advantages in simplicity, it is not advantageous in terms of data packet size, especially in HTTP applications involving large data transfers. Protocol Buffers, introduced by Google, is a language-independent, platform-independent, and scalable mechanism for serializing structured data. It is smaller, faster, but also more complex (compared to JSON). You only need to define the data structure once, and then you can easily write and read your structured data from various data streams using various languages ​​with specially generated source code. If you are unfamiliar with Protocol, please refer to: * github protobuf: * protobuf.dev: [https://protobuf.dev](https://protobuf.dev/) One behavior of protobuf to improve compression ratio is that it removes fields that have default values. For example, the default value for integer types is 0, and the default value for string types is an empty string. If some values ​​are found to be missing after deserialization (even though they are not), it means that the field is a default value. Generally, deserialization methods of high-level languages ​​provide an optional parameter: whether to automatically complete the default value. *** ## Stream JSON Lines The [snapshot v2](/bookmaker-odds/bookmaker-odds/snapshot-v2.md) API delivers a full odds snapshot as an **HTTP streaming response** in **JSON Lines (JSONL)** format. Unlike a conventional JSON API that buffers the entire payload and returns one `application/json` body, this endpoint streams data **incrementally**: each batch is a complete, self-contained JSON object written as a single line, terminated by `\n`. Clients can parse and process batches as they arrive, without waiting for the full snapshot to finish. #### Why JSONL (not a single JSON document)? Snapshot payloads can be large. A single monolithic JSON response forces the client to: 1. Wait until the server finishes serializing everything 2. Buffer the entire body in memory 3. Only then begin parsing With `application/jsonl`, the server: 1. Yields data in batches (default batch size: 200) 2. Serializes each batch as one JSON object 3. Sends batch payload immediately 4. Closes the stream with EOF when done This keeps peak memory lower on both sides and allows progressive processing. *** ## MQTT MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth. Real-time data push is the core service we provide and the only way to obtain real-time data. Its characteristics are: large data volume and high push frequency. Therefore, we chose: * Data format: protobuf * Push protocol: MQTT over WebSocket #### Why not MQTT TCP but MQTT over WebSocket? This is a compromise based on various considerations. Although TCP has many advantages, there are currently no plans to provide it. If you are implementing your own WebSocket transport layer, pay attention to the WebSocket ping/pong mechanism; otherwise, you may experience unexpected disconnections at the WebSocket level, such as error code 1006 (Abnormal Closure). If you are unfamiliar MQTT, please refer to: * mqtt.org: #### Mqtt protocols we support:
protocolsprotocol_levelwhether support
v3.1 3false
v3.1.14true
v5.05true
## Diagram Instruction
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.aiodds.com/explore/data-format.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.