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:
- Launch Monitor & Session Partners — hardware devices and simulator software that produce ball-flight and club-delivery metrics during practice or indoor sessions.
- Rounds & Mobile App Partners — GPS-enabled apps and wearables that capture on-course round data (shot locations, scoring, club usage).
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
Section titled “Authentication”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.
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 Appendix A — 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.