How it works
The moving parts of RideWiseCore and how a ride flows through them.
The two channels
Your backend talks to RideWiseCore over two channels, and both use the same API key.
| Channel | Protocol | Used for |
|---|---|---|
| REST API | HTTPS + JSON | Requesting, reading and cancelling matches; managing keys; reading usage and invoices |
| Real-time socket | Socket.IO over WebSocket | Streaming agent locations in; receiving ride offers, match updates and agent updates out |
Your backend opens one socket connection and keeps it open. Every connection that uses one of your keys joins your tenant's private room, so each of them receives all of your real-time events.
Life of a ride
Your backend RideWiseCore
──────────── ────────────
agent:location (every few secs) ──▶ store position, status, vehicle type
◀── agent:update (echo to your room)
POST /matches {pickup, vehicleType} ─▶ create match (status: searching)
◀── 202 Accepted + match record
find nearest eligible agent, reserve them
◀── ride:offer {matchId, agentId, expiresInMs: 15000}
(forward offer to that agent's app)
ride:respond {response: "accept"} ─▶ status → matched, agent → busy
◀── match:update {status: "matched", matchedAgentId}
— or, on decline / 15 s timeout —
◀── ride:offer to the next-nearest agent
— or, when no agents are left —
◀── match:update {status: "unmatched"}Key rules at a glance
| Rule | Value |
|---|---|
| Offer window for an agent to respond | 15 seconds |
| An agent counts as gone after no location for | 30 seconds |
| Default / maximum search radius | 10 km / 50 km |
| Candidates considered per match | Up to 50 nearest agents |
| REST rate limit | 300 requests / minute per API key |
| Billing period | Calendar month, UTC |
Your agent IDs
An agent ID is any string you choose, up to 100 characters, made of letters, numbers, _ and -. Use your own internal agent ID or an opaque alias of it. RideWiseCore never needs an agent's name or phone number.
Use the same ID for an agent every time. Their status, reservations and billing presence are all tracked by that ID.
Vehicle types
vehicleType is a free-form string, up to 50 characters, that you define, for example sedan, van or bike. A match only goes to agents whose vehicleType is exactly the one requested, including case. Pick a fixed vocabulary and use it everywhere.
Continue reading
- Authentication: API keys vs. dashboard logins.
- Agent tracking: statuses, freshness and going offline.
- Matching: how candidates are chosen and how escalation works.