Documentation

DiscGolfAPI Developer Documentation: REST Endpoints & MCP Guide

Use DiscGolfAPI to fetch disc golf course data for maps, directories, apps, tools, and research. Public endpoints do not require an API key.

Base URL: https://io.discgolfapi.com/v1

GET Quick start

Fetch five courses from Great Britain.

Sample request

fetch("https://io.discgolfapi.com/v1/courses?country=GB&limit=5")
  .then(response => response.json())
  .then(data => console.log(data));

Sample response excerpt

{
  "count": 5,
  "total": 30,
  "offset": 0,
  "courses": [
    {
      "id": "crs_ackers_adventure",
      "name": "Ackers Adventure",
      "country_code": "GB",
      "region_code": "ENG",
      "holes": null,
      "confidence_score": 0.65,
      "verification_strength": "medium"
    }
  ]
}

Endpoints

Method	Endpoint	Use
GET	`/courses`	List courses, optionally filtered by country, region, limit, or offset.
GET	`/courses/{id}`	Fetch a single course by public ID. The response uses the same metadata envelope and `courses` array as the list endpoint, with `count` set to `1`.
GET	`/countries`	List countries represented in the API.
GET	`/regions`	List regions represented in the API.
GET	`/updates/recent`	Review recent data updates when available.
POST	`/report`	Report missing, outdated, or incorrect course data. Requires `course_id`, `type`, and `message`.

Model Context Protocol (MCP) for AI Assistants

DiscGolfAPI provides a free, public, read-only remote Model Context Protocol (MCP) server over Streamable HTTP. AI assistants (Claude Desktop, Cursor, ChatGPT, Windsurf, etc.) can directly query course records and proximity tools without an API key or account.

Tool Name	Parameters	Description
`search_courses`	`query`, `country`, `region`, `is_free`, `is_18_holes`, `limit`, `offset`	Search disc golf courses worldwide by name, city, country, region, hole count, or amenities. Returns a bounded array of up to 25 courses with relevance scoring.
`find_courses_near`	`latitude`, `longitude`, `radius_km`, `limit`	Find disc golf courses within a specified radius (km) of latitude/longitude coordinates, sorted ascending by distance.
`get_course`	`id`	Retrieve complete verified course characteristics, layout details, tee types, basket types, and coordinates by stable ID or alias slug.
`get_recent_updates`	`limit`, `since`	Discover recently added or modified courses across the global catalog sorted newest-first.

Claude Desktop Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "discgolfapi": {
      "url": "https://io.discgolfapi.com/mcp"
    }
  }
}

Endpoint: https://io.discgolfapi.com/mcp • Protocol: MCP 2026-07-28 (Streamable HTTP) • Auth: None (Free public read-only)

Machine-readable files

Developer agents and API clients can use the public discovery files below.

/openapi.json for the OpenAPI 3.1 API contract.
/apis.json for the API discovery index.
/llms.txt for a concise LLM and developer guide.
/robots.txt for crawler guidance.

Filtering and limits

The course list can be filtered and paginated for common directory and map workflows. Course, country, region, and update responses include shared metadata such as schema_version, generated_at, attribution, licence, terms, warranty, and meta.publish_version.

country=GB filters courses by country code.
region=ENG filters courses by region code where supported.
limit=5 limits the number of returned records. It must be a positive integer.
offset=10 skips records before returning the current page. It must be zero or a positive integer.

When country, region, limit, or offset is used, the response includes total, count, offset, and courses. total is the count before pagination and count is the returned page size.

Paginated request

GET https://io.discgolfapi.com/v1/courses?country=GB&limit=5&offset=10

Report payloads

POST /report accepts JSON reports for course records. Required fields are course_id, type, and message. Valid report types are closed, moved, wrong_data, missing_data, and other. Accepted reports return 201 with ok and a report id.

Report request

POST https://io.discgolfapi.com/v1/report
Content-Type: application/json

{
  "course_id": "crs_a6_discgolfpark",
  "type": "wrong_data",
  "message": "The course has recently changed from 9 holes to 18 holes."
}

Course object

Course records are designed for structured display rather than reviews or rankings.

Field	Meaning
`id`	Stable public course identifier.
`name`	Course name.
`country_code`	Country code for filtering and grouping.
`region_code`	Region code where available.
`holes`	Known hole count where available.
`confidence_score`	Numeric confidence signal for the record.
`verification_strength`	Human-readable verification bucket such as `strong`, `medium`, or `low`.

Data completeness

DiscGolfAPI publishes unknown values plainly instead of guessing. Some consumer-facing fields are still sparse while the dataset is being improved.

Current known gaps: hole count data is sparse across the full dataset, so many course records currently return holes: null. Treat this as unknown, not zero. access_model and condition_status are also mostly unknown at present.

For production interfaces, show fallbacks such as “hole count unknown” and avoid filtering out courses solely because these fields are missing. Coordinate, country, region, confidence, and verification fields are the better default signals for initial directory and map experiences.

Full schema reference

The schema page includes a complete course object, field definitions, status values, layout fields, and guidance for handling unknown values.

View schema

Confidence and verification

DiscGolfAPI makes confidence explicit rather than implied. Confidence fields help you decide how to display, review, or qualify a record in your own product.

Use high-confidence records directly in maps and directories.
Use medium-confidence records with normal display and sensible fallbacks.
Review low-confidence or incomplete records before relying on them for critical decisions.

Errors

Clients should handle standard HTTP error states and show a calm fallback to users.

400 for invalid filters or request data.
400 when limit is not a positive integer or offset is negative.
400 when a report is missing course_id, a valid type, or a message of at least 3 characters.
404 when a course or endpoint is not found.
429 if automated traffic is excessive.
500 for temporary server errors.

Fair use

Public endpoints are intended for apps, websites, maps, directories, and research. Cache responses where practical, avoid unnecessary repeated requests, and do not mirror or republish the full dataset as a competing service.

Attribution

If you use DiscGolfAPI data, include visible attribution near the data.

“Course data supplied by DiscGolfAPI.”

See the full licence and terms of use for details.

Need help using the API?

Send API questions, documentation feedback, or data correction notes.