---
title: "Compare the point-blank and supersonic range of each firearm"
method: GET
path: "/v1/firearms/point-blank"
tags: ["Firearm Analysis"]
---

# Compare the point-blank and supersonic range of each firearm

`GET /v1/firearms/point-blank`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/firearms/point-blank`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns, for each of up to 5 firearms firing a load, its maximum point-blank range: the furthest distance at which the bullet stays within half the target's diameter of the line of sight all the way from the muzzle, at the zero that makes that distance longest. With it come that zero (the far zero), the near zero where the bullet first rises through the line of sight, the peak, the time of flight and the velocity at the range, and the supersonic range.

The trajectory is the one `/v1/firearms/{id}/load` flies: the same load, the firearm's own barrel and the same solver, in the ICAO standard atmosphere at sea level (15 °C, 101.325 kPa). It is flown at every metre, so every distance is to the metre. With no `ammo_id`, each firearm fires the load its ballistic profile uses; the sights sit at the height that profile assumes for the firearm's category unless `sight_height_mm` says otherwise.

Every input has a default, and `target.defaulted` names the ones the answer assumed. Each trajectory is flown to 2500 m; a range that reaches it is at least that far, and the answer says so.

**Requires Builder tier or higher.**

## Query parameters

- `ids` string, required
- `ammo_id` string
- `target_mm` number
- `sight_height_mm` number

## Headers

- `If-None-Match` string

## Response `200`

Compare the point-blank and supersonic range of each firearm

- 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.
    - `method` object: The method behind every figure in the answer.
      - `id` string: The method the figures were computed with.
      - `name` string: The method by name.
      - `equation` string: The geometry as written, with its units, so the figures can be reproduced.
      - `citations` object[]: Where the atmosphere the trajectory is flown through is defined.
        - `authors` string: Authors or the issuing body.
        - `year` integer: Year of publication or revision.
        - `title` string: Title.
        - `journal` string: Where it is published: journal, publisher or document number.
        - `doi` string, nullable: Digital Object Identifier, where it has one.
        - `url` string, nullable: A page it can be read at, where it has no DOI.
      - `resolutionM` integer: The step, in metres, every distance is found to.
      - `maxRangeM` integer: How far each trajectory is flown, in metres.
    - `atmosphere` object: The atmosphere, as the trajectory solver uses it.
      - `name` string: The air every trajectory is flown through.
      - `temperatureC` number: Air temperature in °C.
      - `pressureKpa` number: Air pressure in kPa.
      - `airDensityKgM3` number: Air density in kg/m³.
      - `speedOfSoundMps` number: Speed of sound in m/s: the line the supersonic range is drawn at.
    - `target` object: The target every firearm was answered for.
      - `diameterMm` number: Target diameter in mm.
      - `radiusMm` number: Half of it: how far above or below the line of sight the bullet may be.
      - `defaulted` string[]: The query parameters not sent, answered from their defaults.
    - `results` object[]: One result per firearm, in the order their ids were given.
      - `firearm` object: The firearm this result is for.
        - `id` string: Firearm slug.
        - `name` string: Firearm name.
        - `categoryId` string: Category slug.
        - `barrelLengthMm` number, nullable: Barrel length in mm, from the record.
      - `ammunition` object, nullable: The load fired: the one named by `ammo_id`, or the one `/v1/firearms/{id}/load` fires this firearm with. Null when there is none.
        - `id` string: Ammunition slug.
        - `name` string: Load name.
        - `caliberId` string: Cartridge slug.
        - `bulletWeightG` number: Bullet mass in grams, from the load record.
      - `muzzleVelocityMps` number, nullable: The load's muzzle velocity from this firearm's barrel, in m/s.
      - `sight` object: The sights the path is measured from.
        - `heightMm` number: Sight height above the bore in mm.
        - `source` 'query' | 'category': Whether it was given in the query or assumed for the category.
      - `pointBlank` object, nullable: The maximum point-blank range. Null when it could not be computed; `error` says why.
        - `rangeM` integer: Maximum point-blank range in metres.
        - `nearZeroM` integer: Where the bullet first rises through the line of sight, in metres.
        - `farZeroM` integer: Where it falls back through it: the zero that gives this range, in metres.
        - `peakM` integer: Where it is highest above the line of sight, in metres.
        - `peakHeightMm` number: How high it is there, in mm.
        - `boreAngleMrad` number: The bore's angle above the line of sight, in milliradians.
        - `timeOfFlightS` number: Time of flight to the range, in seconds.
        - `velocityMps` number: Velocity at the range, in m/s.
      - `supersonic` object, nullable: How far the bullet stays supersonic. Null when no trajectory was flown.
        - `rangeM` integer: The furthest distance flown faster than sound, in metres. 0 for a load subsonic at the muzzle.
        - `timeOfFlightS` number: Time of flight to it, in seconds.
        - `beyondProfile` boolean: True when the bullet is still supersonic where the trajectory ends, so the range is at least `rangeM`.
      - `delta` object, nullable: Against the option with the longest point-blank range. Null on that option, on a lone firearm, and where no range was computed.
        - `rangeM` integer: Metres of point-blank range against the longest (negative: shorter).
        - `farZeroM` integer: Metres of far zero against it.
      - `warnings` string[]: What an answer needs qualifying with.
      - `error` string, nullable: Why this firearm could not be answered. Null when it was.

## Other responses

- `304`: Your copy is current. No body is sent, and this response does not count toward the daily request allowance.
- `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)