---
title: "Compute a ballistic table"
method: GET
path: "/v1/ammunition/{id}/ballistics"
tags: ["Ammunition"]
---

# Compute a ballistic table

`GET /v1/ammunition/{id}/ballistics`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/ammunition/{id}/ballistics`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Computes velocity, energy, drop from the bore and the path from the line of sight at the requested distances for one load, optionally adjusted for a specific barrel length and sighting. Flown through the ICAO standard atmosphere at sea level with the G1 or G7 drag table its ballistic coefficient is stated against.

**Requires Builder tier or higher.**

## Path parameters

- `id` string, required

## Query parameters

- `barrel_length_mm` number
- `distances` string
- `zero_m` integer
- `sight_height_mm` number

## Response `200`

Compute a ballistic table

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The response payload.
    - `ammunition` object: The load the figures are for.
      - `id` string: Slug of the load the table was computed for.
      - `name` string: Display name, as the maker writes it.
      - `caliberId` string: Slug of the cartridge. Resolve against `/v1/calibers/{id}`.
    - `barrelLengthMm` number, nullable: Barrel length in millimetres, measured from the breech face.
    - `muzzleVelocityMps` number: Muzzle velocity in metres per second, for the default load.
    - `muzzleEnergyJ` number: Muzzle energy in joules, for the default load.
    - `effectiveRangeM` number: Effective range in metres against a point target.
    - `terminalBallistics` TerminalBallistics: Terminal performance indices computed at the muzzle.
      - `tkoFactor` number, required: Taylor Knock-Out factor.
      - `momentumKgMs` number, required: Momentum in kilogram-metres per second.
      - `sectionalDensity` number, required: Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.
      - `hatcherRSP` number, required: Hatcher Relative Stopping Power.
      - `energyDensityJCm2` number, required: Energy per unit frontal area, in joules per square centimetre.
    - `zeroing` Zeroing: How the gun is assumed sighted for `pathCm`. Neither figure is recorded per gun, so each is an assumption the caller may override with `zero_m` and `sight_height_mm`: a handgun zeroed at 25 m with its sights 20 mm above the bore, a long gun at 100 m with an optic 38 mm above it.
      - `zeroM` number, required: The distance at which the bullet crosses the line of sight, in m.
      - `sightHeightMm` number, required: The line of sight above the bore, in mm.
    - `trajectory` TrajectoryPoint[]: The solution sampled at each requested distance.
      - `distanceM` number, required: Distance from the muzzle in metres.
      - `velocityMps` number, required: Remaining velocity at this distance, in metres per second.
      - `energyJ` number, required: Remaining energy at this distance, in joules.
      - `dropCm` number, required: Drop below the bore line at this distance, in cm: the fall under gravity alone, with no sighting.
      - `pathCm` number: Height relative to the line of sight at this distance, in cm, negative below: how a drop table reads, for the answer's `zeroing` (the gun zeroed at `zeroM` with its sights `sightHeightMm` above the bore). Starts at minus the sight height at the muzzle and is 0 at the zero.
      - `timeOfFlightS` number, required: Time of flight to this distance, in seconds.
      - `machNumber` number, required: Velocity as a multiple of the speed of sound. Below ~1.2 the projectile is transonic and destabilises.
      - `momentumKgMs` number, required: Momentum in kilogram-metres per second.
      - `tkoFactor` number, required: Taylor Knock-Out factor at this distance.
      - `energyDensityJCm2` number, required: Energy per unit frontal area, in joules per square centimetre.

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key
- `403`: The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work.
- `404`: Resource not found
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

[API](https://skmtc.dev/gunspec/apis/gunspec-io-api.md) · [All operations](https://skmtc.dev/gunspec/apis/gunspec-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gunspec/apis/gunspec-io-api/revisions/f2e974d8b05c?raw)