Statistics & Analytics

Explorer+

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

application/json

object
The response payload.
integer
Firearms in the catalog.
integer
Manufacturers in the catalog. Counts rows, so it exceeds the number of makers with a catalogued firearm.
integer
Cartridges in the catalog.
integer
Distinct countries of origin across the catalog.
number
Mean data_confidence across the catalog, as a percentage rather than the 0-1 the per-record field uses.
integer
Firearms that are a variant of another, meaning those carrying a parentFirearmId.

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

Responses carry an ETag. Send it back as If-None-Match to receive a 304 Not Modified when nothing has changed.

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.

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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/summary' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": {4    "total_firearms": 9162,5    "total_manufacturers": 1112,6    "total_calibers": 605,7    "countries_of_origin": 92,8    "avg_confidence": 74,9    "total_variants": 135010  }11}

Explorer+

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

application/json

object[]
The response payload.
string | 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.
integer
How many records fall in this bucket.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/production-status' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "status": "in_production",6      "count": 6407    }8  ]9}

Explorer+

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

application/json

object[]
The response payload.
string
Which column the row is about, named as the database names it.
number
Share of records, 0 to 100.

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

Covers the core spec fields: weight_empty_g, barrel_length_mm, action_type, magazine_capacity, effective_range_m, frame_material, year_introduced, country_of_origin, description, height_mm, width_mm, and muzzle_velocity_mps.

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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/field-coverage' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "field": "weight_empty_g",6      "percentage": 947    }8  ]9}

Explorer+

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

application/json

object
The response payload.
integer
Total records matching the query across every page.
number
Percentage of firearms carrying at least one image.
number
Percentage of firearms carrying at least one recorded specification.
number
Percentage of firearms with at least one caliber recorded.
number
Percentage of firearms with an unloaded weight recorded.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/catalog-coverage' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": {4    "total": 9162,5    "images": 28,6    "specifications": 95.9,7    "caliber": 82.4,8    "weight": 94.39  }10}

Explorer+

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

integerdefault20
How many to return
Range
1 – 100
Example

application/json

object[]
The response payload.
string
Slug of the cartridge.
string
Display name, as the maker writes it.
string | null
NATO designation where the cartridge has one. Null otherwise.
integer
How many catalogued firearms chamber it.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/calibers/popular?limit=10' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "id": "9x19mm-parabellum",6      "name": "9x19mm Parabellum",7      "nato_designation": "9mm NATO",8      "firearm_count": 11409    }10  ]11}

Explorer+

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

integerdefault20
How many to return
Range
1 – 100
Example
string
Restrict to a category slug
Example

application/json

object[]
The response payload.
string
Slug of the manufacturer.
string
Display name, as the maker writes it.
string | null
ISO 3166-1 alpha-2 code of where they are based.
integer
How many catalogued firearms they make.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/manufacturers/prolific?category=rifle&limit=5' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "id": "smith-wesson",6      "name": "Smith & Wesson",7      "country_code": "US",8      "firearm_count": 3569    }10  ]11}

Explorer+

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

application/json

object[]
The response payload.
string
Slug of the category.
string
Display name, as the maker writes it.
integer
How many catalogued firearms are in it.
number | null
Mean unloaded weight in grams across the category, over the firearms that record one.
number | null
Mean magazine capacity across the category, over the firearms that record one.
number | null
Mean barrel length in millimetres across the category, over the firearms that record one.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/by-category' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "id": "pistol",6      "name": "Pistol",7      "firearm_count": 3922,8      "avg_weight_g": 816.37,9      "avg_magazine_capacity": 10.94,10      "avg_barrel_length_mm": 111.0711    }12  ]13}

Studio+

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

stringrequired
Decade to report on, formatted like "1990s"
Example

application/json

object
The response payload.
integer
Firearms introduced in the decade.
number | null
Mean unloaded weight in grams, over those that record one.
number | null
Mean magazine capacity, over those that record one.
number | null
Mean barrel length in millimetres, over those that record one.
integer | null
Earliest introduction year inside the decade that any record carries.
integer | null
Latest introduction year inside the decade that any record carries.

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

Requires Studio tier or higher.

Decade must be a string like "1940s", "1990s", "2020s".

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/by-era?decade=1990s' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": {4    "firearm_count": 487,5    "avg_weight_g": 2183.4,6    "avg_magazine_capacity": 14.2,7    "avg_barrel_length_mm": 304.9,8    "earliest_year": 1990,9    "latest_year": 199910  }11}

Studio+

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

application/json

object
The response payload.
object[]
Frame materials, and how many firearms use each.
string
The material as recorded on the firearm.
integer
How many records fall in this bucket.
object[]
Slide materials, and how many firearms use each.
string
The material as recorded on the firearm.
integer
How many records fall in this bucket.
object[]
Barrel materials, and how many firearms use each.
string
The material as recorded on the firearm.
integer
How many records fall in this bucket.
object[]
Stock materials, and how many firearms use each.
string
The material as recorded on the firearm.
integer
How many records fall in this bucket.

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

Requires Studio tier or higher.

Materials are sorted by count descending within each component.

Firearms without a value for a given component are excluded from that breakdown.

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/materials' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": {4    "frame": [5      {6        "material": "Polymer",7        "count": 28418      }9    ],10    "slide": [11      {12        "material": "Polymer",13        "count": 284114      }15    ],16    "barrel": [17      {18        "material": "Polymer",19        "count": 284120      }21    ],22    "stock": [23      {24        "material": "Polymer",25        "count": 284126      }27    ]28  }29}

Studio+

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

stringrequired
ISO 3166-1 alpha-2 country code
Max length
10
Example

application/json

object[]
The response payload.
integer
Numeric id of the adoption record itself, not of the firearm.
string | null
The organisation that adopted the firearm.
string | null
Kind of operator: one of military, law_enforcement, civilian, paramilitary, special_forces, private_security, training.
integer | null
Year the operator adopted it. Null where the date is unrecorded.
string | null
Military or standards designation for the load, e.g. M882.
string
Slug of the adopted firearm.
string
Display name of the firearm.

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

Requires Studio tier or higher.

Country code must be a valid ISO 3166-1 alpha-2 code.

Results include military, police, and civilian adoption records.

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/adoption/by-country?code=AT' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "id": 412,6      "user_name": "Australian Army",7      "user_type": "military",8      "adopted_year": 1988,9      "designation": "F88 Austeyr",10      "firearm_id": "steyr-aug",11      "firearm_name": "Steyr AUG"12    }13  ]14}

Studio+

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

stringrequired
Operator type
Accepts
Example

application/json

object[]
The response payload.
string
Slug of the adopted firearm.
string
Display name of the firearm.
integer
How many operators of this type adopted it.
string[]
ISO 3166-1 alpha-2 codes of the countries those operators belong to.

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

Requires Studio tier or higher.

Valid types are military, police, and civilian.

Results are sorted by adoption count descending.

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/adoption/by-type?type=military' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "firearm_id": "makarov-pm",6      "firearm_name": "Makarov PM",7      "adoption_count": 36,8      "countries": [9        "SU"10      ]11    }12  ]13}

Explorer+

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

string
Restrict to a category slug
Example

application/json

object[]
The response payload.
string | null
The action as stored, and the value to send as action_type when filtering.
integer
How many records fall in this bucket.

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

Results are sorted by count descending.

Percentages are relative to the total firearms matching the filter (or all firearms if no filter).

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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/action-types?category=pistol' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "action_type": "short_recoil",6      "count": 28127    }8  ]9}

Builder+

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

string
Restrict to a category slug
Example
integerdefault50
How many to return
Range
1 – 100
Example

application/json

object[]
The response payload.
string
The feature as stored, and the value to send as feature to /v1/firearms/by-feature.
integer
How many records fall in this bucket.

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

Requires Builder tier or higher.

Features are extracted from firearm specification fields.

Results are sorted by count descending.

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.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/feature-frequency?category=rifle&limit=10' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "feature": "threaded-barrel",6      "count": 1637    }8  ]9}

Studio+

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

string
Earliest decade, formatted like "1940s"
Example
string
Latest decade, formatted like "2020s"
Example

application/json

object[]
The response payload.
string
The decade this row covers, e.g. 1940s.
object[]
The cartridges chambered by firearms introduced in this decade.
string
Slug of the cartridge. Resolve against /v1/calibers/{id}.
string
Display name of the cartridge.
integer
How many firearms this row covers.

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

Requires Studio tier or higher.

Decade format must be a string like "1940s", "1990s", "2020s".

Calibers within each decade are sorted by count descending.

Only the top 10 calibers per decade are returned.

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1curl --request GET \2  --url 'https://api.gunspec.io/v1/stats/caliber-popularity-by-era?from_decade=1940s&to_decade=2020s' \3  --header 'X-API-Key: your_key'

1{2  "success": true,3  "data": [4    {5      "decade": "1940s",6      "calibers": [7        {8          "caliberId": "9x19mm-parabellum",9          "caliberName": "9x19mm Parabellum",10          "firearmCount": 4211        }12      ]13    }14  ]15}

AuthorizationExplorer+

Response200application/json

Errors

Notes

Rate limitsFull rate limits

CachingCaching guide

AuthorizationExplorer+

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationExplorer+

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationStudio+

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationBuilder+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Notes

Rate limitsFull rate limits

Explorer+

application/json

Full rate limits

Caching guide

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Studio+

application/json

Full rate limits

Studio+

application/json

Full rate limits

Studio+

application/json

Full rate limits

Studio+

application/json

Full rate limits

Explorer+

application/json

Full rate limits

Builder+

application/json

Full rate limits

Studio+

application/json

Full rate limits