pickpoint (Python SDK)

Official Python SDK for Pickpoint — a geolocation platform with four APIs under one key:

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 package is the idiomatic async Python client for that platform:

Apache-2.0. Go sibling: github.com/pickpoint/go-sdk. Rust sibling: github.com/pickpoint/rust-sdk. JS sibling: @pickpoint/sdk. Wire schema: pickpoint-proto.

pip install pickpoint

Requires Python 3.10+.

python-sdk/
  src/pickpoint/           # HTTP client
  src/pickpoint/tracking/  # tracking session client
  src/pickpoint/tracking/v2/  # protobuf stubs

Public API

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

import asyncio
import os
from pickpoint import Client, Config

async def main() -> None:
    async with Client(Config(api_key=os.environ["PICKPOINT_API_KEY"])) as pp:
        places = await pp.forward({"q": "Berlin", "limit": "5"})
        print(places)

        await pp.reverse({"lat": "52.52", "lon": "13.405"})
        await pp.search({"q": "Alexanderplatz"})
        await pp.route({
            "locations": [
                {"lat": 52.52, "lon": 13.40},
                {"lat": 52.53, "lon": 13.42},
            ],
            "costing": "auto",
        })

        devices = await pp.devices.list()
        print(devices.total)

asyncio.run(main())

API map

Query params for geocode/address are plain dict[str, str].

Auth

Provide exactly one of:

Keep the secret API key on the server. For client apps mint client-tokens and pass client_auth.

from pickpoint import Client, ClientAuth, Config, mint_client_tokens

pair = await mint_client_tokens(
    Config(api_key=os.environ["PICKPOINT_API_KEY"]),
    scopes=["geocoding", "address", "routing", "devices"],
    ttl_sec=600,
)

async with Client(
    Config(
        client_auth=ClientAuth(
            access_token=pair.access_token,
            refresh_token=pair.refresh_token,
            expires_at=pair.expires_at,
        )
    )
) as pp:
    ...

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

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

Config

Config(
    api_key="…",
    base_url="https://api.pickpoint.io",  # default
    timeout=30.0,
    max_retries=3,
    retry_base=1.0,
    concurrency=20,
)

Tracking

Realtime publisher / listener over binary WebSocket (tracking.v2.proto subprotocol). gRPC via Transport.GRPC.

import asyncio
from pickpoint import tracking
from pickpoint.tracking.v2 import LatLng

async def main() -> None:
    client = await tracking.connect(
        tracking.Config(
            endpoint="wss://tracking.pickpoint.io",  # local: "ws://127.0.0.1:3100"
            device=tracking.DeviceAuth(
                client_id=device_uid,
                client_secret=device_secret,
            ),
        )
    )
    try:
        track_uid = await client.start_track(
            LatLng(latitude=55.75, longitude=37.61)
        )
        seq, ok = await client.publish(LatLng(latitude=55.76, longitude=37.62))
        # managed client_seq; ok=False if rate-limited locally
        await client.stop_track()
    finally:
        await client.close()

asyncio.run(main())

Auth modes

Exactly one of device / listener is required.

Main methods

Limits enforced client-side: MAX_PUBLISH_HZ = 50, MAX_EVENT_BYTES = 4 KiB, MAX_EVENT_HZ = 1.

Develop

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Live geocode batch e2e (skipped unless the key is set; 1000 requests each):

PICKPOINT_API_KEY=… pytest tests/test_e2e_geocode_batch.py -q --tb=short
# optional: PICKPOINT_BASE_URL=https://api.pickpoint.io  (default: https://beta-api.pickpoint.io)

CI & release

• PR → .github/workflows/ci.yml (pytest on Python 3.10 / 3.12 / 3.13)
• Push to main (untagged HEAD) → bump patch, tag vX.Y.Z, PyPI publish (OIDC) + GitHub Release in the same job
  (tag push via GITHUB_TOKEN does 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 pyproject.toml and __version__ in a PR, merge with [skip release] in the commit message, then:

git tag v2.1.0
git push origin v2.1.0

PyPI Trusted Publishing must match this workflow: repo python-sdk, workflow release.yml, environment pypi.

Protobuf stubs under src/pickpoint/tracking/v2 are generated from pickpoint-proto. Regenerate:

python -m grpc_tools.protoc \
  -I ../pickpoint-proto \
  --python_out=src/pickpoint/tracking/v2 \
  --grpc_python_out=src/pickpoint/tracking/v2 \
  ../pickpoint-proto/tracking/v2/*.proto
# then flatten nested tracking/v2/ paths and fix imports to `from . import …_pb2`