--- title: "Compare the cost of marching with each firearm" method: GET path: "/v1/firearms/load-carriage" tags: ["Firearm Analysis"] --- # Compare the cost of marching with each firearm `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 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.** ## Query parameters - `ids` string, required - `body_mass_kg` number - `body_fat_pct` number - `kit_kg` number - `magazines` integer - `attachments` string - `speed_kmh` number - `grade_pct` number - `terrain` 'paved' | 'dirt_road' | 'light_brush' | 'heavy_brush' | 'swampy_bog' | 'loose_sand' - `distance_km` number - `model` 'lcda' | 'pandolf' ## Headers - `If-None-Match` string ## Response `200` Compare the cost of marching with each firearm - object - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead. - `data` object, required: The response payload. - `model` object: The equation behind every figure in the answer. - `id` string: The model the costs were computed with. - `name` string: The model by name. - `equation` string: The equation as written, with its units, so the figures can be reproduced. - `citations` object[]: Where the equation and its constants are from. - `authors` string: Authors as the paper lists them. - `year` integer: Year of publication. - `title` string: Title of the paper. - `journal` string: Journal, volume, issue and pages. - `doi` string, nullable: Digital Object Identifier, where the paper has one. - `validated` object, nullable: The range the equation was fitted on. Null for a model whose paper states none here. - `speedMps` number[]: Slowest and fastest fitted speed, in m/s. - `loadFraction` number[]: Lightest and heaviest fitted load, as a share of body mass. - `march` object: The march every firearm was costed on. - `bodyMassKg` number: Soldier body mass in kg. - `bodyFatPct` number: Body fat as a percentage of body mass. - `kitKg` number: Other equipment carried, in kg. - `magazines` integer: Full magazines carried in total. - `speedKmh` number: Marching speed in km/h. - `speedMps` number: Marching speed in m/s, as the equations read it. - `gradePct` number: Slope as a percentage. - `terrain` string: Surface id. - `terrainFactor` number: The terrain factor (Soule and Goldman 1972) the moving cost is multiplied by. - `distanceKm` number: March distance in km. - `durationS` integer: How long the march takes at this speed, in seconds. - `defaulted` string[]: The query parameters not sent, answered from their defaults. - `attachments` object[]: The attachments added to every firearm. - `id` string: Attachment slug. - `name` string: Attachment name. - `weightG` number: Recorded weight in grams. - `results` object[]: One result per firearm, in the order their ids were given. - `firearm` object: The firearm this result is for. - `id` string: Firearm slug. - `name` string: Firearm name. - `magazineType` string, nullable: How the firearm feeds, as the catalogue records it. - `magazineCapacity` integer, nullable: Rounds in a standard magazine. - `load` object: What is carried, piece by piece. - `firearmEmptyG` number, nullable: Empty weight in grams, from the record. - `loadedMagazineG` number, nullable: What one full magazine adds, in grams: loaded weight less empty weight. - `magazines` integer: Full magazines counted. - `magazinesG` number, nullable: All the full magazines together, in grams. - `attachmentsG` number: All the attachments together, in grams. - `carriedG` number, nullable: The firearm, its magazines and its attachments, in grams. - `totalLoadKg` number, nullable: Everything carried, kit included, in kg. - `loadFraction` number, nullable: The total load as a share of body mass. - `sources` object: Where each firearm mass came from. - `firearmEmptyG` 'catalogue' | 'derived' | 'null', nullable: `catalogue` when the record states the empty weight. - `loadedMagazineG` 'catalogue' | 'derived' | 'null', nullable: `derived` when it was computed from the loaded and empty weights. - `cost` object, nullable: What the march costs this soldier with this firearm. Null when a mass it needs is not recorded; `error` says which. - `watts` number: Metabolic rate while marching, in watts, resting rate included. - `wattsPerKg` number: The same rate per kilogram of body mass. - `energyKj` number: Energy the whole march costs, in kilojoules. - `energyKcal` number: The same energy in kilocalories. - `delta` object, nullable: Against the option with the lightest carried load. Null on that option, on a lone firearm, and where no cost could be computed. - `carriedG` number: Grams more carried than the lightest option. - `watts` number: Watts more than the lightest option. - `energyKj` number: Kilojoules more over the march. - `energyKcal` number: Kilocalories more over the march. - `warnings` string[]: Where an input lies outside the fitted range, or a count needs qualifying. - `error` string, nullable: Why this firearm could not be costed. Null when it was. ## Other responses - `304`: Your copy is current. No body is sent, and this response does not count toward the daily request allowance. - `400`: Validation error - `401`: Missing or invalid API key - `403`: The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work. - `404`: Resource not found - `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset. - `500`: Internal server error --- [API](https://skmtc.dev/gunspec/apis/gunspec-io-api.md) · [All operations](https://skmtc.dev/gunspec/apis/gunspec-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gunspec/apis/gunspec-io-api/revisions/f2e974d8b05c?raw)