pickpoint (Rust SDK)
Official Rust SDK for Pickpoint — a geolocation platform with four APIs under one key:
| API | What it does |
|---|---|
| Geocoding | Address ↔ coordinates (forward, reverse, place lookup) |
| Address search | Typeahead / autocomplete for address inputs |
| Routing | Routes, matrices, optimized multi-stop, elevation |
| Device tracking | Register devices over HTTP; stream live GPS over WebSocket |
Built for maps, delivery, logistics, and anything that needs places, routes, or live location. Data is OpenStreetMap-backed; HTTP responses are plain JSON / GeoJSON. Docs: pickpoint.io/docs.
This crate is the idiomatic Rust client for that platform:
| Module | Import | Role |
|---|---|---|
| root | pickpoint |
HTTP: geocode, search, routing, devices, client-tokens |
tracking |
pickpoint::tracking |
Live GPS over WebSocket (tracking.v2) |
Apache-2.0. Go sibling: github.com/pickpoint/go-sdk. JS sibling: @pickpoint/sdk. Wire schema: pickpoint-proto.
[]
= "2"
= { = "1", = ["macros", "rt-multi-thread"] }
Public API
One Client, one auth session, whole public HTTP surface:
use ;
async
API map
| Method | HTTP | Notes |
|---|---|---|
forward / geocoding().forward |
GET /v2/geocode/forward |
Nominatim-style; returns Vec<Value> |
reverse / geocoding().reverse |
GET /v2/geocode/reverse |
Option<Value> |
lookup / geocoding().lookup |
GET /v2/address/lookup |
e.g. osm_ids |
forward_batch / reverse_batch / lookup_batch |
same | Geocoding only; conveyor ≤20 in flight |
search / address().search |
GET /v2/address/search |
Photon autocomplete |
route / optimized_route / matrix / locate / elevation |
POST /v2/route… |
Valhalla JSON body → Value |
devices().list / get / create / update / delete |
/v2/devices |
Typed structs |
devices().command |
POST …/command |
Payload &[u8] (SDK base64-encodes) |
mint_client_tokens |
POST /v2/client-tokens |
Package helper; needs secret api_key |
Query params for geocode/address are Query (HashMap<String, String>) — use [query] helper or pass whatever the public API accepts (q, lat, lon, limit, accept-language, …).
Auth
Provide exactly one of:
| Field | Header | Use |
|---|---|---|
api_key |
x-api-key |
Backends, workers, CLIs |
client_auth |
Authorization: Bearer |
Short-lived pair; auto-refresh |
access_token |
Authorization: Bearer |
Static token, no refresh |
Keep the secret API key on the server. For client apps mint client-tokens and pass client_auth.
use ;
let pair = mint_client_tokens
.await?;
let pp = new
.await?;
Refresh behavior (same as Go/JS):
- Proactive refresh at ~50% of access TTL (single-flight).
- On HTTP 401, one refresh + retry.
- If refresh fails →
err.is_auth().
Config
use Duration;
use Config;
let cfg = with_api_key
.base_url // default
.timeout
.max_retries
.retry_base
.concurrency;
| Constant | Value |
|---|---|
DEFAULT_BASE_URL |
https://api.pickpoint.io |
DEFAULT_TIMEOUT |
30s |
DEFAULT_MAX_RETRIES |
3 |
DEFAULT_RETRY_BASE |
1s (MIN_RETRY_BASE = 200ms) |
MAX_CONCURRENCY |
20 |
Errors
match pp.devices.get.await
Tracking
Live GPS is a separate WebSocket session: wss://tracking.pickpoint.io/v2/ws, subprotocol tracking.v2. It is not pickpoint::Client (that one is HTTP).
A dropped socket is not a new trip. The SDK reconnects and Resumes the same track_uid.
First publish starts the trip if none is live. close sends TrackStop then hangs up. Call start_track only to supersede (new order / TRACK_NOT_FOUND) or to set a route.
Device (publisher)
use ;
async
Listener (dashboard)
The JWT is the client-token access_token — same one as HTTP client_auth. Mint it on your backend with scope devices (API key never goes in the dashboard).
use ;
use ;
let pair = mint_client_tokens
.await?;
let session = connect
.await?;
loop
Wire format: pickpoint-proto.
Develop
Live geocode batch e2e (skipped unless the key is set; 1000 requests each):
PICKPOINT_API_KEY=…
# optional: PICKPOINT_BASE_URL=https://api.pickpoint.io (default: https://beta-api.pickpoint.io)
CI & release
- PR →
.github/workflows/ci.yml(fmt,clippy,test) - CI on
maingreen (untagged HEAD) → bump patch inCargo.toml, tagvX.Y.Z,cargo publish(OIDC) + GitHub Release in the same job
(tag push viaGITHUB_TOKENdoes not start new workflows — publish cannot wait on the tag event) - Manual tag
v*(pushed by a human) → publish + GitHub Release
Minor/major: bump version in Cargo.toml in a PR, merge with [skip release] in the commit message, then:
crates.io Trusted Publishing must match this workflow: repo rust-sdk, workflow release.yml (leave Environment empty).