pickpoint (Ruby SDK)

Official Ruby SDK for Pickpoint — geocoding, address search, routing, and device registry over HTTP.

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
Devices	Register / manage tracking devices over HTTP

This gem covers the public HTTP API only (no realtime WebSocket / gRPC tracking client). Docs: pickpoint.io/docs.

Apache-2.0. Siblings: @pickpoint/sdk, go-sdk, python-sdk, rust-sdk.

gem install pickpoint
# or in Gemfile:# gem "pickpoint"

Requires Ruby 3.1+. Zero runtime dependencies (stdlib Net::HTTP + JSON).

---

Public API

One Client, one auth session, whole public HTTP surface:

require"pickpoint"pp=Pickpoint::Client.new(Pickpoint::Config.new(api_key: ENV.fetch("PICKPOINT_API_KEY")))places=pp.forward("q"=>"Berlin","limit"=>"5")pp.reverse("lat"=>"52.52","lon"=>"13.405")pp.search("q"=>"Alexanderplatz")pp.route("locations"=>[{"lat"=>52.52,"lon"=>13.40},{"lat"=>52.53,"lon"=>13.42}],"costing"=>"auto")devices=pp.devices.listputsdevices.total

API map

Method	HTTP	Notes
forward / geocoding.forward	GET /v2/geocode/forward	Nominatim-style; returns Array
reverse / geocoding.reverse	GET /v2/geocode/reverse	Hash or nil
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
devices.list / get / create / update / delete	/v2/devices	Typed structs
devices.command	POST …/command	Payload bytes (SDK base64-encodes)
Pickpoint.mint_client_tokens	POST /v2/client-tokens	Needs secret api_key

Query params for geocode/address are plain Hash of strings (symbol keys are fine).

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.

pair=Pickpoint.mint_client_tokens(Pickpoint::Config.new(api_key: ENV.fetch("PICKPOINT_API_KEY")),scopes: %w[geocodingaddressroutingdevices],ttl_sec: 600)pp=Pickpoint::Client.new(Pickpoint::Config.new(client_auth: Pickpoint::ClientAuth.new(access_token: pair.access_token,refresh_token: pair.refresh_token,expires_at: pair.expires_at)))

Refresh behavior (same as Go/Python/JS):

1. Proactive refresh at ~50% of access TTL (single-flight).
2. On HTTP 401, one refresh + retry.
3. If refresh fails → Pickpoint::APIError with auth code.

Config

Pickpoint::Config.new(api_key: "…",base_url: "https://api.pickpoint.io",# defaulttimeout: 30.0,max_retries: 3,retry_base: 1.0,concurrency: 20)

Constant	Value
DEFAULT_BASE_URL	https://api.pickpoint.io
DEFAULT_TIMEOUT	30s
DEFAULT_MAX_RETRIES	3
DEFAULT_RETRY_BASE	1s (MIN_RETRY_BASE = 0.2s)
MAX_CONCURRENCY	20

---

Development

bundle install
bundle exec rake test

Contributing

Fork and open a pull request against dev — not main. Only pickpoint organization members can merge dev or main. Releases are dev → main.