GunSpec

Ammunition

Resource class for interacting with the GunSpec Ammunition API. Wraps all /v1/ammunition endpoints. Instantiated internally by the GunSpec client and exposed as client.ammunition.

Auth RequiredBuilder+

client.ammunition.list()

List ammunition with optional filters and pagination.

list(params?: ListAmmunitionParams): Promise<PaginatedResponse<Ammunition>>
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+

client.ammunition.listAutoPaging()

Auto-paginate through all ammunition matching the given filters. Returns an async iterator that fetches pages on demand, yielding individual Ammunition objects.

listAutoPaging(params?: ListAmmunitionParams): AsyncIterableIterator<Ammunition>
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

Returns an async iterator: it fetches each page as you consume it, so a loop over the whole collection is one statement and one page in memory at a time.

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+

client.ammunition.get()

Get a single ammunition load by its slug or ID.

get(id: string): Promise<APIResponse<Ammunition>>
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.

Optional AuthExplorer+

client.ammunition.getBulletSvg()

Get a bullet profile SVG image for an ammunition load. Returns a raw SVG string representing the bullet projectile shape. This endpoint returns raw SVG content, not the standard JSON envelope.

getBulletSvg(id: string): Promise<string>
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

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

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.

Auth RequiredBuilder+

client.ammunition.ballistics()

Get ballistic trajectory data for an ammunition load.

ballistics(id: string, params?: AmmunitionBallisticsParams): Promise<APIResponse<BallisticProfile>>
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

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.