@opengolfapi/client

The OpenGolf client for any JS runtime — Expo, React Native, Capacitor, web, and Node. The free golf-data surface — 16k+ courses with holes, scorecard, hazard facts, location search, Sign in with OpenGolf, and free contribution — with offline course bundles, courses-near-me, and typed models. Fetch-based, zero framework deps.

Free surface only. Advanced geometry, the OpenGolf Rating, wallet/rewards, and booking are the enterprise layer and are not part of this package.

Install

npm i @opengolfapi/client

No required peer deps. For offline bundles, pass any key/value store as storage — React Native AsyncStorage, Capacitor Preferences (wrapped), or your own { getItem, setItem }.

Quickstart

import { OpenGolfMobile } from '@opengolfapi/client';

// storage is optional — pass one to enable offline bundles.
// RN:        new OpenGolfMobile({ storage: AsyncStorage })
// Capacitor: new OpenGolfMobile({ storage: { getItem:k=>Preferences.get({key:k}).then(r=>r.value), setItem:(k,v)=>Preferences.set({key:k,value:v}) } })
const og = new OpenGolfMobile();   // no key needed for reads

// Courses near the golfer
const { courses } = await og.coursesNearMe(56.348, -2.814, 15);   // St Andrews area, 15 mi

// Full course (facts + holes + scorecard)
const course = await og.course(courses[0].id);

// Play offline: download before the round, then `course()` works with no signal
await og.downloadCourse(courses[0].id);

Sign in with OpenGolf (OIDC)

import * as AuthSession from 'expo-auth-session';

const redirectUri = AuthSession.makeRedirectUri();
const url = og.signInUrl({ clientId: 'your.app', redirectUri, scope: 'openid profile' });
// open `url` in an AuthSession; on return you get `code`:
const tokens = await og.exchangeCode({ code, clientId: 'your.app', redirectUri });
// then reads on the golfer's OWN data:
const chain = new OpenGolfMobile({ apiKey: tokens.access_token }).myChain();

Contribute from the app (free)

const keyed = new OpenGolfMobile({ apiKey: FREE_KEY });
await keyed.submitCorrection({ course_id, field: 'phone', value: '+44 1334 466718' });
await keyed.submitRound(course_id, gpsTrack);   // breadcrumbs feed the open map

API (free surface)

| Method | What | |---|---| | searchCourses(q) | name search (global) | | coursesNearMe(lat, lng, radiusMi?) | location search | | course(id) | facts + holes + scorecard + hazard facts (offline-first) | | holes(id) | per-hole par / yardage / stroke index | | coursesInState(code) | every course in a US state | | downloadCourse(id) / isDownloaded / removeDownload | offline bundles | | submitCorrection / submitRound | free contribution (needs a free key) | | signInUrl / exchangeCode / myChain | Sign in with OpenGolf + own data |

Reads are cache-first (24h default) and fall back to the last persisted copy when offline.

MIT · built on the open OpenGolfAPI.