Firearms

Resolve a name to one firearm

Turns a name as somebody actually writes it ("G19 gen 5 MOS", "AK-47", "H&K MP5") into a single catalog id, or says why it cannot.

This is not search. /v1/firearms/search ranks a page of records about a query; this answers which record a query is, and reports its own certainty. It is a deterministic lookup over an index of spellings, so the same query returns the same id indefinitely, and it is the endpoint to call before any other when you are starting from text rather than from an id.

Three things about the response are deliberate. An ambiguous query is not decided for you: "Glock 19" is three generations, so status is ambiguous, firearmId is null, and all three are returned to choose between. Words the resolver could not place are returned in unresolvedTokens rather than dropped: "MOS" is a variant the catalog does not hold, and knowing that is worth more than being handed the base model as though it were the answer. And a fuzzy candidate is a suggestion offered when nothing matched at all; it never appears as a resolution.

Requires Builder tier or higher.

get/v1/firearms/resolve

Request

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

Query parameters

qstring required

The name to resolve, up to 200 characters.

Headers

If-None-Matchstring

The ETag from a previous response. If the body would be byte-identical, the API answers 304 Not Modified with no body. A 304 counts toward the per-minute rate limit but not the daily request allowance.

Response

The resolution, whether or not it resolved. A query that matches nothing is a 200 with status: "not_found", not a 404, because the request was answerable and the answer is that we hold no such record.

successboolean required

Always true on a successful response. Every error carries false and an error object instead.

Example response

{
  "success": true,
  "data": {
    "query": "G19 gen 5 MOS",
    "status": "resolved",
    "firearmId": "glock-19-gen5",
    "match": "shorthand",
    "score": 0.6,
    "matchedTokens": [
      "g19"
    ],
    "unresolvedTokens": [
      "mos"
    ],
    "alternatives": [
      {
        "firearmId": "glock-19-gen5",
        "name": "Glock 19 Gen5",
        "manufacturerName": "Glock",
        "match": "shorthand",
        "matchedAlias": "G19 Gen5",
        "score": 0.6
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.