Ammunition

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

Authentifizierung erforderlichBuilder+

client.ammunition.list()

List ammunition with optional filters and pagination.

list(params?: ListAmmunitionParams): Promise<PaginatedResponse<Ammunition>>

GET/v1/ammunition

Builder+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

integerstandard1
Page number, from 1 to 10,000
Bereich
1 – 10000
Beispiel
integerstandard20
Items per page (max 100)
Bereich
1 – 100
Beispiel
string
Filter by caliber slug
Beispiel
string
Filter by bullet construction
Beispiel
integer
Restrict to commonly stocked loads (1) or uncommon ones (0)
Bereich
0 – 1
Beispiel

application/json

AmmunitionLoad[]
A specific factory ammunition load within a caliber.
string
URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.
string
Slug of the cartridge. Resolve against /v1/calibers/{id}.
string
Display name, as the maker writes it.
string | null
Military or standards designation for the load, e.g. M882.
string | null
Who makes it.
string | null
ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.
number
Bullet weight in grams. Divide by 0.0648 for grains.
string
Bullet construction: fmj, jhp, sp, match.
number | null
Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.
number | null
Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.
number
Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.
number
Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.
number | null
Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.
integer | null
Year it entered production or service. Null where the date is disputed or unknown.
integer
1 when the load is commonly stocked.
string | null
Absolute URL of the rendered bullet diagram.
number | null
Decay exponent used when extrapolating velocity to a barrel length other than the reference one.
string | null
Prose summary of the record, where one has been written.
integer
1 when the load is a military issue round.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.
number
Current page number
number
Items per page
number
Total matching records (Builder and above)

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

Alle Anfragelimits

Mindeststufe: Builder+
Monatskontingent: 25,000/mo
Anfragerate: 60/min
Tageslimit: 2,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

Dieser Aufruf beantwortet bedingte Anfragen. Speichern Sie das ETag einer Antwort und senden Sie es als If-None-Match zurueck: ein unveraenderter Datensatz liefert 304 Not Modified ohne Body. Das zaehlt auf Ihr Minutenlimit, aber nicht auf Ihr Tageskontingent.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const result = await client.ammunition.list({6  caliber_id: '9x19mm-parabellum',7  bullet_type: 'hollow-point',8  per_page: 25,9});

1{2  "success": true,3  "data": [4    {5      "id": "m882",6      "caliberId": "9x19mm-parabellum",7      "name": "9mm 124gr FMJ",8      "designation": "M882",9      "manufacturer": "Federal",10      "countryOfOrigin": "US",11      "bulletWeightG": 8.03,12      "bulletType": "fmj",13      "ballisticCoefficientG1": 0.165,14      "ballisticCoefficientG7": null,15      "referenceVelocityMps": 360,16      "referenceBarrelLengthMm": 114,17      "sectionalDensity": 0.14,18      "yearIntroduced": 1985,19      "isCommon": 1,20      "bulletSvgUrl": null,21      "velocityRetentionExponent": 0.12,22      "description": "Special purpose subsonic 7.62x39mm ammunition.",23      "isMilitary": 1,24      "createdAt": "2026-05-26 12:30:51",25      "updatedAt": "2026-05-26 12:30:51"26    }27  ],28  "pagination": {29    "page": 1,30    "limit": 20,31    "per_page": 20,32    "total": 605,33    "totalPages": 3134  }35}

Authentifizierung erforderlichBuilder+

client.ammunition.listAutoPaging()

Auto-paginate through all ammunition matching the given filters. Returns an async iterator that fetches pages on demand, yielding individual Ammunition objects.

listAutoPaging(params?: ListAmmunitionParams): AsyncIterableIterator<Ammunition>

GET/v1/ammunition

Builder+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

integerstandard1
Page number, from 1 to 10,000
Bereich
1 – 10000
Beispiel
integerstandard20
Items per page (max 100)
Bereich
1 – 100
Beispiel
string
Filter by caliber slug
Beispiel
string
Filter by bullet construction
Beispiel
integer
Restrict to commonly stocked loads (1) or uncommon ones (0)
Bereich
0 – 1
Beispiel

application/json

AmmunitionLoad[]
A specific factory ammunition load within a caliber.
string
URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.
string
Slug of the cartridge. Resolve against /v1/calibers/{id}.
string
Display name, as the maker writes it.
string | null
Military or standards designation for the load, e.g. M882.
string | null
Who makes it.
string | null
ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.
number
Bullet weight in grams. Divide by 0.0648 for grains.
string
Bullet construction: fmj, jhp, sp, match.
number | null
Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.
number | null
Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.
number
Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.
number
Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.
number | null
Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.
integer | null
Year it entered production or service. Null where the date is disputed or unknown.
integer
1 when the load is commonly stocked.
string | null
Absolute URL of the rendered bullet diagram.
number | null
Decay exponent used when extrapolating velocity to a barrel length other than the reference one.
string | null
Prose summary of the record, where one has been written.
integer
1 when the load is a military issue round.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.
number
Current page number
number
Items per page
number
Total matching records (Builder and above)

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

Returns an async iterator: it fetches each page as you consume it, so a loop over the whole collection is one statement and one page in memory at a time.

Alle Anfragelimits

Mindeststufe: Builder+
Monatskontingent: 25,000/mo
Anfragerate: 60/min
Tageslimit: 2,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

Caching-Leitfaden

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5let seen = 0;6for await (const ammo of client.ammunition.listAutoPaging({ caliber_id: '45-acp' })) {7  console.log(ammo.name, ammo.bulletWeightGrains);8  // Drop this to walk the whole collection.9  if (++seen >= 5) break;10}

1{2  "success": true,3  "data": [4    {5      "id": "m882",6      "caliberId": "9x19mm-parabellum",7      "name": "9mm 124gr FMJ",8      "designation": "M882",9      "manufacturer": "Federal",10      "countryOfOrigin": "US",11      "bulletWeightG": 8.03,12      "bulletType": "fmj",13      "ballisticCoefficientG1": 0.165,14      "ballisticCoefficientG7": null,15      "referenceVelocityMps": 360,16      "referenceBarrelLengthMm": 114,17      "sectionalDensity": 0.14,18      "yearIntroduced": 1985,19      "isCommon": 1,20      "bulletSvgUrl": null,21      "velocityRetentionExponent": 0.12,22      "description": "Special purpose subsonic 7.62x39mm ammunition.",23      "isMilitary": 1,24      "createdAt": "2026-05-26 12:30:51",25      "updatedAt": "2026-05-26 12:30:51"26    }27  ],28  "pagination": {29    "page": 1,30    "limit": 20,31    "per_page": 20,32    "total": 605,33    "totalPages": 3134  }35}

Authentifizierung erforderlichBuilder+

client.ammunition.get()

Get a single ammunition load by its slug or ID.

get(id: string): Promise<APIResponse<Ammunition>>

GET/v1/ammunition/{id}

Builder+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Ammunition load slug
Akzeptiert
a lowercase slug: letters, digits and hyphens
Beispiel

application/json

AmmunitionLoad
A specific factory ammunition load within a caliber.
string
URL-safe slug identifying the load, e.g. 9mm-124gr-fmj.
string
Slug of the cartridge. Resolve against /v1/calibers/{id}.
string
Display name, as the maker writes it.
string | null
Military or standards designation for the load, e.g. M882.
string | null
Who makes it.
string | null
ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.
number
Bullet weight in grams. Divide by 0.0648 for grains.
string
Bullet construction: fmj, jhp, sp, match.
number | null
Ballistic coefficient against the G1 drag model, the convention for flat-based bullets.
number | null
Ballistic coefficient against the G7 drag model, which fits boat-tail rifle bullets better than G1.
number
Muzzle velocity in metres per second at the reference barrel length below, not at the barrel of any particular firearm.
number
Barrel length in millimetres the reference velocity was measured from. Velocity for another barrel is extrapolated from this pair.
number | null
Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.
integer | null
Year it entered production or service. Null where the date is disputed or unknown.
integer
1 when the load is commonly stocked.
string | null
Absolute URL of the rendered bullet diagram.
number | null
Decay exponent used when extrapolating velocity to a barrel length other than the reference one.
string | null
Prose summary of the record, where one has been written.
integer
1 when the load is a military issue round.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When a field we serve last changed, YYYY-MM-DD HH:MM:SS in UTC.

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

Alle Anfragelimits

Mindeststufe: Builder+
Monatskontingent: 25,000/mo
Anfragerate: 60/min
Tageslimit: 2,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

Caching-Leitfaden

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.ammunition.get('federal-hst-124jhp');6console.log(data.name, data.muzzleVelocityFps, data.bulletWeightGrains);

1{2  "success": true,3  "data": {4    "id": "m882",5    "caliberId": "9x19mm-parabellum",6    "name": "9mm 124gr FMJ",7    "designation": "M882",8    "manufacturer": "Federal",9    "countryOfOrigin": "US",10    "bulletWeightG": 8.03,11    "bulletType": "fmj",12    "ballisticCoefficientG1": 0.165,13    "ballisticCoefficientG7": null,14    "referenceVelocityMps": 360,15    "referenceBarrelLengthMm": 114,16    "sectionalDensity": 0.14,17    "yearIntroduced": 1985,18    "isCommon": 1,19    "bulletSvgUrl": null,20    "velocityRetentionExponent": 0.12,21    "description": "Special purpose subsonic 7.62x39mm ammunition.",22    "isMilitary": 1,23    "createdAt": "2026-05-26 12:30:51",24    "updatedAt": "2026-05-26 12:30:51"25  }26}

Authentifizierung optionalExplorer+

client.ammunition.getBulletSvg()

Get a bullet profile SVG image for an ammunition load. Returns a raw SVG string representing the bullet projectile shape. This endpoint returns raw SVG content, not the standard JSON envelope.

getBulletSvg(id: string): Promise<string>

GET/v1/ammunition/{id}/bullet.svg

Explorer+

stringHeader
Optional. Ohne Schlüssel antwortet dieser Endpunkt nach der öffentlichen Richtlinie; ein Schlüssel erhöht Ihre Limits und schaltet planabhängige Felder frei. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Ammunition load slug
Akzeptiert
a lowercase slug: letters, digits and hyphens
Beispiel

400VALIDATION_ERRORValidation error
404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const svg = await client.ammunition.getBulletSvg('federal-hst-124jhp');6// Mount it by parsing the SVG, e.g. via DOMParser + element.append().

1"string"

Authentifizierung erforderlichBuilder+

client.ammunition.ballistics()

Get ballistic trajectory data for an ammunition load.

ballistics(id: string, params?: AmmunitionBallisticsParams): Promise<APIResponse<BallisticProfile>>

GET/v1/ammunition/{id}/ballistics

Builder+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Ammunition load slug
Akzeptiert
a lowercase slug: letters, digits and hyphens
Beispiel

number
Barrel length to adjust muzzle velocity for
Bereich
50 – 2000
Beispiel
string
Comma-separated distances in metres
Beispiel

application/json

object
The response payload.
object
The load the figures are for.
string
Slug of the load the table was computed for.
string
Display name, as the maker writes it.
string
Slug of the cartridge. Resolve against /v1/calibers/{id}.
number | null
Barrel length in millimetres, measured from the breech face.
number
Muzzle velocity in metres per second, for the default load.
number
Muzzle energy in joules, for the default load.
number
Effective range in metres against a point target.
TerminalBallistics
Terminal performance indices computed at the muzzle.
number
Taylor Knock-Out factor.
number
Momentum in kilogram-metres per second.
number
Bullet mass divided by the square of its diameter. Higher penetrates better, all else equal.
number
Hatcher Relative Stopping Power.
number
Energy per unit frontal area, in joules per square centimetre.
TrajectoryPoint[]
The solution sampled at each requested distance.
number
Distance from the muzzle in metres.
number
Remaining velocity at this distance, in metres per second.
number
Remaining energy at this distance, in joules.
number
Bullet drop below the line of sight at this distance, in centimetres.
number
Time of flight to this distance, in seconds.
number
Velocity as a multiple of the speed of sound. Below ~1.2 the projectile is transonic and destabilises.
number
Momentum in kilogram-metres per second.
number
Taylor Knock-Out factor at this distance.
number
Energy per unit frontal area, in joules per square centimetre.

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

Alle Anfragelimits

Mindeststufe: Builder+
Monatskontingent: 25,000/mo
Anfragerate: 60/min
Tageslimit: 2,000

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.ammunition.ballistics('federal-hst-124jhp', {6  barrel_length_mm: 102,7  distances: '0,25,50,100,200',8});9for (const point of data.trajectory) {10  console.log(`${point.distanceM}m: ${point.velocityFps} fps, ${point.energyFtLbs} ft-lbs`);11}

1{2  "success": true,3  "data": {4    "ammunition": {5      "id": "m882",6      "name": "9mm 124gr FMJ",7      "caliberId": "9x19mm-parabellum"8    },9    "barrelLengthMm": 114,10    "muzzleVelocityMps": 360,11    "muzzleEnergyJ": 510,12    "effectiveRangeM": 50,13    "terminalBallistics": {14      "tkoFactor": 12.9,15      "momentumKgMs": 5.7,16      "sectionalDensity": 0.181,17      "hatcherRSP": 103,18      "energyDensityJCm2": 4135.219    },20    "trajectory": [21      {22        "distanceM": 100,23        "velocityMps": 686,24        "energyJ": 1873,25        "dropCm": 10,26        "timeOfFlightS": 0.143,27        "machNumber": 2,28        "momentumKgMs": 5.46,29        "tkoFactor": 12.3,30        "energyDensityJCm2": 3801.531      }32    ]33  }34}

Ammunition

AutorisierungBuilder+

Abfrageparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

CachingCaching-Leitfaden

AutorisierungBuilder+

Abfrageparameter

Antwort200application/json

Fehler

Hinweise

AnfragelimitsAlle Anfragelimits

CachingCaching-Leitfaden

AutorisierungBuilder+

Pfadparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

CachingCaching-Leitfaden

AutorisierungExplorer+

Pfadparameter

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungBuilder+

Pfadparameter

Abfrageparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

Builder+

application/json

Alle Anfragelimits

Caching-Leitfaden

Builder+

application/json

Alle Anfragelimits

Caching-Leitfaden

Builder+

application/json

Alle Anfragelimits

Caching-Leitfaden

Explorer+

Alle Anfragelimits

Builder+

application/json

Alle Anfragelimits