HD2Clans Hangar API Spec

Endpoints

Base URL https://hd2clans.com/api/public

No authentication. CORS is open, so you can call it straight from a browser. Use the batch form if you're watching more than one clan.

Quick start

import requests

CLANS = [334, 597, 1404, 168, 1381, 1396, 1414, 483,
         1325, 395, 179, 1341, 1719, 1388, 902]

r = requests.get(
    "https://hd2clans.com/api/public/clan/hangars",
    params={"ids": ",".join(map(str, CLANS))},
    headers={"User-Agent": "YourAppName/1.0 (+contact: yourdiscord)"},
    timeout=30,
)
r.raise_for_status()

for hangar in r.json()["hangars"]:
    if not hangar["available"]:
        continue
    print(hangar["clan"]["name"], hangar["counts"]["total"], "ships")
    for ship in hangar["ships"]:
        print(" ", ship["name"], ship["hull"]["label"],
              ship["condition"]["label"])

Results come back in the order you asked for them. Every entry carries clan_id at the top level whether it resolved or not, so you can match responses to requests without relying on position.

Response

Top level

Ship object

Condition keys

anchored, preparing_deploy, preparing_dss, deployed, escorting_dss, drydocked, reserve. You may also see supporting_operation on older ships; nothing new enters that state. Match on key, not label. Labels are display copy and can be reworded.

Those are the keys a ship reports. The condition_key inside fleet_status.by_condition is a different, smaller vocabulary: it carries preparing, which no individual ship ever reports, and it never carries reserve. Don't build one lookup table and use it for both.

fleet_status

This object exists to draw the status bar players see on the clan's hangar page, so it is shaped for that job rather than for arithmetic.

Hull

Segments never reach zero. A wrecked ship reads 1, "Critical".

Hull Breaches

1. The forced flag, for current state

Every ship's condition object carries forced. It is true only when a hull breach put the ship where it is, and false for every voluntary drydock.

"condition": {
  "key": "drydocked",
  "label": "Drydocked",
  "location": "Freedom Alliance Orbital Hub",
  "forced": true
}

Use this when you poll on a slow cycle, or when you want to show which ships are currently out of action through damage rather than by choice. It stays true for as long as the emergency repair lasts, so you cannot miss it.

2. The activity feed, for the moment it happened

A breach writes a distinct event with event_type of hull_breach. Watch for it if you want to announce breaches as they occur rather than report standing state.

for event in hangar["activity"]:
    if event["event_type"] == "hull_breach":
        print(event["ship_name"], "breached at", event["location"])

Bear in mind the feed only carries the last 10 events for the clan. A busy clan during an operation can push a breach out of that window between two polls, which is exactly why the forced flag exists alongside it. If you want both reliability and timeliness, watch the flag for state and the feed for the announcement.

Battle Groups

A Battle Group is a named formation of a clan's ships that its leadership commands as one order. Clans use them to organise a fleet into task forces. The formation list arrives at the top level, and every ship tells you which one it belongs to, so you can present a clan's fleet grouped the way the clan itself groups it.

ship_count counts what you can see. It is derived from the same ships array this response carries, not from the clan's raw membership. A ship on a class we haven't published yet is withheld from the array, and it is left out of the count too, so the two always agree. Group the ships array yourself and you will get the same numbers.

Super Destroyers can never join a formation, so battle_group is always null across personal_ships. The key is still present on every ship in both arrays, so you can walk either one without branching.

groups = {g["id"]: g for g in hangar["battle_groups"]}
for ship in hangar["ships"]:
    bg = ship["battle_group"]
    if bg:
        print(bg["name"], ship["name"], ship["condition"]["label"])

Formations come and go. A disbanded Battle Group leaves the list immediately and its ships' battle_group goes null, so don't treat an id you saw yesterday as permanent. Key your own storage on the id while it is present, and drop it when it stops appearing.

Crew and Activity

Every crew list uses the same row shape: username and public_id. Captains and first officers add ship_id and ship_name; commodores add battle_group_id and battle_group_name. Profile links are /user/<public_id>.

• leaders: clan leadership, deduplicated.
• shipmasters: clan-wide fleet authority.
• commodores: authority over one Battle Group. A clan can have several, one person can hold more than one, and a formation can have up to three. Also repeated inside each entry of battle_groups, so you can read them either way round.
• captains and first_officers: per-ship roles.

Activity events carry ship_id, ship_name, class_display, event, event_type, condition_key, at (ISO 8601), location, location_kind, location_opcode, notes, and an actor of username plus role_label.

On identifiers

public_id is the only user identifier this API returns. Discord IDs are deliberately absent, and users who have been removed from public view won't appear in any list. Don't key your storage on username, because people rename. Key on public_id.

Unavailable Clans and Errors

A clan that can't be shown still returns HTTP 200 with available: false and a reason. This is on purpose: you can keep a clan in your poll list through a disbandment without special-casing an error.

Actual errors

Bad input returns HTTP 400 with an error code and a human-readable detail:

{"error": "invalid_id",   "detail": "Clan IDs must be integers; got 'abc'.",  "max_ids": 25}
{"error": "too_many_ids", "detail": "Requested 26 clans; the limit is 25 per call.", "max_ids": 25}
{"error": "missing_ids",  "detail": "Pass ?ids= with a comma-separated list of clan IDs.", "max_ids": 25}

Over-length lists are rejected.

Rules of the Road

• Please send a real User-Agent. Something like PutYourAppNameHere/1.0 (+contact: yourdiscordnamehere). If your traffic ever looks odd, we may block it if we can't figure out who you are from your User-Agent string.
• Poll no faster than every 60 seconds. Responses are cached for 60s, so anything quicker returns identical bytes. Every 2 to 5 minutes is plenty; ship conditions move on a one-minute tick and hull on five.
• Use the batch endpoint when watching more than one clan, and keep it to one call per cycle rather than firing several in parallel.
• Rate limits: 60 requests/minute on the single-clan endpoint, 20/minute on batch. Exceeding them returns 429. Back off and retry rather than hammering.

This API is read-only and returns only data already public on the site. It may be changed, updated, or switched off at any time. We make no uptime guarantees.