Stats

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

Auth RequiredExplorer+

client.stats.summary()

Get a high-level summary of the database.

summary(): Promise<APIResponse<StatsSummary>>

GET/v1/stats/summary

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.summary();6console.log(`Database has ${data.totalFirearms} firearms`);

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}

Auth RequiredExplorer+

client.stats.productionStatus()

Get firearm counts grouped by production status.

productionStatus(): Promise<APIResponse<ProductionStatusItem[]>>

GET/v1/stats/production-status

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.productionStatus();6// { in_production: 342, discontinued: 891, prototype: 12 }

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

Auth RequiredExplorer+

client.stats.fieldCoverage()

Get field coverage statistics across the database. Shows the percentage of firearms that have data for each field, useful for assessing data completeness.

fieldCoverage(): Promise<APIResponse<FieldCoverage>>

GET/v1/stats/field-coverage

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.fieldCoverage();6console.log(`Weight field: ${data.weight}% coverage`);

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

Auth RequiredExplorer+

client.stats.popularCalibers()

Get the most popular calibers by firearm count.

popularCalibers(params?: PopularCalibersParams): Promise<APIResponse<PopularCaliber[]>>

GET/v1/stats/calibers/popular

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.popularCalibers({ limit: 10 });6for (const entry of data) {7  console.log(`${entry.name}: ${entry.count} firearms`);8}

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}

Auth RequiredExplorer+

client.stats.prolificManufacturers()

Get the most prolific manufacturers by firearm count.

prolificManufacturers(params?: ProlificManufacturersParams): Promise<APIResponse<ProlificManufacturer[]>>

GET/v1/stats/manufacturers/prolific

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.prolificManufacturers({6  limit: 10,7  category: 'pistol',8});

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}

Auth RequiredExplorer+

client.stats.byCategory()

Get firearm counts grouped by category.

byCategory(): Promise<APIResponse<CategoryStats[]>>

GET/v1/stats/by-category

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.byCategory();6// [{ category: 'pistol', count: 512 }, { category: 'rifle', count: 234 }, ...]

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}

Auth RequiredStudio+

client.stats.byEra()

Get firearm statistics for a specific decade/era.

byEra(params: ByEraParams): Promise<APIResponse<EraStats>>

GET/v1/stats/by-era

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.byEra({ decade: '1940s' });

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}

Auth RequiredStudio+

client.stats.materials()

Get statistics about materials used across all firearms.

materials(): Promise<APIResponse<MaterialStats>>

GET/v1/stats/materials

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.materials();

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}

Auth RequiredStudio+

client.stats.adoptionByCountry()

Get firearm adoption statistics for a specific country.

adoptionByCountry(params: AdoptionByCountryParams): Promise<APIResponse<AdoptionByCountryItem[]>>

GET/v1/stats/adoption/by-country

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.adoptionByCountry({ code: 'US' });

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}

Auth RequiredStudio+

client.stats.adoptionByType()

Get firearm adoption statistics by usage type.

adoptionByType(params: AdoptionByTypeParams): Promise<APIResponse<AdoptionByTypeItem[]>>

GET/v1/stats/adoption/by-type

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.adoptionByType({ type: 'military' });

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}

Auth RequiredExplorer+

client.stats.actionTypes()

Get firearm counts grouped by action type.

actionTypes(params?: ActionTypesParams): Promise<APIResponse<ActionTypeStats[]>>

GET/v1/stats/action-types

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.actionTypes({ category: 'rifle' });

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

Auth RequiredBuilder+

client.stats.featureFrequency()

Get feature frequency statistics across the database.

featureFrequency(params?: FeatureFrequencyParams): Promise<APIResponse<FeatureFrequency[]>>

GET/v1/stats/feature-frequency

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.featureFrequency({6  category: 'pistol',7  limit: 20,8});

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

Auth RequiredStudio+

client.stats.caliberPopularityByEra()

Get caliber popularity trends across historical eras.

caliberPopularityByEra(params?: CaliberPopularityByEraParams): Promise<APIResponse<CaliberPopularityByEra[]>>

GET/v1/stats/caliber-popularity-by-era

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

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.caliberPopularityByEra({6  from_decade: '1940s',7  to_decade: '2020s',8});

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}

Auth RequiredExplorer+

client.stats.catalogCoverage()

Get catalog completeness percentages. Reports what share of firearms have a line-art image, core specifications filled, at least one caliber mapped, and a recorded weight. Computed live.

catalogCoverage(): Promise<APIResponse<CatalogCoverage>>

GET/v1/stats/catalog-coverage

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.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.stats.catalogCoverage();6console.log(`${data.images}% of ${data.total} firearms have line art`);

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}

Stats

AuthorizationExplorer+

Response200application/json

Errors

Rate limitsFull rate limits

CachingCaching guide

AuthorizationExplorer+

Response200application/json

Errors

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

Rate limitsFull rate limits

AuthorizationStudio+

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationBuilder+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationExplorer+

Response200application/json

Errors

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

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

Explorer+

application/json

Full rate limits