GunSpec

Firearms

Browse, search, compare, and retrieve detailed specifications for over 9,000+ firearms including variants.

Auth RequiredExplorer+

Find Similar

Returns the 10 most similar firearms in the same category, scored on shared calibers, manufacturer, action type, weight, barrel length, year, and capacity. Each result inlines its images array so a "you may also like" strip can be rendered from this one call.

GET/v1/firearms/{id}/similar

Explorer+

  • 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

application/json

  • SimilarFirearm[]

    The response payload.

  • string

    Slug of the similar firearm.

  • string

    Display name, as the maker writes it.

  • number

    How alike the two records are, 0 to 1. Computed from the specifications, not from what people browse together.

  • string | null

    Slug of the manufacturer that makes it. Resolve against /v1/manufacturers/{id}.

  • string | null

    Slug of the category it belongs to. Resolve against /v1/categories.

  • string | null

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

  • integer | null

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

  • FirearmStatus | null

    Production status, one of in_production, discontinued, out_of_production, in_service, limited_production, prototype. Discontinued records are kept deliberately: a rifle built in 2004 wears parts nobody sells today.

  • string | null

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

  • string | null

    How the action cycles: short_recoil, gas_operated, blowback, bolt_action and so on. An open vocabulary: the values in use are published on the schema as x-gunspec-vocabulary, and GET /v1/firearms/action-types is the live list.

  • InlineMediaItem[]

    Every image this firearm has, silhouette first. Empty when none are on file.

  • integer

    Autoincrementing image id.

  • string

    Absolute, directly fetchable URL.

  • MediaKind

    What kind of asset a media row is.

  • string | null

    Alt text, where one has been written. Null otherwise, so do not render an empty string.

  • integer | null

    Pixel width, where it is known.

  • integer | null

    Pixel height, where it is known.

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

Requires Explorer tier or higher.

Returns at most 10 results, sorted by similarity score descending.

Score factors: shared calibers (0.20), action type (0.15), weight proximity, barrel length, era, magazine capacity, manufacturer.

Each result inlines its images array, so a related-products strip needs no follow-up request. For credits, licensing, or data-URI encoding, call /v1/firearms/{id}/media.

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.