Documentation

PinPlotter Documentation

Learn how to use PinPlotter to map golf courses and integrate course data into your applications.

v1.0.0

Introduction

PinPlotter is a satellite-based golf course mapping tool that combines the Golf Course API with Google Gemini AI to provide comprehensive course data. Export high-precision coordinates for GPS rangefinding applications.

App Features

Quick Map Mode

Rapidly place Tee → Fairway → Green points with single clicks. Auto-advances to next hole after placing green.

AI Auto-Trace

Drop a pin anywhere on the course. AI identifies the hole number and can generate polygon boundaries for greens, fairways, and hazards.

Area Scan

Draw a rectangle around a hole. AI analyzes the satellite imagery to identify and place tee and green markers automatically.

Rangefinder

Interactive distance measurement tool. Click anywhere on the map to see distance from tee and to green in yards.

Keyboard Shortcuts

When in Quick Map Mode, use these keys to switch feature types:

T
Tee Box
F
Fairway
G
Green
H
Hazard

Tip: Use Ctrl+Z or Cmd+Z to undo your last action.

Export Data Structure

The exported JSON file combines your mapped coordinates with official course data from the Golf Course API, including yardages, par, handicap, and course ratings for each hole.

course_mapping.json
{
  "course": "Pebble Beach Golf Links",
  "createdAt": "2024-03-20T10:00:00Z",
  "location": {
    "address": "1700 17-Mile Drive, Pebble Beach, CA",
    "city": "Pebble Beach",
    "state": "CA",
    "country": "United States"
  },
  "tee": "Blue",
  "courseRating": 74.8,
  "slopeRating": 144,
  "totalYards": 6828,
  "totalPar": 72,
  "holes": [
    {
      "number": 1,
      "par": 4,
      "yardage": 380,
      "handicap": 8,
      "features": [
        { "type": "Tee", "lat": 36.568805, "lng": -121.950624 },
        { "type": "Center", "lat": 36.567500, "lng": -121.951200 },
        { "type": "Green", "lat": 36.566123, "lng": -121.952001 }
      ],
      "areas": [
        { "type": "Green", "coordinates": [...] }
      ]
    }
    // ... Holes 2-18
  ]
}

Course-Level Fields

  • locationAddress, city, state, country
  • courseRatingUSGA course rating
  • slopeRatingUSGA slope rating (55-155)
  • totalYardsTotal course distance

Hole-Level Fields

  • parPar for this hole (3, 4, 5)
  • yardageDistance in yards from tee
  • handicapDifficulty (1=hardest)
  • features[]Mapped point coordinates

Feature Types

Tee

Starting point

Center

Fairway/landing

Green

Putting surface

Hazard

Bunker/water

Integration Guide

1. Calculating Distance (Haversine)

To measure the distance between the user's GPS position and a hole feature (e.g., "Distance to Pin"), use the Haversine formula. This accounts for the earth's curvature.

TypeScript
const toRad = (d: number) => d * Math.PI / 180;

// Returns distance in Yards
function getDistance(lat1: number, lng1: number, lat2: number, lng2: number) {
    const R = 6371e3; // Earth radius in meters
    const φ1 = toRad(lat1);
    const φ2 = toRad(lat2);
    const Δφ = toRad(lat2 - lat1);
    const Δλ = toRad(lng2 - lng1);

    const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) +
            Math.cos(φ1) * Math.cos(φ2) *
            Math.sin(Δλ/2) * Math.sin(Δλ/2);

    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
    const meters = R * c;

    return Math.round(meters * 1.09361); // Convert meters to yards
}

2. Heads-Up Navigation (Bearing)

To rotate the map so the Green is always at the top of the screen, calculate the initial bearing from the user to the Green.

TypeScript
const toDeg = (r: number) => r * 180 / Math.PI;

function getBearing(startLat: number, startLng: number, destLat: number, destLng: number) {
    const startLatRad = toRad(startLat);
    const destLatRad = toRad(destLat);
    const destLngRad = toRad(destLng);
    const startLngRad = toRad(startLng);

    const y = Math.sin(destLngRad - startLngRad) * Math.cos(destLatRad);
    const x = Math.cos(startLatRad) * Math.sin(destLatRad) -
            Math.sin(startLatRad) * Math.cos(destLatRad) * Math.cos(destLngRad - startLngRad);

    let brng = Math.atan2(y, x);
    return (toDeg(brng) + 360) % 360; // Returns 0-360 degrees
}

// Usage: rotate map container
const rotation = -getBearing(userLat, userLng, greenLat, greenLng);

Data Sources

PinPlotter combines two data sources to provide comprehensive golf course information:

Golf Course API

Provides official course data including hole-by-hole yardages, par, handicap ratings, course/slope ratings, and multiple tee options.

GET /v1/search?search_query={term}
GET /v1/courses/{id}

Google Gemini AI

Uses Google Search and Maps grounding to find courses not in the API database, identify hole locations, and generate feature boundaries.

AI Course search with geolocation
AI Hole identification from coordinates
AI Polygon boundary generation

Looking for the API?

If you're a developer looking to integrate PinPlotter course data into your application, check out our API documentation for endpoint references and code examples.

View API Documentation

Ready to Start Mapping?

Create your free account and start mapping golf courses in minutes.

Get Started FreeContact Support→