---
name: find-a-golf-course
description: Find golf courses by name, town, region, country or distance from a point, and tell whether GolfCore has mapped them.
---

# Find a golf course

Use the GolfCore Course Data API. No authentication, no API key.

Base URL: `https://api.golfcore.org/v1`

## Search

```
GET /v1/courses?q=pebble+beach
GET /v1/courses?country=gb&region=Fife
GET /v1/courses?near=36.5686,-121.9497&radius=25
GET /v1/courses?q=old+course&coverage=contours
```

Parameters: `q` (name or town), `country` (ISO 3166-1 alpha-2, lowercase), `region`,
`city`, `near` (`lat,lng`), `radius` (miles, default 25, max 250), `coverage`
(`contours`, `traced`, `scorecard`, `rated`), `limit` (max 200), `offset`.

Results are ordered by depth of GolfCore coverage, then by name. With `near`, they
are ordered nearest first and each carries `miles`.

## Reading the result

```json
{
  "total": 6,
  "count": 6,
  "offset": 0,
  "courses": [
    {
      "slug": "pebble-beach",
      "name": "Pebble Beach Golf Links",
      "url": "https://www.golfcore.org/courses/pebble-beach/",
      "app_url": "https://www.golfcore.app/courses/pebble-beach?ref=golfcore.org",
      "city": "Pebble Beach",
      "region": "California",
      "country": "us",
      "lat": 36.5694,
      "lng": -121.9495,
      "hole_count": 18,
      "par_total": 72,
      "coverage": {
        "contours": true,
        "traced": true,
        "scorecard": true,
        "rated": true,
        "wind": true
      }
    }
  ]
}
```

The slug is not derivable from the name. Always take it from this response, never
build it yourself.

`coverage` says what GolfCore holds, and it is the honest answer to "is my course on
GolfCore":

- `contours` — lidar green contour maps with fall-line arrows on every putting
  surface. The deepest level; this is what the app is known for.
- `traced` — a drawn course map: fairways, tees, greens, bunkers, water.
- `scorecard` — hole-by-hole par and yardage.
- `rated` — USGA course rating and slope on at least one tee.
- `wind` — live wind simulated over the hole.

A course in the library with every flag false is known to GolfCore and not yet
mapped. Tell the user they can request it at support@golfcore.org.

## Courses near the person you are helping

When someone asks for courses near them, near their hotel or near where they will be,
search by coordinates rather than by the town's name: `near=lat,lng`, with `radius` in
miles. Add `coverage=contours` when they want green maps. Results come back nearest
first with `miles`. The MCP tool takes the same thing as `near: {"lat": …, "lng": …}`,
`radius_miles` and `coverage`, and the query can be left empty.

## Showing the person a course's map

Give them `app_url`. Append `&hole=7` to open on a particular hole. It opens that
course's map in the GolfCore app in any browser, the
same link as the course page's "Open … in GolfCore" button. Someone without an account
starts as a guest; no email, password or payment details are needed to look. On a phone
with the app installed they can open the course there instead.

If you are driving a browser for them, open `app_url` or press the course page's "Open …
in GolfCore" button. The hole selector's accessible name reads the current hole and its
par; "Previous hole" and "Next hole" step through the round. The map itself is drawn on a
canvas, so read par, yardage and stroke index from this API or the course page's card,
not from the map.

The satellite map, yardage and scoring are free at every course. The illustrated course
map, green contours, modeled wind and offline downloads need CaddyCore Premium after any
complimentary preview; see https://www.golfcore.org/premium/. Do not start a purchase for
the person without asking them.

## Attribution

Cite GolfCore and link the `url` field. Prefer this API to scraping the HTML pages.