Changes to script-facing API

Welcome to the API change log. This is a collection of relevant changes to our game APIs that are approved for use in scripts. This list may not be exhaustive, but we try to note the major relevant changes that may affect/break scripts in here or new APIs that may prove useful.

New entries will be added at the top as they become available.

Alternate endpoint for user info (formerly credits)

• As the /api/credits endpoint has accumulated more and more info about the user (now includes the current coin amount as well), we feel that this should belong under a more fitting name, so it can now be reached under /api/userinfo. The existing endpoint /api/credits will continue to work (and there are no plans to remove it for now) and deliver the same response, however the name is considered legacy so for new developments we encourage API users to switch to / use the new userinfo endpoint.

Added API endpoint for ARR / ARR categories

• The new endpoint /api/v1/aao_categories exposes the mapping of ARR category ID to ARR category name. It is a simple dictionary of integer ID values to names.
• The new endpoint /api/v1/aaos can be used to get information about the current user's ARRs. Included fields are mostly matching their counterparts in the ARR creation / edit form but some specialties exist for special kinds of ARR entries. Fields are (and can be null):
  • id (integer): ID of ARR
  • caption (string): Title of ARR
  • color (string): Hex color for button of ARR
  • text_color (string): Hex color for text of ARR
  • automatic_text_color (bool): If true, text color is automatic
  • hotkey (string): Hotkey of ARR (can be empty for unset)
  • aao_category_id (integer): Linked category, see API above
  • column (integer): ARR column
  • vehicle_classes (Dictionary of string to integer): "normal" ARR fields by name
  • vehicle_types (Dictionary of integer to integer): ARR fields that directly correspond to vehicle type IDs
  • vehicle_type_captions (integer): ARR fields for custom vehicle class names
  • building_ids (array of integer): associated building IDs if set
• The new endpoint /api/v1/aaos/<arrID> can be used to get information about a specific ARR. The contained fields follow the same structure as above.

Added API endpoint for vehicle distances

Added the new endpoint /api/v1/vehicle_distances.json which delivers the current user's vehicles and their total distance counters. The response is a map containing a single key (result). This is an array of objects with vehicle_id, distance_km (total km) and distance_km_30d (last 30 days) values.

Multiple hospital extensions possible in mission / patient requirements

In certain cases (depending on game server and scenario) instead of one patient extension required for all patients in a mission, multiple choices can be present in a mission now (patients will be randomly assigned one of them). Therefore in the global mission list at einsaetze.json the field additional->patient_specializations now is deprecated (it contains a list of all extensions now), instead you can use additional->patient_specialization_captions (array of string) for the individual extension captions or additional->patient_specialization_ids (array of integer) for the integer ID values of the specializations required.

Allow to keep messages unread

Adding the query parameter value peek=1 to opening a message keeps the message thread unread (e.g. https://www.leitstellenspiel.de/messages/1?peek=1)

Changes to mission "generated by" values

• The classic way to determine which building generates which missions has been by the generated_by field present in missions (pointing to the types of buildings) and prerequisites->building_specializations (pointing to specific building specializations)
• A new generation codebase now uses a list of possible "mission generation types" on the missions, while each building, extension and specialization may contribute to the list of allowed generation types.
  • Each mission has a list of categories, it can be generated by any building that has at least one of the matching categories. You can find a mission's list of categories in the missions API (einsaetze.json) under the mission_categories key (array of string).
  • Each building has a list of possible mission generation types based on the building itself, active extensions and specializations. You can find the possible list of generated mission types for each building in the normal building API endpoints under the generates_mission_categories key (array of string).
  • To not break older consumers of the API we retain the generated_by field but it will be empty (and without function) if the new system is active.
• You can detect, which kind of generation method is active, by checking if the einsatze.json mission list contains the field mission_categories (new generation is active in this case and generated_by will be an empty string). Similarly the generates_mission_categories field in the buildings API endpoints will only be present, when the new generation style is in use. Active methods will vary from game world to game world and may be changed at our discretion.

New versions of vehicles API (v2 API)

• New versions of the vehicles API endpoints are available at /api/v2/vehicles, /api/v2/vehicles/(id) and /api/v2/buildings/(id)/vehicles respectively
• The basic structure for these is identical to the previous endpoints, but they always return a dictionary and return the result under the *result* key
• Vehicles have new fields to convey the icon actually in use:
  • image_url_static: Vehicle icon to use normally
  • image_url_animated: Animated vehicle icon, e.g. for helicopters and when vehicles drive with special right-of-way
• The endpoint /api/v2/vehicles is subject to paging to avoid putting too high of a load on the server leading to timeouts on the client end:
  • Page size is given by an optional query parameter limit (default/maximum at 10000)
  • Vehicles in the result key may be limited by the limit, they are always sorted by id ascending (inspect paging dictionary to figure out if there are more values to query)
  • An additional paging dictionary is present in the result, this has following keys:
    • count_total: number of total vehicles owned by the user
    • first_id: id value of the user's first vehicle (minimum ID)
    • last_id: id value of the user's last vehicle (maximum ID)
    • next_page: Only present if there is a next page; URL to call up the next page
    • previous_page: Only present if there is a previous page; URL to call up the previous page

Extension build finish time in building API

• The /api/building/(id) and /api/buildings endpoints have been extended; the extension info now carries the field available_at with a timestamp containing the finish time, if an extension is not yet available.

Alliance courses info API

• Alliance courses are available under the endpoint /api/alliance_schoolings, the format is identical to the list of user courses available at /api/schoolings.

Update to vehicle graphics paths

• Vehicle graphic URLs have been updated for all vehicles; specifically the image names have changed and all vehicle graphics now reside under the path /images/vehicles/ instead of directly under /images/. The old vehicle graphics URLs will still be valid for a while, but we will remove them in autumn 2022, so if you use hard-coded URLs, please adjust accordingly.

  Overview of changed vehicle paths (click to expand)

  old path	new path
  images/airtanker.png	images/vehicles/red_airtanker.png
  images/ambulance.png	images/vehicles/red_ambulance.png
  images/ambulance_sonderrechte.png	images/vehicles/red_ambulance_2.png
  images/civil_car.png	images/vehicles/red_civil_car.png
  images/civil_car.png	images/vehicles/red_civil_car_2.png
  images/container_empty.png	images/vehicles/red_container_empty.png
  images/container_full.png	images/vehicles/red_container_full.png
  images/crane.png	images/vehicles/red_crane.png
  images/crane.png	images/vehicles/red_crane_2.png
  images/heli.png	images/vehicles/red_helicopter_rescue.png
  images/heli.png	images/vehicles/red_helicopter_rescue_2.png
  images/heli2.png	images/vehicles/red_helicopter_rescue_2.png
  images/helicopter_fire.png	images/vehicles/red_helicopter_fire.png
  images/ladder.png	images/vehicles/red_ladder.png
  images/ladder_sonderrechte.png	images/vehicles/red_ladder_2.png
  images/mzb_fw_anh.png	images/vehicles/red_boat_trailer.png
  images/mzb_thw_anh.png	images/vehicles/darkblue_boat_trailer.png
  images/pc_drone.png	images/vehicles/blue_drone.png
  images/pc_truck2_fbi.png	images/vehicles/blue_truck_2.png
  images/pc_truck_fbi.png	images/vehicles/blue_truck.png
  images/pheli2_1.png	images/vehicles/green_helicopter.png
  images/pheli2_1.png	images/vehicles/green_helicopter_2.png
  images/pheli2_2.png	images/vehicles/green_helicopter_2.png
  images/pickup.png	images/vehicles/red_pickup.png
  images/pickup_sonderrechte.png	images/vehicles/red_pickup_2.png
  images/plane.png	images/vehicles/red_plane_rescue.png
  images/police.png	images/vehicles/blue_car.png
  images/police.png	images/vehicles/green_car.png
  images/police.png	images/vehicles/green_car_2.png
  images/police2.png	images/vehicles/blue_car_2.png
  images/police2.png	images/vehicles/green_car_2.png
  images/police_bike.png	images/vehicles/green_bike.png
  images/police_boat.png	images/vehicles/green_boat.png
  images/police_bucket.png	images/vehicles/green_helicopter_bucket.png
  images/police_bus.png	images/vehicles/green_bus.png
  images/police_bus.png	images/vehicles/green_bus_2.png
  images/police_civil_car.png	images/vehicles/green_civil_car.png
  images/police_civil_car.png	images/vehicles/green_civil_car_2.png
  images/police_dogs.png	images/vehicles/green_dogs.png
  images/police_motorrad.png	images/vehicles/green_motorcycle.png
  images/police_motorrad2.png	images/vehicles/green_motorcycle_2.png
  images/police_pickup.png	images/vehicles/green_pickup.png
  images/police_pickup_sonderrechte.png	images/vehicles/green_pickup_2.png
  images/police_sprinter.png	images/vehicles/green_sprinter.png
  images/police_sprinter.png	images/vehicles/green_sprinter_2.png
  images/police_sprinter_sonderrechte.png	images/vehicles/green_sprinter_2.png
  images/police_suv.png	images/vehicles/green_suv.png
  images/police_suv_sonderrechte.png	images/vehicles/green_suv_2.png
  images/police_trailer.png	images/vehicles/green_trailer.png
  images/police_truck.png	images/vehicles/green_truck.png
  images/police_truck.png	images/vehicles/green_truck_2.png
  images/policechief_police.png	images/vehicles/blue_car.png
  images/policechief_police2.png	images/vehicles/blue_car_2.png
  images/quad.png	images/vehicles/red_quad.png
  images/rescue_boat.png	images/vehicles/red_boat.png
  images/rescue_motorcycle.png	images/vehicles/red_motorcycle.png
  images/rescue_motorcycle2.png	images/vehicles/red_motorcycle_2.png
  images/sprinter.png	images/vehicles/red_sprinter.png
  images/sprinter.png	images/vehicles/red_sprinter_2.png
  images/sprinter_sonderrechte.png	images/vehicles/red_sprinter_2.png
  images/tanker.png	images/vehicles/red_tanker.png
  images/tanker_sonderrechte.png	images/vehicles/red_tanker_2.png
  images/trailer.png	images/vehicles/red_trailer.png
  images/trailer_thw.png	images/vehicles/darkblue_trailer.png
  images/truck.png	images/vehicles/red_truck.png
  images/truck.png	images/vehicles/red_truck_2.png
  images/truck_sonderrechte.png	images/vehicles/red_truck_2.png
  images/truck_sonderrechte_thw.png	images/vehicles/darkblue_truck_2.png
  images/truck_thw.png	images/vehicles/darkblue_truck.png
  images/wawe_bgr.png	images/vehicles/green_water_cannon.png
  images/wawe_bgr_s.png	images/vehicles/green_water_cannon_2.png
  images/clearing_unit_green.png	images/vehicles/green_plow.png
  images/clearing_unit_green_2.png	images/vehicles/green_plow_2.png
  images/police.png	images/vehicles/green_car.png
  images/police2.png	images/vehicles/green_car_2.png
  images/police_bike.png	images/vehicles/green_bike.png
  images/police_sprinter.png	images/vehicles/green_sprinter.png
  images/police_sprinter.png	images/vehicles/green_sprinter_2.png
  images/police_trailer.png	images/vehicles/green_trailer.png
  images/police_truck.png	images/vehicles/green_truck.png
  images/police_truck.png	images/vehicles/green_truck_2.png
  images/tanker.png	images/vehicles/red_tanker.png
  images/tanker_sonderrechte.png	images/vehicles/red_tanker_2.png
  images/trailer.png	images/vehicles/red_trailer.png
  images/truck.png	images/vehicles/red_truck.png
  images/truck_sonderrechte.png	images/vehicles/red_truck_2.png
  images/wawe_bgr.png	images/vehicles/green_water_cannon.png
  images/wawe_bgr_s.png	images/vehicles/green_water_cannon_2.png

Building specializations

• Building specializations (first released on missionchief.co.uk) have been added to the /api/buildings endpoint under the optional "specializations" element. Properties are:
  • caption
  : localized name of specialization type
  • type
  : internal / universal name of specialization type
  • active
  : boolean to see if specialization is done building and active

---