python-api.md

Python client guide

ArccosClient is the entry point for read-only access to your Arccos Golf data. It exposes focused resources for rounds, handicap, clubs, courses, and stats.

Authentication

The safest interactive flow is to authenticate with the CLI first:

arccos login

Python can then load and refresh the cached credentials:

from arccos import ArccosClient

with ArccosClient() as client:
    print(client.profile())

For a first login or controlled automation, provide credentials directly:

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

ArccosClient also accepts a named profile, a custom creds_path, an existing Credentials object, or use_keyring=True.

Basic usage

from arccos import ArccosClient

with ArccosClient() as client:
    # Recent rounds
    rounds = client.rounds.list(limit=10)
    for round_ in rounds:
        print(
            round_["startTime"][:10],
            round_["noOfShots"],
            round_.get("courseName", ""),
        )

    # Hole-by-hole detail
    detail = client.rounds.get(rounds[0]["roundId"])
    for hole in detail["holes"]:
        print(hole["holeId"], hole["noOfShots"], hole["putts"])

    # Handicap and smart distances
    print(client.handicap.current())
    print(client.clubs.smart_distances())

Runnable examples are available in examples/.

Resources

Resource	Common methods
client.rounds	list, iter_all, get, holes, analysis, pace_of_play
client.handicap	current, history
client.clubs	list, smart_distances, bag, club_shots, shot_dispersion, distance_distribution, directional_bias, compare, tour_analytics
client.courses	get, played, search, passport, stats, hole_features, image URL helpers
client.stats	strokes_gained, dashboard_analysis, player_profile, personal_bests, tour_analytics
client	profile, details, user_id, email

Methods return typed dictionaries and lists matching upstream response data. Because the Arccos API is private and may evolve, callers should use .get() for optional fields where practical.

More examples

Iterate through every round

with ArccosClient() as client:
    for round_ in client.rounds.iter_all():
        print(round_["roundId"], round_["noOfShots"])

Map club IDs to bag configuration

with ArccosClient() as client:
    profile = client.profile()
    bag = client.clubs.bag(profile["bagId"])

    for club in bag["clubs"]:
        if club.get("isDeleted") != "T":
            print(club["clubId"], club.get("clubMakeOther"), club.get("clubModelOther"))

clubId is a user-specific bag slot, not a universal club name. Use the bag response to resolve its type, make, and model.

Dashboard analytics

with ArccosClient() as client:
    dispersion = client.clubs.shot_dispersion()
    dashboard = client.stats.dashboard_analysis(goal_hcp=5, no_of_rounds=20)
    profile = client.stats.player_profile()
    tour = client.stats.tour_analytics_summary()

Course and hole metadata

with ArccosClient() as client:
    courses = client.courses.search("Example Golf Club")
    features = client.courses.hole_features(10769, 7, version=11)
    image_url = client.courses.hole_image_url(10769, 7, 11, "2026-07")

API behavior

Golf data requests go to https://api.arccosgolf.com and are restricted to GET. The client exposes no data-API methods for creating, editing, or deleting data.

Authentication uses https://authentication.arccosgolf.com. Login and token refresh are the only non-GET interactions; they obtain credentials and do not modify golf or account data.

For endpoints, parameters, and known schemas, see the complete OpenAPI 3.1 specification.

Errors and cleanup

Use the client as a context manager so its HTTP session is always closed:

with ArccosClient() as client:
    rounds = client.rounds.list()

Authentication, request, and response errors are exposed through the exception types in arccos.exceptions. Never log credentials, access keys, or JWTs.

OpenTelemetry

OpenTelemetry is an optional, explicit integration. Install arccos-api[otel], configure providers in your application, and attach an instrumentor to one client:

from arccos import ArccosClient
from arccos.otel import ArccosInstrumentor

client = ArccosClient()
instrumentor = ArccosInstrumentor()
instrumentor.instrument(client)
try:
    client.rounds.list(limit=5)
finally:
    instrumentor.uninstrument()
    client.close()

The core install does not import or depend on OpenTelemetry. See the dedicated OpenTelemetry guide for provider setup, metrics, historical events, OTLP Collector configuration, and privacy constraints.