Integration Guide
PickPoint exposes four APIs over standard HTTPS (REST/JSON) and WebSocket (tracking.v2). We recommend the official SDKs for your language — they handle auth, retries, and the tracking wire protocol so you can ship faster and avoid common integration pitfalls.
Official SDKs
Each SDK wraps the same surface: forward, reverse, search, route, device registry, and (where supported) live tracking via connect / publish.
| Language | Package | Tracking WS |
|---|---|---|
| JavaScript / TypeScript | @pickpoint/sdk (npm) | @pickpoint/sdk/tracking |
| Python | pickpoint (PyPI) | pickpoint.tracking |
| Go | github.com/pickpoint/go-sdk | go-sdk/tracking |
| Rust | pickpoint (crates.io) | pickpoint::tracking |
| Kotlin / Java | io.pickpoint:pickpoint (Maven) | io.pickpoint.tracking |
| Dart | pickpoint (pub.dev) | package:pickpoint/tracking.dart |
| C++ | cpp-sdk | pickpoint::tracking |
| Ruby | pickpoint gem | HTTP only |
| Swift / iOS | No official SDK — implement wire format from pickpoint-proto | |
Why use the SDK?
- Less boilerplate — auth headers, query encoding, JSON bodies, and typed errors are built in; no hand-rolled
fetchor socket framing. - Tracking protocol — binary
tracking.v2frames, Hello handshake, heartbeats, sequence numbers, and acknowledgements handled automatically. - Resilience — WebSocket reconnect with trip Resume (same
trackUidafter a drop); client-token refresh; HTTP retries on transient failures. - Batch & limits — geocode batch helpers with in-flight caps; rate limiting helpers on the publish path (up to 50 Hz).
- Cross-language consistency — same API surface across JavaScript, Python, Go, Rust, JVM, Dart, and C++.
Not using one of these languages? All HTTP endpoints are documented in the OpenAPI reference on docs.pickpoint.io. Live tracking wire format is in pickpoint-proto.
Choose your integration pattern
There is no single “correct” architecture — pick the pattern that matches where your code runs and who holds credentials.
| Pattern | When | Credentials | Examples |
|---|---|---|---|
| 1. Server-side | Backend jobs, microservices, CLI, internal tools | X-Api-Key in server env | Batch geocoding |
| 2. Client-facing API | Browser or mobile UI needs geocoding/routing | Your auth → backend SDK → PickPoint | Server integration, Web maps |
| 3. Live tracking | Real-time GPS publish and subscribe | Device: client-id + secret direct; Subscriber: client-token via backend | Device Tracking, Navigator |
Pattern 1: Server-side
Your server holds the API key and calls PickPoint directly via the SDK. No REST wrapper, no proxy — just PICKPOINT_KEY in an environment variable and SDK calls from your job or service.
Pattern 2: Client-facing backend
Use this when browsers or mobile apps need geocoding or routing but must not hold your API key. Clients authenticate against your backend (JWT, session, OAuth). Your backend validates the request, calls PickPoint via the SDK, and returns the result.
Pattern 3: Live tracking
Devices publish GPS directly to PickPoint using per-device credentials — safe to embed in mobile and IoT apps. Subscribers (dispatch dashboards) connect through your backend, which mints a short-lived client token.
Security rules
Three credential types — don't mix them up:
| Credential | Scope | Where it lives |
|---|---|---|
API key (X-Api-Key) | Full account access — billing, all APIs | Server env only — never in browser, mobile bundle, or firmware |
Device credentials (client-id + secret) | One device — publish location only | Safe in mobile/IoT apps; rotate if device is lost |
Client token (accessToken) | Short-lived subscriber access (scope devices) | Minted on backend; passed to dashboard clients |
- Store
PICKPOINT_KEYin an environment variable, never in source code. - Use separate keys for development, staging, and production.
- Set up usage alerts — an unexpected spike is the first sign of a leaked key.
- Rotate the key immediately if you suspect exposure.
Getting StartedServer IntegrationDevice TrackingAPI Reference ↗