yardage-hub-python

A Python client for yardage-hub, an open, crowdsourced database of golf courses: where they are, and their scorecards (holes, par, handicaps, tees, ratings, slopes, yardages). It starts from OpenStreetMap, and golfers fill in the rest.

This README is a quick start. The full API documentation is at lukeheide.com/sports/yardage-hub/docs.

Install

pip install yardage-hub

Python 3.9+, no dependencies.

Get a key

Every call needs a key. Sign in at lukeheide.com, open your profile page, and generate one. It's shown once, so copy it somewhere safe; if you lose it, regenerate it. Free keys allow 1,000 calls a day and 30 a minute.

from yardage_hub import YardageHub

hub = YardageHub("yh_...")   # or set YARDAGE_HUB_KEY and call YardageHub()

Quick start

# Find a course
found = hub.search_courses("pebble beach", state="CA")
course = hub.get_course(found["courses"][0]["id"])

print(course["course_name"], course["par"])
for tee in course["tee_sets"]:
    print(tee["tee_name"], tee["yardage"], [(r["gender"], r["course_rating"], r["slope"]) for r in tee["ratings"]])
for hole in course["holes_data"]:
    print(hole["number"], hole["par"], hole["handicap_index"], hole["yardages"], hole["pars"])

# Courses near a point (km)
near = hub.search_courses(lat=42.28, lon=-83.74, radius_km=10)

# Courses that need help from contributors near you
help = hub.courses_needing_help(lat=42.28, lon=-83.74, radius_km=25)
for c in help["courses"]:
    print(c["course_name"], [n["need"] for n in c["needs"]])

A hole's pars is None, or the tees that play it at a par of their own, by tee_key ({"red": 5}). A tee's par for a hole is its entry in pars, else women_par for a women's rating that has one, else par. A hole's handicaps works the same way for a tee's handicap, with women_handicap_index and handicap_index.

Name search forgives abbreviations, punctuation, and typos: "st johns", "mt pleasant", and "pebel beach" all find what you mean. It reads the club and course name together, so "detroit north" finds Detroit Golf Club's North Course.

Courses at the same club share a club_name, and each keeps its own course_name ("North Course"). get_course adds facility, the club with its address, postcode, phone, and website.

Methods

Each method returns the API's JSON as Python dicts and lists. The fields are described in the docs.

Writing: apply for write access

Every key can read. The last seven methods send data to a review queue, and a person reviews every edit, so they need a key with write access. New keys don't have it; a key without it gets a 403.

1. Contribute on the site first. Suggest edits on course pages at lukeheide.com/sports/yardage-hub.
2. Once 5 of your edits are approved, apply on your profile page. Say what you'll write, e.g. "building an app that lets people suggest edits".
3. The maintainer reviews the application. Once it's granted, your key can call the write methods.

Write access can be taken back. After a denial or revocation, you can apply again in 30 days.

An edit looks like this:

hub.submit_edit(course_id, {
    "course": {"phone": "(415) 561-4661", "scorecard_url": "https://example.com/scorecard.pdf"},
    "holes": [{"number": 1, "par": 4, "handicap": 7}],
    "tees": [{"name": "Blue", "color": "blue", "gender": "M", "rating": 70.8, "slope": 132,
              "yardages": {"1": 512, "2": 410}, "pars": {"2": 5}, "handicaps": {"1": 3}}],
}, note="From the 2026 scorecard")

A tee's pars and handicaps hold only the holes where it differs from the hole; None clears one.

It's validated right away (a bad payload raises a 400) and waits as pending until it's reviewed.

Clubs

Say which club a course belongs to. Like an edit, it waits for review:

hub.link_course(course_id, club_id, note="North and South are both Detroit Golf Club")
hub.unlink_course(course_id, note="This course isn't part of that club")

Once a link is approved, the club is a facility: search stops returning it and returns its courses instead. An unlinked club stays a facility. submit_edit can do the same with a link section: {"link": {"club_id": club_id}}, or None to unlink.

Scorecard photos

Send 1–4 photos of a course's card, in order (front, back, …). Each one can be a file path, bytes, or a binary file object:

result = hub.submit_scorecard_photos(course_id, ["front.jpg", "back.jpg"],
                                     note="Card from the pro shop", contributor_ref="user-42")
result["url"]  # the photos; it becomes the course's scorecard_url once approved

Photos stay private until a reviewer approves them: until then url returns 404, for you too.

• A photo is the card. If the course already has a scorecard_url, the call is refused (409) unless you pass replaces_link=True. Pass it only when the user says the current link is wrong.

• JPEG, PNG, or WebP, at most 2 MB each, and at least 1000 px on the long side (500 on the short). Photos straight off a phone are 2–6 MB, so resize first: about 2400 px on the long side, JPEG quality 85. With Pillow:

  from io import BytesIO
  from PIL import Image, ImageOps
  
  img = ImageOps.exif_transpose(Image.open("card.jpg")).convert("RGB")
  img.thumbnail((2400, 2400))
  buf = BytesIO()
  img.save(buf, "JPEG", quality=85)
  hub.submit_scorecard_photos(course_id, buf.getvalue(), contributor_ref="user-42")
  

• Metadata is removed on the server, including GPS location and orientation, so send photos upright (exif_transpose above does that).

• Limits: 5 photos per user a day, 200 per app, 500 in all (UTC days). An upload counts as two calls against your daily quota. App keys must pass contributor_ref, since the per-user limit counts by it.

• Don't send cards with personal information written on them (names, scores, handicaps). Approved photos are public.

• Junk is deleted. Photos that aren't a scorecard, can't be read, or show personal details are rejected as junk and deleted within the hour. After 3 in 30 days, that user's photo uploads are paused (403, saying until when). Links still work.

Errors

A failed call raises YardageHubError, with status, message, and retry_after (seconds, after a 429):

from yardage_hub import YardageHubError

try:
    hub.submit_edit(course_id, {"course": {"phone": "555-0100"}})
except YardageHubError as e:
    if e.status == 403:
        print("This key is read-only: apply for write access on your profile page")
    elif e.status == 429:
        print(f"Over a limit; retry in {e.retry_after} s")
    else:
        raise

Data and license

The data contains information from OpenStreetMap, © OpenStreetMap contributors, and is available under the ODbL. Credit it wherever you show it: "© OpenStreetMap contributors, yardage-hub". For the whole dataset, download the weekly snapshots from lukhed/yardage-hub-data; please don't harvest it through the API.

This client is MIT licensed.