API reference.

import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = os.environ["YARDAGE_API_URL"].rstrip("/")
api_key = os.environ["YARDAGE_API_KEY"]

def get_json(path, params=None):
    query = "?" + urlencode(params) if params else ""
    request = Request(
        base_url + path + query,
        headers={"Authorization": f"Bearer {api_key}"},
    )
    with urlopen(request, timeout=15) as response:
        return json.load(response)

page = get_json("/v1/courses", {"q": "Verulam", "limit": 5})
for course in page["courses"]:
    print(course["course_ref"], course["display_name"])
if not page["courses"]:
    print("No matching courses.")

const baseUrl = process.env.YARDAGE_API_URL;
const apiKey = process.env.YARDAGE_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set the API URL and key.");

async function getJSON(path, params = {}) {
  const url = new URL(path, baseUrl);
  url.search = new URLSearchParams(params).toString();
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(15000),
  });
  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}: ${await response.text()}`);
    error.status = response.status;
    error.retryAfter = response.headers.get("Retry-After");
    throw error;
  }
  return response.json();
}

const page = await getJSON("/v1/courses", { q: "Verulam", limit: 5 });
for (const course of page.courses) {
  console.log(course.course_ref, course.display_name);
}
if (!page.courses.length) console.log("No matching courses.");

curl --fail-with-body --silent --show-error --max-time 15 --get \
  "$YARDAGE_API_URL/v1/courses" \
  --header "Authorization: Bearer $YARDAGE_API_KEY" \
  --data-urlencode "q=Verulam" \
  --data-urlencode "limit=5"

# Continue after the Python quickstart.
if page["courses"]:
    course_ref = page["courses"][0]["course_ref"]
    detail = get_json(f"/v1/courses/{course_ref}")
    print(detail["display_name"])
    for card in detail["cards"]:
        print(card["tee"], card["total"], card["par_total"])
        for hole in card["holes"]:
            print(hole["number"], hole["yards"],
                  hole["par"], hole["stroke_index"])

// Continue after the JavaScript quickstart.
if (page.courses.length) {
  const courseRef = page.courses[0].course_ref;
  const detail = await getJSON(`/v1/courses/${courseRef}`);
  console.log(detail.display_name);
  for (const card of detail.cards) {
    console.log(card.tee, card.total, card.par_total);
    for (const hole of card.holes) {
      console.log(hole.number, hole.yards, hole.par, hole.stroke_index);
    }
  }
}

# Set COURSE_REF to a course_ref returned by the list request.
curl --fail-with-body --silent --show-error --max-time 15 \
  "$YARDAGE_API_URL/v1/courses/${COURSE_REF:?Set COURSE_REF first}" \
  --header "Authorization: Bearer $YARDAGE_API_KEY"

# Reuse get_json from the Python quickstart.
params = {"q": "Verulam", "limit": 25}
while True:
    result = get_json("/v1/courses", params)
    for course in result["courses"]:
        print(course["course_ref"], course["display_name"])
    cursor = result["next_cursor"]
    if cursor is None:
        break
    params["cursor"] = cursor

// Reuse getJSON from the JavaScript quickstart.
const params = { q: "Verulam", limit: 25 };
while (true) {
  const result = await getJSON("/v1/courses", params);
  for (const course of result.courses) {
    console.log(course.course_ref, course.display_name);
  }
  if (result.next_cursor === null) break;
  params.cursor = result.next_cursor;
}

# Set NEXT_CURSOR to the previous response's next_cursor value.
# Keep the same q filter. Stop when next_cursor is null.
curl --fail-with-body --silent --show-error --max-time 15 --get \
  "$YARDAGE_API_URL/v1/courses" \
  --header "Authorization: Bearer $YARDAGE_API_KEY" \
  --data-urlencode "q=Verulam" \
  --data-urlencode "limit=25" \
  --data-urlencode "cursor=${NEXT_CURSOR:?Set NEXT_CURSOR first}"