Firearm Analysis

Compare the cost of marching with each firearm

Returns the metabolic cost of a foot march carrying each of up to 5 firearms, by a published load-carriage equation, from the masses the catalogue records.

Each firearm is carried empty plus magazines full magazines, plus the attachments named, on top of kit_kg of other equipment. A full magazine is the firearm's loaded weight less its empty weight: two figures the record states, never an estimate. A firearm missing one of them is answered with an error in place of its cost, and the others are still compared.

The default model is the US Army Load Carriage Decision Aid backpacking equation (Looney et al. 2022) with its graded-walking term, which covers level, uphill and downhill marching. model=pandolf gives the Pandolf equation (1977) for comparison with the older literature, level and uphill only. Each answer carries the equation, its constants' sources and the range it was fitted on, and warns where an input lies outside that range.

Every input has a default, and march.defaulted names the ones the answer assumed. The result is energy expenditure only: neither model predicts fatigue, marksmanship or time to exhaustion.

Requires Builder tier or higher.

get/v1/firearms/load-carriage

Request

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

Query parameters

idsstring required

Comma-separated firearm slugs, maximum 5.

body_mass_kgnumber

Soldier body mass in kg.

body_fat_pctnumber

Body fat as a percentage of body mass; the LCDA resting rate is computed from lean mass.

kit_kgnumber

Everything else carried, in kg: armour, pack, water.

magazinesinteger

Full magazines carried in total, the one in the firearm included. 0 carries it unloaded.

attachmentsstring

Comma-separated attachment slugs, maximum 10, added to every firearm by their recorded weight.

speed_kmhnumber

Marching speed in km/h.

grade_pctnumber

Slope as a percentage, rise over run: negative is downhill.

terrain'paved' | 'dirt_road' | 'light_brush' | 'heavy_brush' | 'swampy_bog' | 'loose_sand'

Surface: paved (paved road or treadmill), dirt_road (dirt road), light_brush (light brush), heavy_brush (heavy brush), swampy_bog (swampy bog), loose_sand (loose sand).

distance_kmnumber

March distance in km.

model'lcda' | 'pandolf'

Equation: lcda (default) or pandolf, which refuses a downhill grade.

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

Compare the cost of marching with each firearm

successboolean required

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

Example response

{
  "success": true,
  "data": {
    "model": {
      "id": "lcda",
      "name": "LCDA backpacking equation with the LCDA graded-walking term",
      "citations": [
        {
          "authors": "Looney DP, Lavoie EM, Vangala SV, Holden LD, Figueiredo PS, Friedl KE, et al.",
          "year": 2022,
          "title": "Modeling the Metabolic Costs of Heavy Military Backpacking",
          "journal": "Medicine & Science in Sports & Exercise 54(4):646-654",
          "doi": "10.1249/MSS.0000000000002833"
        }
      ],
      "validated": {
        "speedMps": [
          0.45
        ],
        "loadFraction": [
          0.66
        ]
      }
    },
    "march": {
      "bodyMassKg": 80,
      "bodyFatPct": 15,
      "kitKg": 25,
      "magazines": 7,
      "speedKmh": 4.8,
      "speedMps": 1.333,
      "terrain": "paved",
      "terrainFactor": 1,
      "distanceKm": 20,
      "durationS": 15000,
      "defaulted": [
        "body_mass_kg"
      ]
    },
    "attachments": [
      {
        "id": "aimpoint-compm5",
        "name": "Aimpoint CompM5",
        "weightG": 148
      }
    ],
    "results": [
      {
        "firearm": {
          "id": "hk416",
          "name": "HK416",
          "magazineType": "detachable_box",
          "magazineCapacity": 30
        },
        "load": {
          "firearmEmptyG": 3020,
          "loadedMagazineG": 400,
          "magazines": 7,
          "magazinesG": 2800,
          "attachmentsG": 148,
          "carriedG": 5968,
          "totalLoadKg": 30.968,
          "loadFraction": 0.387
        },
        "cost": {
          "watts": 481.2,
          "wattsPerKg": 6.02,
          "energyKj": 7218,
          "energyKcal": 1725.2
        },
        "delta": {
          "carriedG": 390,
          "watts": 6.1,
          "energyKj": 91.5,
          "energyKcal": 21.9
        }
      }
    ]
  }
}

Changes

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