arccos-api

Your Arccos Golf data, from the terminal or Python.

arccos-api is an unofficial, read-only client for exploring your own rounds, handicap, club distances, strokes gained, pace of play, and more.

Important: Arccos does not provide a public API. This project is not affiliated with Arccos Golf LLC, and upstream changes may occasionally require a library update.

What you can do

• Browse rounds and hole-by-hole scoring
• Track handicap, scoring, and strokes-gained trends
• Inspect smart distances, club shots, and dispersion
• Compare rounds and review personal bests
• Explore courses, pace of play, and hole imagery metadata
• Export data as JSON, CSV, or NDJSON
• Export opt-in operational and golf telemetry through OpenTelemetry/OTLP
• Use the same data through a Python client

Golf data access is read-only by design. The client only sends GET requests to the Arccos data API. Login and token refresh use the authentication service's required POST requests, but never create, edit, or delete golf or account data.

Install

Requires Python 3.11 or newer.

pip install arccos-api

For the CLI on macOS or Linux, Homebrew is also available:

brew install pfrederiksen/tap/arccos-api

Optional operating-system keyring support:

pip install 'arccos-api[keyring]'

Optional vendor-neutral OpenTelemetry support:

pip install 'arccos-api[otel]'

Quick start

Authenticate once, then start exploring:

arccos login
arccos rounds
arccos handicap
arccos clubs

Some useful next steps:

arccos round 12345678            # hole-by-hole round detail
arccos stats --dashboard         # strokes-gained dashboard
arccos trends                    # handicap trend
arccos pace                      # pace of play by course
arccos export -f csv -o rounds.csv

Most display commands support --json, and every command supports --help. See the CLI guide for the complete command list, filtering, profiles, shell completion, and export examples.

Use it from Python

arccos login caches credentials, so Python can reuse them without putting a password in source code:

from arccos import ArccosClient

with ArccosClient() as client:
    rounds = client.rounds.list(limit=5)
    handicap = client.handicap.current()
    distances = client.clubs.smart_distances()

    print(f"Handicap: {handicap['userHcp']:.1f}")
    for round_ in rounds:
        print(round_["startTime"][:10], round_["noOfShots"])

You can also authenticate directly:

client = ArccosClient(email="you@example.com", password="your_password")

See the Python client guide for resources and examples, or browse the complete OpenAPI 3.1 specification.

Documentation

Guide	Contents
CLI guide	Commands, filters, exports, profiles, and environment variables
Python client	Authentication, resources, and usage examples
OpenTelemetry	Explicit instrumentation, OTLP export, cardinality, and privacy
OpenAPI specification	Complete endpoint and schema reference
Examples	Runnable Python scripts
Contributing	Local setup, tests, style, and releases
Security	Credential handling and vulnerability reporting
Changelog	Release history

Credentials and privacy

• Credentials are cached with owner-only permissions in your platform's config directory. Legacy ~/.arccos_creds.json files migrate automatically.
• Named profiles are available through ARCCOS_PROFILE or command options.
• Set ARCCOS_KEYRING=true to use the optional OS keyring integration.
• arccos logout clears local credentials but cannot revoke upstream tokens; change your Arccos password if credentials may be compromised.
• Use your own account and avoid aggressive polling.

Run arccos doctor to check configuration, credentials, and API connectivity. See SECURITY.md to report a vulnerability privately.

Development

git clone https://github.com/pfrederiksen/arccos-api.git
cd arccos-api
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest

Tests use mocked and sanitized responses; no Arccos account is required. See CONTRIBUTING.md for the full development workflow.

Disclaimer

Not affiliated with, endorsed by, or connected to Arccos Golf LLC. Use your own account credentials only. This project is intended for personal data access and research.

Released under the MIT License.