# Ballistics Concepts

Everything Connect takes and returns is in SI units (meters, kilograms,
seconds, kelvins, pascals, radians, newtons, joules), except a spine
rating. A quantity's name ends in its unit, spelled out: `rangeMeters`,
`speedMetersPerSecond`, `massKilograms`, `drawWeightNewtons`. We don't
convert for you: convert at your boundary. Draw weight is a force, so it's
in newtons.

These are the factors we use, each exact:

| From | To SI | Factor |
|---|---|---|
| pound-force (lbf) | newtons | 1 lbf = 4.4482216152605 N (0.45359237 kg × 9.80665 m/s²) |
| grain (gr) | kilograms | 1 gr = 0.00006479891 kg (0.45359237 kg ÷ 7000) |
| inch (in) | meters | 1 in = 0.0254 m |
| yard (yd) | meters | 1 yd = 0.9144 m |
| feet per second (fps) | meters per second | 1 fps = 0.3048 m/s |
| degrees Fahrenheit (°F) | kelvins | K = (°F + 459.67) × 5/9 |
| degrees Celsius (°C) | kelvins | K = °C + 273.15 |

Bounds are exact, so don't round a converted value: send it at full
precision. A value at a bound, such as a 100 lbf draw weight
(444.82216152605 N), passes as converted, but rounded it can land just
outside the bound and get a `400`.

The PCA Drag Index (`dragIndex`) carries no unit. A spine rating
(`recommendedSpine` and the other `...Spine` fields) is in thousandths of
an inch of static deflection, so 300 means 0.300 in.

## Build descriptions

Every `compute:analyze` route takes a `model`: `massKilograms` (the
arrow's total mass, point included), `dragIndex` (see [Choosing a PCA Drag
Index™](/documentation/developers/drag-index/)) and
`launchSpeedMetersPerSecond`. You need real numbers for the build you're
asking about, from one of two places:

- **A chronograph reading,** used directly as
  `launchSpeedMetersPerSecond`.
- **The bow's specs,** through `build/launch-speed`, which estimates the
  launch speed of an arrow from the bow's IBO rating or from a speed you
  measured with a known arrow.

## What launch speed means

**Launch speed is the speed at the launch station, 0.9 m along the launch
line from the start**, where a chronograph reads it. Every launch speed
Connect takes or returns is the speed there. The start is where the
arrow's flight begins, a sight height below the peep, and times count from
it.

## What each area does

The [OpenAPI document](/documentation/developers/calling-the-api/#openapi-document)
has every field, bound and example. In brief:

- **Build** (`compute:build`): `build/launch-speed` estimates the launch
  speed for each arrow mass you ask about, and `build/spine-recommendation`
  recommends a spine for a bow and arrow, with the neighbors for a shaft
  an inch shorter or longer and a draw weight 3 lbf lighter or heavier.
- **Analyze** (`compute:analyze`): for the build in `model`, at each range
  you ask about, `analyze/trajectory` gives one zeroed shot (position,
  time, speed, energy, momentum and wind drift), `analyze/impact` the
  speed and energy on arrival, `analyze/sight-clearance` the pin's
  clearance above the arrow, `analyze/wind-drift` the drift for each
  crosswind speed, and `analyze/range-forgiveness` how far off the sight
  setting can be and still hit a target of a given size. Shots are on
  level ground.
- **Air** (`compute:air`): `air/density` turns readings (a station's, a
  weather report's, or a density altitude) into
  `airDensityKilogramsPerCubicMeter`, which you pass unchanged to the
  other routes.
- **Subscription:** `connect/subscription` says whether the user can
  compute now ([Calling the
  API](/documentation/developers/calling-the-api/#subscription-check)).

A row a route can't compute (the arrow doesn't reach that range) comes
back with `null` fields, not an error, and a `null` with several possible
causes has a `…Code` field beside it saying which. Response fields are
always present: `null` means not computed. A whole request fails only on a
real error ([Errors](/documentation/developers/errors/)).
