Project

pickpoint

0.0
The project is in a healthy, maintained state
pickpointpickpoint/ruby-sdkHomepageDocumentationSource CodeBug Tracker
Idiomatic Ruby client for the Pickpoint public HTTP API: geocoding, address search, routing, device registry, and client-token minting. No realtime tracking client in this gem.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
2,341
Stars
0
Forks
0
Watchers
0
 Releases
Current version
2.0.3
Total releases
1
First release
2026-08-10
Latest release
2026-08-10
 Development
Primary Language
Ruby
Licenses
Apache-2.0
Average date of last 50 commits
2026-08-10
Reverse Dependencies
0

 Dependencies
 Project Readme

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.list
puts devices.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[geocoding address routing devices],
  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", # default
  timeout: 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