Connecting

Parklio pushes results and status changes over a Socket.IO connection. Connect once from your server, keep the connection open, and listen for the events you need.

Prerequisites

• An API token; see Authentication. Realtime uses the same token as the REST API.
• A Socket.IO v4 client: socket.io-client 4 for Node.js, or python-socketio 5 for Python.

Connection settings

Setting	Value
URL	https://api.parklio.com
Namespace	/v2/realtime
Path	/socketio
Auth	your API token in the handshake query parameter token

Connect

Node.js

connect.ts

import { io } from 'socket.io-client';

const socket = io('https://api.parklio.com/v2/realtime', {
  path: '/socketio',
  query: { token: process.env.PARKLIO_API_TOKEN },
});

socket.on('connect', () => console.log('Connected'));
socket.on('authorized', () => console.log('Token accepted'));
socket.on('connect_error', (err) => console.error('Could not connect:', err.message));
socket.on('disconnect', (reason) => console.warn('Disconnected:', reason));

// Every payload is a JSON string: parse it before reading fields.
socket.on('lot_change', (raw: string) => {
  const event = JSON.parse(raw);
  console.log('lot_change', event.lot_id, event.event_id, event.data.status);
});

Python

connect.py

import json
import os

import socketio

NS = "/v2/realtime"
sio = socketio.Client()  # reconnects automatically


@sio.event(namespace=NS)
def connect():
    print("Connected")


@sio.on("authorized", namespace=NS)
def on_authorized(_):
    print("Token accepted")


@sio.event(namespace=NS)
def connect_error(data):
    print("Could not connect:", data)


@sio.on("lot_change", namespace=NS)
def on_lot_change(raw):
    event = json.loads(raw)  # every payload is a JSON string
    print("lot_change", event["lot_id"], event.get("event_id"), event["data"]["status"])


sio.connect(
    f"https://api.parklio.com?token={os.environ['PARKLIO_API_TOKEN']}",
    namespaces=[NS],
    socketio_path="socketio",
)
sio.wait()

Authentication

The server checks the token while the connection is being set up:

• Accepted: it sends an authorized event (with an empty payload), and the connection completes. Your client's connect fires.
• Rejected (missing, invalid or revoked token): the connection is refused and your client gets connect_error. Don't retry in a loop with the same token; fix it first.

Either authorized or connect tells you you're in. authorized can arrive just before connect.

The server adds your connection to its rooms (below) a moment after that, once it has looked up your token. Events sent in that moment don't reach you, so read the state you track over REST once you're connected, not before.

What you receive

There are no subscribe messages, and the server doesn't accept any messages from you: the events you receive are fixed when you connect, by the kind of token. If a user is assigned to another lot later, their connection gets that lot's events only after it reconnects.

Token	You receive events for
API token	everything in your account
User token	that user, plus every lot the user is assigned to

Use an API token for integrations. Events for things not attached to a lot (for example a product with no lot) aren't sent at all.

Your connection also receives events nobody on your side requested: changes made from the Connect app, by other users, or by Parklio itself. Filter on what you care about.

Payloads are JSON strings

Every event's payload is a string of JSON, not an object. Call JSON.parse (Node) or json.loads (Python) first. The event catalog shows the parsed objects.

Reconnecting

Both clients reconnect automatically, with backoff, and the server puts you back in the same rooms when you're back. But events sent while you were disconnected are lost: there's no replay. After every reconnect, re-read what you track over REST. See Patterns.

Connect before you send commands

Results of remote-control commands arrive only as realtime events. Connect, and wait until you're connected, before calling POST /v2/products/{id}/state; otherwise you can miss the result.

Next

• Events: the catalog.
• Patterns: correlating results, deduplicating, resyncing.