Golf Course
Maps.

Tile-first course maps

Map data shaped for map tools.

Golf Course Maps preserves a fixed, north-up Web Mercator coordinate system across Map Tiles, PMTiles archives, and Static Images. It fits interactive GPS products, course explorers, operations tools, and other interfaces where your application owns the viewport.

Maps and Graphics share measured course geometry and cartographic foundations, but their output contracts stay separate. Golf Course Graphics fits and rotates a hole, green, or course into a configurable finished composition.

Delivery surfaces

Plan, tile, bound, or package.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/maps/tiles?zoom=17&tileSize=512" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://caddie100.com/api/v1/courses/COURSE_ID/maps/tiles/17/35275/49613?tileSize=512&revision=COURSE_REVISION&mapRevision=MAP_REVISION" \
  -H "x-api-key: YOUR_API_KEY" \
  --output course-17-35275-49613.webp

Keys, quotas, and revisions

An authorization-safe revision contract.

Use an organization credential with the course-maps:read scope and send it through x-api-key or Authorization: Bearer …. Successful responses report X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; an exhausted window returns 429 with Retry-After. Licensed organization traffic uses an atomic Supabase rate window shared by every application instance. Environment-configured bootstrap keys retain only a process-local fallback and should be replaced by organization credentials for partner integrations.

The plan returns both a full SHA-256 course revision and a rendered-map revision, and includes both in generated URLs. A matching revision guarantees that the requested course data is still current. A matching mapRevision also pins the Overture context and renderer revision that affect pixels. A stale value receives 409 with the current revision headers. Authenticated responses use Cache-Control: private, no-store so a browser or shared CDN cannot serve licensed content after a key is revoked. Partners may cache rendered artifacts behind their own authenticated boundary using the map revision as the cache key.

MapLibre XYZ example

Use the returned template as a raster source.

Read the plan first. Fit the initial viewport to geographicBounds, use coverageBounds as the available padded extent, and retain the returned course and map revisions in every tile URL. MapLibre's transformRequest keeps the key in a request header instead of a query string.

Tile plans and tile requests default to lossless WebP. Add format=png to the plan or tile URL only when a client requires PNG.

const apiOrigin = "https://caddie100.com";
const apiKey = "YOUR_API_KEY";
const courseId = "COURSE_ID";
const revision = "COURSE_REVISION";
const mapRevision = "MAP_REVISION";

const map = new maplibregl.Map({
  container: "map",
  transformRequest: (url) => url.startsWith(apiOrigin)
    ? { url, headers: { "x-api-key": apiKey } }
    : { url },
  style: {
    version: 8,
    sources: {
      "caddie100-course": {
        type: "raster",
        tiles: [
          `${apiOrigin}/api/v1/courses/${courseId}/maps/tiles/{z}/{x}/{y}?tileSize=512&revision=${encodeURIComponent(revision)}&mapRevision=${encodeURIComponent(mapRevision)}`
        ],
        tileSize: 512,
        minzoom: 15,
        maxzoom: 20
      }
    },
    layers: [{ id: "caddie100-course", type: "raster", source: "caddie100-course" }]
  }
});

The interactive Maps Explorer is available in the private employee workspace.

One custom image

Bounding box + zoom → PNG.

Provide bbox=west,south,east,north and an integer zoom from 0 through 22. The requested box must stay within the course's padded coverage and may span at most 16 × 16 source tiles. The service snaps outward to whole Web Mercator pixels, brands the finished image after its final crop, then reports the exact resolved box and natural output size in response headers. Source XYZ tiles remain unbranded.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/maps/static?bbox=-83.110736,39.987982,-83.092498,39.997394&zoom=17&revision=COURSE_REVISION&mapRevision=MAP_REVISION" \
  -H "x-api-key: YOUR_API_KEY" \
  --output course-static.png

The Static Map Playground is available in the private employee workspace.

PMTiles delivery boundary

Archive serving is ready for populated courses.

The archive endpoint supports GET, HEAD, ETags, conditional requests, and single HTTP byte ranges without reading a complete archive into memory. A missing archive returns 404; the tile-plan response also reports archive.available so clients can choose XYZ fallback before opening it.

curl "https://caddie100.com/api/v1/courses/COURSE_ID/maps/archive.pmtiles?mapRevision=MAP_REVISION" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Range: bytes=0-16383" \
  --output archive-header.bin