# Swing data: instructions for an AI assistant

The person who gave you this has golf swings analyzed at https://swing.basmith.net and a
read-only API key for them (it starts with `swk_`). Use it to fetch their swings and help them
understand and improve their swing.

## Calling the API

Send the key on every request: `Authorization: Bearer swk_...`. Everything is a GET; the key
can't upload, share or delete. It sees exactly what its owner sees: their own swings, swings
friends have shared with them, and tour-pro reference swings (owner "Reference").

    curl -H "Authorization: Bearer $KEY" https://swing.basmith.net/api/swings

- `GET /api/me`: who the key belongs to (`name`, `email`, `height_in`).
- `GET /api/swings`: every finished swing the key can see, newest first. **Usually all you need.**
  Each has `id`, `session_id`, `owner`, `mine` (true = the key owner's own), `captured_at` (UTC),
  `view`, `metrics` and `ball`.
- `GET /api/sessions`, `GET /api/sessions/{id}`: swings grouped by practice session (one
  range or simulator visit).
- `GET /api/swings/{id}`: one swing.
- `GET /media/swings/{id}/keyframes.png`: address / top / impact / finish side by side with the
  skeleton drawn on. Look at it to sanity-check a number.
- `GET /media/swings/{id}/data.json`: per-frame series (`series.<measure>[frame]`) and phase
  frames, for charting a measure through the swing.
- `GET /media/swings/{id}/video.mp4`: the clip.

## metrics fields

- `view`: `dtl` (down-the-line, camera behind the golfer looking at the target) or `fo` (face-on).
- `spine_angle_deg.{address,top,impact}` (dtl): forward tilt of the spine from vertical.
  **Key number:** `address - top` is how much posture is lost in the backswing ("standing up").
  Tour reference swings lose 1 to 3 degrees; more than about 6 is a real fault.
- `hips_toward_ball_at_impact_in` (dtl): + = hips moved toward the ball (early extension).
  Within about ±1 in is good; +3 in or more is a clear fault.
- `head_toward_ball_at_impact_in`, `head_drop_at_impact_in`: head movement, in inches.
- face-on only: `head_shift_*_in`, `hip_shift_*_in` (+ = toward the target).
- `backswing_s`, `downswing_s`, `tempo_ratio`: rough, since positions come from the body, not
  the club. Don't coach from them.
- `golfer_height_in`: inches are scaled from this; angles don't depend on it.

## ball (launch monitor numbers, when a swing has them; otherwise null)

`carry_yd`, `total_yd`, `ball_speed_mph`, `club_speed_mph`, `smash`, `apex_ft`, `spin_rpm`,
`spin_axis_deg`, and sometimes `face_angle_deg`, `club_path_deg`. Negative = left, positive =
right. `source` says where they came from (some were read off a simulator screen by hand).

## Limits

- Top and impact can read a frame or two early.
- Compare a golfer's swings with each other, or with the Reference swings, rather than with
  published tour numbers measured another way.
- A swing whose address spine angle is far off the golfer's others probably mis-read address;
  check its keyframes before trusting it.