# Countries

Country-level military and law enforcement adoption data. Discover which countries use which firearms.

Source: https://docs.gunspec.io/en/api/countries

## List Countries

`GET /v1/countries`

Auth: API key required  
Tier: Explorer+

Returns every country that has adopted a catalogued firearm, ranked by how many distinct firearms it operates.

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | object[] | The response payload. |
| `data[].code` | string | ISO 3166-1 alpha-2 country code. |
| `data[].firearm_count` | integer | Distinct catalogued firearms this country operates. |

```json
{
  "success": true,
  "data": [
    {
      "code": "US",
      "firearm_count": 214
    }
  ]
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Countries are sorted by firearm_count descending.
- Only countries with at least one adoption record are included.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/countries' \
  --header 'X-API-Key: your_key'
```

## Country Arsenal

`GET /v1/countries/{code}/arsenal`

Auth: API key required  
Tier: Builder+

Returns the firearms in service with one country, grouped by operator type (military, law enforcement, and so on).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | ISO 3166-1 alpha-2 country code |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The country arsenal, keyed by operator type. |
| `data.countryCode` | string | ISO 3166-1 alpha-2 code of the country, echoing the path parameter. |
| `data.arsenal` | object | Operator type -> the firearms that type operates. Keys are dynamic; entries missing a type are grouped under "unknown". |

```json
{
  "success": true,
  "data": {
    "countryCode": "AU",
    "arsenal": {}
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Requires **Builder** tier or higher.
- Country code must be a valid ISO 3166-1 alpha-2 code (e.g. US, DE, GB, RU, CN).
- Records within each group are sorted by adopted_year descending (most recent first).
- Empty arrays indicate no adoption records for that user type.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/countries/AU/arsenal' \
  --header 'X-API-Key: your_key'
```