General Platform Conventions
AVA Golf ingests shot-level golf data from multiple sources — launch monitors, simulators, GPS-based round trackers, and mobile scoring apps — and unifies it into a single analytics pipeline that powers strokes-gained analysis, trend tracking, and performance mapping.
This guide defines what we need from your integration so data flows cleanly into that pipeline. Requirements are split into two partner profiles:
- Rounds & Mobile App Partners — GPS-enabled apps and wearables that capture on-course round data (shot locations, scoring, club usage).
- Launch Monitor & Session Partners — hardware devices and simulator software that produce ball-flight and club-delivery metrics during practice or indoor sessions.
The closer your API output maps to the data schemas described here, the faster we ship your integration.
Conventions
Section titled “Conventions”Before diving into partner-specific requirements, note the conventions that apply to every integration.
Authentication & Account Linking
Section titled “Authentication & Account Linking”We support OAuth 2.0 (preferred) and OAuth 1.0a. Your API must provide a standard authorization flow with refresh-token support so we can re-authenticate silently without re-prompting the user. Every integration needs these endpoints, or functional equivalents:
/oauth/authorizeInitiate the OAuth flow; redirect the user to your consent screen.
/oauth/tokenExchange authorization code for access + refresh tokens.
/oauth/token/refreshRefresh an expired access token without user interaction.
/users/meReturn the authenticated user’s profile. Must include a stable, unique user identifier.
Webhooks
Section titled “Webhooks”Notify us when a round or session is completed, edited or deleted, and when a user disconnects or changes permissions. Webhooks are the preferred integration path; see Webhooks.
Data Format
Section titled “Data Format”JSON over HTTPS.
Metric Units Preferred
Section titled “Metric Units Preferred”We work in meters and meters per second internally. Your API may return imperial or metric — just be explicit about units in your documentation so we can convert correctly (see Unit Conventions).
Stable Unique IDs
Section titled “Stable Unique IDs”Every shot and every session/round must carry a stable, unique identifier. Re-syncing the same data should never create duplicates.
Timestamps
Section titled “Timestamps”ISO 8601 format with timezone offset (e.g., 2026-03-16T14:30:00-07:00). UTC is
acceptable, but offset-aware is preferred so we can localize for the user.
Pagination
Section titled “Pagination”For list endpoints returning historical data, implement cursor-based or offset pagination. Required for production-scale backfill of user history.
Rate Limiting
Section titled “Rate Limiting”Document your rate limits and return a standard 429 Too Many Requests with a Retry-After
header.
Error Responses
Section titled “Error Responses”Use conventional HTTP status codes. Error bodies should include a machine-readable code
and a human-readable message.
Changelog
Section titled “Changelog”1.3 — 16 October 2026
Section titled “1.3 — 16 October 2026”- The shot identifier is
sourceIdeverywhere. The Core Endpoints pages called itshotId; the Data Schema pages already saidsourceId. round.editedandround.deletedare strongly recommended, assession.editedandsession.deletedalready were.round.completedandsession.completedare still required. See Webhooks.- The hole’s first-putt distance is
firstPuttDistanceMeters, in meters like every other distance. It wasfirstPuttDistanceFeet. - Webhooks and the account-linking endpoints are each described once, for both partner families: Webhooks and Authentication & Account Linking.
1.2 — 1 April 2026
Section titled “1.2 — 1 April 2026”Earlier changes weren’t recorded here.