The format

A record

On this date, on this hole, the cup was here.

That is all a record says. The point locates itself: whoever wants to know which course or which green it belongs to asks the coordinate, not an ID. The hole number is the one the club uses, and it describes the record without being a key.

date,date_basis,hole,lat,lon,source,accuracy_m,front_m,left_m,input_front,input_offset,input_side,input_unit,channel,missing
2027-04-12,local,7,52.1234561,13.1234573,estimated,,12,9.5,12,5,right,m,openyardage,
2027-04-12,local,8,52.1241077,13.122915,mapped,,,,,,,,openyardage,
2027-04-12,local,9,,,,,,,,,,,,1

The last row is a hole where a pin was set that day but its position has been lost. It stays in the file, because a cup did stand there.

Sources

Positions say how they were obtained; entries made before a tool stored coordinates carry no source. An estimate is useful, but it is not a measurement; the column source keeps the two apart.

Columns

One row per hole and day. The same names are used in the CSV and in the properties of the GeoJSON. Empty means unknown, never zero.

Not in the data

• No IDs for courses, holes, greens or people, and no OpenStreetMap IDs. They change; a coordinate does not.
• No names and no e-mail addresses.
• No time of day. At a small club, the time the pins were set is one person's working hours.
• No pin sets, rotations or plans. Those belong to the tool a club works with.

Files

A day is published three days later, once no course anywhere can still enter pins for it. After that the file does not change. Corrections and withdrawals get files of their own, so what was published on a day can always be checked.

v1/index.json                 list of files, sizes, sha256, format version
v1/days/2027-04-12.csv
v1/days/2027-04-12.geojson
v1/years/2027.csv             all days of a year

Use the files

No account and no key. Everything lives under one address, and index.json lists every file with its size, row count and sha256 checksum.

https://data.openpinsheet.com/v1/index.json
https://data.openpinsheet.com/v1/days/YYYY-MM-DD.csv
https://data.openpinsheet.com/v1/days/YYYY-MM-DD.geojson
https://data.openpinsheet.com/v1/years/YYYY.csv

Until the first day is published, index.json does not exist and the address answers 404.

index.json

{
 "format": 1,
 "generated": "2027-04-15",
 "license": { "name": "Open Database License 1.0", "spdx": "ODbL-1.0", "url": "..." },
 "files": [
  { "path": "days/2027-04-12.csv", "kind": "day", "date": "2027-04-12",
    "bytes": 1234, "sha256": "...", "rows": 18 },
  { "path": "years/2027.csv", "kind": "year", "year": "2027", ... }
 ]
}

Caching and browsers

• Day files never change. They are served with a one-year cache, so download each one once.
• index.json and the year files change when a day is added and are cached for five minutes. Checking index.json once a day is enough: a new day appears at most once a day.
• Any website may fetch the files from a browser; cross-origin requests are allowed.
• Compare the sha256 in index.json with what you downloaded if you keep copies.

Python

import csv, io, json, urllib.request

BASE = "https://data.openpinsheet.com/v1/"
index = json.load(urllib.request.urlopen(BASE + "index.json"))
days = [f for f in index["files"] if f["kind"] == "day" and f["path"].endswith(".csv")]
latest = max(days, key=lambda f: f["date"])

text = urllib.request.urlopen(BASE + latest["path"]).read().decode("utf-8-sig")
lines = (line for line in io.StringIO(text) if not line.startswith("#"))
for row in csv.DictReader(lines):
    print(row["date"], row["hole"], row["lat"], row["lon"], row["source"])

JavaScript

const BASE = "https://data.openpinsheet.com/v1/";
const index = await (await fetch(BASE + "index.json")).json();
const days = index.files.filter(f => f.kind === "day" && f.path.endsWith(".geojson"));
const latest = days.reduce((a, b) => (a.date > b.date ? a : b));

const day = await (await fetch(BASE + latest.path)).json();
for (const f of day.features) {
  console.log(f.properties.hole, f.properties.source, f.geometry?.coordinates);
}

Delivering pins

Pins come in through data partners, not through these files. A golf app or course tool that wants to deliver pins writes to info@openyardage.com.

Licence

The data is under the Open Database License 1.0, the licence of OpenStreetMap data. Anyone may use, copy and share it, including commercially. Whoever builds a database from it names the source and shares that database under the same licence. The licence cannot be withdrawn.

The second line is not a courtesy: a position computed against an OpenStreetMap outline is derived from OpenStreetMap, and the ODbL asks for that credit.