GunSpec

Ammunition

Query individual ammunition loads, retrieve ballistic trajectory tables, calculate firearm-specific performance, and load firearms with full ballistic profiles. Essential for ballistic simulation, ammunition databases, and game development.

Auth RequiredBuilder+

Calculate Firearm Ballistics

Computes muzzle performance for a firearm using its own barrel length and a chosen ammunition load, and compares the result against the figures the catalog records for the firearm.

GET/v1/firearms/{id}/calculate

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Resource slug ID

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

  • stringrequired

    Ammunition load to fire

    Max length
    255
    Example

application/json

  • object

    Muzzle solution adjusted for this firearm barrel length, against its published figures.

  • BallisticsFirearm

    The firearm the solution was computed for. barrelLengthMm is absent when the firearm has no recorded barrel.

  • string

    URL-safe slug identifying the firearm, e.g. glock-17-gen5.

  • string

    Display name, as the maker writes it.

  • number

    Barrel length in millimetres, measured from the breech face.

  • object

    The load the calculation used.

  • string

    Slug of the ammunition load that was fired.

  • string

    Display name, as the maker writes it.

  • object

    The figures derived for the barrel length asked about, rather than the reference one.

  • number

    Muzzle velocity in metres per second, for the default load.

  • number

    Muzzle energy in joules, for the default load.

  • TerminalBallistics

    Terminal performance indices computed at the muzzle.

  • object

    The figures published for this firearm, where the catalog records them.

  • number | null

    Muzzle velocity in metres per second, for the default load.

  • number | null

    Muzzle energy in joules, for the default load.

  • object

    Computed minus source-reported. Null where no source figure exists to compare against.

  • number | null

    Remaining velocity at this distance, in metres per second.

  • number | null

    Remaining energy at this distance, in joules.

  • string | null

    Why the calculation could not be completed, or null when it succeeded.

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Requires Builder tier or higher.

Calculation uses the firearm barrel length to adjust the ammunition reference velocity using a barrel length velocity model.

Delta values show how much the calculated values differ from manufacturer-reported specifications. Small deltas indicate good model accuracy.

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Auth RequiredBuilder+

Load Firearm

Returns the full ballistic profile for a firearm chambered with a given load: muzzle velocity and energy, effective range, terminal indices, and the trajectory sampled from the muzzle out to 1000 m.

GET/v1/firearms/{id}/load

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Resource slug ID

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

  • string

    Ammunition load to chamber. Defaults to the firearm default load, then the first common load for its primary caliber.

    Max length
    255
    Example

application/json

  • object

    The response payload.

  • BallisticsFirearm

    The firearm the solution was computed for. barrelLengthMm is absent when the firearm has no recorded barrel.

  • string

    URL-safe slug identifying the firearm, e.g. glock-17-gen5.

  • string

    Display name, as the maker writes it.

  • number

    Barrel length in millimetres, measured from the breech face.

  • object

    The load the calculation used.

  • string

    Slug of the ammunition load the firearm was chambered with.

  • string

    Display name, as the maker writes it.

  • string

    Slug of the cartridge. Resolve against /v1/calibers/{id}.

  • number

    Bullet weight in grams. Divide by 0.0648 for grains.

  • string

    Bullet construction: fmj, jhp, sp, match.

  • object

    The figures derived for the barrel length asked about, rather than the reference one.

  • number

    Muzzle velocity in metres per second, for the default load.

  • number

    Muzzle energy in joules, for the default load.

  • number

    Effective range in metres against a point target.

  • TerminalBallistics

    Terminal performance indices computed at the muzzle.

  • object

    The figures published for this firearm, where the catalog records them.

  • number | null

    Muzzle velocity in metres per second, for the default load.

  • number | null

    Muzzle energy in joules, for the default load.

  • number | null

    Effective range in metres against a point target.

  • TrajectoryPoint[]

    The flight path, one row per distance step.

  • number

    Distance from the muzzle in metres.

  • number

    Remaining velocity at this distance, in metres per second.

  • number

    Remaining energy at this distance, in joules.

  • number

    Bullet drop below the line of sight at this distance, in centimetres.

  • number

    Time of flight to this distance, in seconds.

  • number

    Velocity as a multiple of the speed of sound. Below ~1.2 the projectile is transonic and destabilises.

  • number

    Momentum in kilogram-metres per second.

  • number

    Taylor Knock-Out factor at this distance.

  • number

    Energy per unit frontal area, in joules per square centimetre.

  • string | null

    Why the calculation could not be completed, or null when it succeeded.

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Requires Builder tier or higher.

When ammo_id is omitted, the endpoint auto-resolves ammunition in this order: (1) the firearm's default ammunition, (2) the most common load for the caliber.

Muzzle velocity is adjusted based on the firearm's barrel length relative to the ammunition's reference barrel.

The trajectory table covers distances from 0 to the effective range at regular intervals.

Ideal for game engines that need a ready-to-use ballistic profile for a weapon.

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Auth RequiredBuilder+

Ammunition by Caliber

Returns the specific factory loads available in a given cartridge.

GET/v1/calibers/{id}/ammunition

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Caliber slug

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

  • integerdefault1

    Page number, from 1 to 10,000

    Range
    1 – 10000
    Example
  • integerdefault20

    Items per page (max 100)

    Range
    1 – 100
    Example

application/json

  • AmmunitionLoad[]

    A specific factory ammunition load within a caliber.

  • string

    URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.

  • string

    Slug of the cartridge. Resolve against /v1/calibers/{id}.

  • string

    Display name, as the maker writes it.

  • string | null

    Military or standards designation for the load, e.g. M882.

  • string | null

    Who makes it.

  • string | null

    ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.

  • number

    Bullet weight in grams. Divide by 0.0648 for grains.

  • string

    Bullet construction: fmj, jhp, sp, match.

  • number | null

    Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.

  • number | null

    Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.

  • number

    Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.

  • number

    Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.

  • number | null

    Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.

  • integer | null

    Year it entered production or service. Null where the date is disputed or unknown.

  • integer

    1 when the load is commonly stocked.

  • string | null

    Absolute URL of the rendered bullet diagram.

  • number | null

    Decay exponent used when extrapolating velocity to a barrel length other than the reference one.

  • string | null

    Prose summary of the record, where one has been written.

  • integer

    1 when the load is a military issue round.

  • string

    When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.

  • string

    When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.

  • number

    Current page number

  • number

    Items per page

  • number

    Total matching records (Builder and above)

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Requires Builder tier or higher.

Returns all known ammunition loads for the given caliber, including military designations, commercial loads, and specialty rounds.

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Auth RequiredBuilder+

List Ammunition

Returns a paginated list of specific ammunition loads across all calibers.

GET/v1/ammunition

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • integerdefault1

    Page number, from 1 to 10,000

    Range
    1 – 10000
    Example
  • integerdefault20

    Items per page (max 100)

    Range
    1 – 100
    Example
  • string

    Filter by caliber slug

    Example
  • string

    Filter by bullet construction

    Example
  • integer

    Restrict to commonly stocked loads (1) or uncommon ones (0)

    Range
    0 – 1
    Example

application/json

  • AmmunitionLoad[]

    A specific factory ammunition load within a caliber.

  • string

    URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.

  • string

    Slug of the cartridge. Resolve against /v1/calibers/{id}.

  • string

    Display name, as the maker writes it.

  • string | null

    Military or standards designation for the load, e.g. M882.

  • string | null

    Who makes it.

  • string | null

    ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.

  • number

    Bullet weight in grams. Divide by 0.0648 for grains.

  • string

    Bullet construction: fmj, jhp, sp, match.

  • number | null

    Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.

  • number | null

    Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.

  • number

    Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.

  • number

    Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.

  • number | null

    Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.

  • integer | null

    Year it entered production or service. Null where the date is disputed or unknown.

  • integer

    1 when the load is commonly stocked.

  • string | null

    Absolute URL of the rendered bullet diagram.

  • number | null

    Decay exponent used when extrapolating velocity to a barrel length other than the reference one.

  • string | null

    Prose summary of the record, where one has been written.

  • integer

    1 when the load is a military issue round.

  • string

    When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.

  • string

    When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.

  • number

    Current page number

  • number

    Items per page

  • number

    Total matching records (Builder and above)

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Caching guide

This read answers conditional requests. Keep the ETag from a response and send it back as If-None-Match: an unchanged record returns 304 Not Modified with no body, which counts toward your per-minute rate limit but not your daily allowance.

Auth RequiredBuilder+

Get Ammunition

Returns the full specification for a single ammunition load.

GET/v1/ammunition/{id}

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Ammunition load slug

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

application/json

  • AmmunitionLoad

    A specific factory ammunition load within a caliber.

  • string

    URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.

  • string

    Slug of the cartridge. Resolve against /v1/calibers/{id}.

  • string

    Display name, as the maker writes it.

  • string | null

    Military or standards designation for the load, e.g. M882.

  • string | null

    Who makes it.

  • string | null

    ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.

  • number

    Bullet weight in grams. Divide by 0.0648 for grains.

  • string

    Bullet construction: fmj, jhp, sp, match.

  • number | null

    Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.

  • number | null

    Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.

  • number

    Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.

  • number

    Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.

  • number | null

    Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.

  • integer | null

    Year it entered production or service. Null where the date is disputed or unknown.

  • integer

    1 when the load is commonly stocked.

  • string | null

    Absolute URL of the rendered bullet diagram.

  • number | null

    Decay exponent used when extrapolating velocity to a barrel length other than the reference one.

  • string | null

    Prose summary of the record, where one has been written.

  • integer

    1 when the load is a military issue round.

  • string

    When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.

  • string

    When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Caching guide

This read answers conditional requests. Keep the ETag from a response and send it back as If-None-Match: an unchanged record returns 304 Not Modified with no body, which counts toward your per-minute rate limit but not your daily allowance.

Auth RequiredBuilder+

Ammunition Ballistics

Computes velocity, energy, and drop at the requested distances for one load, optionally adjusted for a specific barrel length.

GET/v1/ammunition/{id}/ballistics

Builder+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Ammunition load slug

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

  • number

    Barrel length to adjust muzzle velocity for

    Range
    50 – 2000
    Example
  • string

    Comma-separated distances in metres

    Example

application/json

  • object

    The response payload.

  • object

    The load the figures are for.

  • string

    Slug of the load the table was computed for.

  • string

    Display name, as the maker writes it.

  • string

    Slug of the cartridge. Resolve against /v1/calibers/{id}.

  • number | null

    Barrel length in millimetres, measured from the breech face.

  • number

    Muzzle velocity in metres per second, for the default load.

  • number

    Muzzle energy in joules, for the default load.

  • number

    Effective range in metres against a point target.

  • TerminalBallistics

    Terminal performance indices computed at the muzzle.

  • number

    Taylor Knock-Out factor.

  • number

    Momentum in kilogram-metres per second.

  • number

    Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.

  • number

    Hatcher Relative Stopping Power.

  • number

    Energy per unit frontal area, in joules per square centimetre.

  • TrajectoryPoint[]

    The solution sampled at each requested distance.

  • number

    Distance from the muzzle in metres.

  • number

    Remaining velocity at this distance, in metres per second.

  • number

    Remaining energy at this distance, in joules.

  • number

    Bullet drop below the line of sight at this distance, in centimetres.

  • number

    Time of flight to this distance, in seconds.

  • number

    Velocity as a multiple of the speed of sound. Below ~1.2 the projectile is transonic and destabilises.

  • number

    Momentum in kilogram-metres per second.

  • number

    Taylor Knock-Out factor at this distance.

  • number

    Energy per unit frontal area, in joules per square centimetre.

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Requires Builder tier or higher.

If barrel_length_mm is provided, muzzle velocity is adjusted based on barrel length relative to the reference barrel.

Default distances are 0, 100, 200, 300, and 500 meters. Maximum 20 distance points per request.

Trajectory calculations use a G1 drag model with standard atmospheric conditions (15C, 1013 hPa, sea level).

Full rate limits

Minimum tier
Builder+
Monthly quota
25,000/mo
Rate limit
60/min
Daily cap
2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

Optional AuthExplorer+

Bullet SVG Image

Returns a scale SVG cross-section of the bullet, generated from its recorded dimensions.

GET/v1/ammunition/{id}/bullet.svg

Explorer+

  • stringheader

    Optional. Without a key this endpoint answers under the public policy; a key raises your limits and unlocks plan-gated fields. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Ammunition load slug

    Accepts
    a lowercase slug: letters, digits and hyphens
    Example

image/svg+xml

  • header

    image/svg+xml

  • header

    public, max-age=86400, s-maxage=604800 (cached for 24h client / 7 days CDN)

  • 400VALIDATION_ERRORValidation error
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

No authentication required. This is a public image endpoint.

Aggressively cached: 24-hour client cache, 7-day CDN cache.

Every ammunition list/detail response includes a bulletSvgUrl field with the full URL to this endpoint.

Bullet profiles: FMJ (rounded ogive), JHP (hollow cavity), AP (steel penetrator tip), SP (exposed lead tip), OTM (match-grade open tip).

SVG proportions are derived from the caliber's bullet_diameter_mm for realistic scaling.

Ideal for ammunition catalogs, e-commerce product pages, game UIs, and educational material.

Full rate limits

Minimum tier
Explorer+
Monthly quota
200/mo
Rate limit
10/min
Daily cap
50

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.