GunSpec

Firearms

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

Auth RequiredBuilder+

Compare up to 5 firearms side by side.

compare(params: CompareFirearmsParams): Promise<APIResponse<FirearmComparison>>
GET/v1/firearms/compare

  • stringheaderrequired

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

  • stringrequired

    Comma-separated firearm slugs, maximum 5

    Example

  • object

    The response payload.

  • FirearmWithRelations[]

    The compared firearms, in the order their ids were given.

  • integer

    Integer flag, 1 when a 3D model is on file. Stored as the database holds it rather than as a boolean.

  • string | null

    Line-art silhouette, or null where none has been drawn.

  • string | null

    GLB model, or null where none is on file.

  • string | null

    The ammunition load ballistics figures are quoted against, where one is nominated.

  • number | null

    Muzzle velocity in metres per second exactly as the source stated it, kept beside our own figure so a reader can see what was quoted and what was derived.

  • number | null

    Muzzle energy in joules exactly as the source stated it.

  • number | null

    Effective range in metres exactly as the source stated it.

  • number | null

    Maximum range in metres exactly as the source stated it.

  • string | null

    Where the ballistics figures came from, named in prose.

  • string | null

    URL of the ballistics source, where it is a page rather than a book.

  • string

    URL-safe slug identifying the firearm, e.g. glock-17-gen5. Stable: it is what a mirror keys on.

  • string

    Display name, as the maker writes it.

  • object[]

    Per-field differences across the compared firearms, one entry per numeric field.

  • string

    Which column the row is about, named as the database names it.

  • number | null[]

    This field on each compared firearm, in the order the ids were given. Null where that record does not carry the field.

  • number | null

    Lowest value across the compared firearms. Null when fewer than two of them carry the field.

  • number | null

    Highest value across the compared firearms. Null when fewer than two of them carry the field.

  • number | null

    Spread from the lowest value, as a percentage of it: (max - min) / min * 100, rounded to two places. Null when the minimum is zero or fewer than two records carry the field.

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

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.

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.