Compare the free recoil of each firearm
Returns the free recoil of each of up to 5 firearms firing a load: the velocity the firearm is pushed back at, the energy it takes and the impulse, by the free recoil formula the Sporting Arms and Ammunition Manufacturers' Institute (SAAMI) publishes.
The firearm's mass is its recorded loaded weight (mass=empty for its empty weight; the empty weight is used, with a warning, where no loaded weight is recorded). The bullet is the load's record, and its muzzle velocity is the one computed for this firearm's own barrel, as /v1/firearms/{id}/calculate computes it. With no ammo_id, each firearm fires the load /v1/firearms/{id}/load fires it with.
The catalogue records no powder charge. Without powder_charge_g, only the bullet's momentum is counted, and since the powder gas leaves the muzzle the same way, the real free recoil is larger: every figure is then a lower bound, and recoil.lowerBound says so. With a charge, the gas is added at SAAMI's gas velocity factor for the class of firearm (1.75 times the muzzle velocity for high powered rifles, 1.50 for handguns and average shotguns, 1.25 for long-barrelled shotguns). A submachine gun or personal defence weapon is in none of SAAMI's classes: name one with gas_class to count its gas.
Free recoil is the reaction of a firearm with nothing holding it. It is not felt recoil, and SAAMI's formula does not count a muzzle brake or suppressor redirecting the gas.
Requires Builder tier or higher.
Request
- Base URL: https://api.gunspec.io
- URL: https://api.gunspec.io/v1/firearms/recoil
- Auth: one of:
- API key in header X-API-Key
- HTTP bearer
Query parameters
Comma-separated firearm slugs, maximum 5.
The load every firearm fires. Without it, each fires the load its ballistic profile uses.
Which recorded weight the firearm recoils with: loaded or empty.
The load's powder charge in grams. Needs ammo_id. Without it the figures are a lower bound.
The SAAMI class whose gas velocity factor applies, in place of the one read from each firearm's category: rifle (high powered rifles, 1.75), shotgun (shotguns (average length), 1.5), shotgun_long_barrel (shotguns (long barrel), 1.25), handgun (pistol & revolvers, 1.5).
Headers
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
Compare the free recoil of each firearm
Example response
{
"success": true,
"data": {
"method": {
"id": "saami-free-recoil",
"name": "SAAMI free recoil",
"citations": [
{
"authors": "Sporting Arms and Ammunition Manufacturers' Institute (SAAMI)",
"year": 2018,
"title": "Gun Recoil, Technical: Free Recoil Energy",
"journal": "SAAMI technical sheet, Rev. 7/9/2018",
"url": "https://saami.org/wp-content/uploads/2025/03/Gun-Recoil-Formulae-2018-07-9.pdf"
}
],
"gasFactors": {
"rifle": 1.75,
"shotgun": 1.5,
"shotgun_long_barrel": 1.25,
"handgun": 1.5
}
},
"shot": {
"mass": "loaded",
"lowerBound": true,
"defaulted": [
"mass"
]
},
"results": [
{
"firearm": {
"id": "hk416",
"name": "HK416",
"categoryId": "assault-rifle",
"barrelLengthMm": 264
},
"ammunition": {
"id": "m855",
"name": "M855 Ball (SS109)",
"caliberId": "5-56x45mm-nato",
"bulletWeightG": 4.02
},
"mass": {
"firearmG": 3420
},
"muzzleVelocityMps": 777,
"gas": {
"class": "rifle",
"label": "High powered rifles",
"factor": 1.75
},
"recoil": {
"impulseNs": 3.125,
"bulletImpulseNs": 3.125,
"velocityMps": 0.914,
"energyJ": 1.43,
"lowerBound": true
},
"delta": {
"energyJ": 0.36,
"velocityMps": 0.123,
"impulseNs": 0.316
}
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.