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+

client.firearms.resolve()

Resolve a free-text name to a firearm id. Builder.

resolve(q: string): Promise<APIResponse<ResolveResult>>
GET/v1/firearms/resolve

Builder+

  • stringheaderrequired

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

  • stringrequired

    The name to resolve, up to 200 characters.

    Max length
    200
    Example

application/json

  • object

    What one query resolved to.

  • string

    The query this result answers, echoed back so a batch response can be matched to its request.

  • string

    One of resolved (exactly one record), ambiguous (several equally good, none chosen) or not_found.

  • string | null

    The resolved catalog id. Null on ambiguous and not_found, since an ambiguous query is deliberately not decided for you.

  • string | null

    How the resolution was made, or null when nothing resolved. Never fuzzy: a suggestion is not a resolution.

  • number

    Confidence in the resolution, 0 to 1. Derived from how much of the query a catalogued spelling accounted for and how strong that spelling is as evidence.

  • string[]

    The words of the query a catalogued spelling accounted for.

  • string[]

    The words it did not. Reported rather than guessed at: a variant we do not hold appears here instead of being silently dropped.

  • object[]

    Other records this query could mean, best first. On ambiguous these are the tied candidates and choosing between them is yours.

  • string

    The catalog id of this candidate.

  • string

    The catalogued name of this candidate.

  • string | null

    The maker, or null where the record has none.

  • string

    How this candidate was matched. One of slug, name, alternate, shorthand, base (the name with its maker removed), family (the model designation with its trailing descriptor removed, e.g. M4 from M4 Carbine) or fuzzy.

  • string | null

    The catalogued spelling that matched, or null for a fuzzy suggestion.

  • number

    Confidence in this candidate, 0 to 1. Always 0 for a fuzzy suggestion, which is offered rather than scored.

  • 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.