API clients can use the Message Queue facility to listen to events on the autorouter platform and react to them. Messages are kept in a queue on the server until they are either received and acknowledged or expire (currently after one week).

Using the messaging API, clients can get the same information that is used by the platform to send email and instant messages on events. In a standard configuration, the user account continues to receive those emails (and instant messages). To disable email and instant messages for your account, please open a support ticket.

Message polling

To retrieve messages, you have to poll the server. It can either be done by a quick poll message returning the messages or an empty array or it can be done as “longpolling” where the request is blocked by the server until either messages become available or a timeout is reached. Which method you use is up to you but you should make sure that after returning from this call, you pause for a reasonable amount of time before issuing the call again to limit network traffic and server bandwidth use.

HTTP GET to https://api.autorouter.aero/v1.0/message

The call as is will return immediately with an array of messages if messages are available. Otherwise it will wait for the timeout which is 30 seconds by default and return an empty array.

Messages are always returned in chronological order with the oldest message first. Only messages that have not been acknowledged yet are returned. When not acknowledging messages, they will expire after a certain duration (currently one week).

The following query parameters are recognized:

• limit
  Default is 10 and denotes the maximum number of messages returned at once. It can be between 1 and 100.
• timeout
  Default is 30 which means 30 seconds. Can be between 0 (return immediately) and 300 seconds.

To determine the number of messages queued, without retrieving them, you can use the following call:

HTTP GET to https://api.autorouter.aero/v1.0/message/count

Message acknowledgement

A message is returned until it either expires (currently after one week) or reception was acknowledged by the API client. Normally you should acknowledge all messages directly after receiving and processing them in your application. Messages are identified by a unique ID (see message format further down). To acknowledge reception of a single message, perform

HTTP POST to https://api.autorouter.aero/v1.0/message/<id>/acknowledge

To acknowledge a series of messages (which can also be just a single message), perform a

HTTP POST to https://api.autorouter.aero/v1.0/message/acknowledge

And in the HTTP POST body, send an array of integers denoting the message IDs.

Messages

Each message is identified by its field type which can take on of the following values. You can ignore messages you are not interested in, however you still have to acknowledge them by their ID, otherwise each subsequent polling request will produce the message again.

Message format

A message is always a JSON object with some generic members and message specific members. The generic members found in every message are as follows:

{
  /* unique message ID, 64-bit unsigned integer, used to acknowledge the message */
  "id": 12345,
  /* the user ID, integer the message applies to */
  "uid": 5484,
  /* timestamp in seconds since the Unix epoch from when the message originates */
  "timestamp": 1474191842,
  /* message type identifier */
  "type": "fplan_status_changed",
  /* message specific data */
  "message": 
  {
    ...
  }
}

The subsequent documentation only contains the message portion. The type member is set to the message name which is the section caption. Note that messages can contain more fields and described here and that you could receive messages of types that are not (yet) documented here. Therefore you have to make sure to handle these cases and also acknowledge messages that you don’t process at this time.

Message type: “fplan_status_changed”

{
  "fplid": 456,
  "status_previous": "filed",
  "status": "departed"
}

Message type: “fplan_filed”

{
  "fplid": 456,
  /* whether it was filed as part of a "bring forward operation */
  "refile": false
}

Message type: “fplan_queued”

{
  "fplid": 456,
  "refile": false
}

Message type: “fplan_rejected”

{
  "fplid": 456,
  "errors:
  [
  ]
}

Message type: “fplan_slot_allocated”

Slots carry additional information about the reason and location. The regulation number is internal to the Eurocontrol system and given for information. The regulation cause field consists of two letters with the first one giving the delay reason according to the codes defined in ICAO Annex 6:

• C: ATC capacity
• I: ATC industrial action
• R: ATC routings
• S: ATC staffing
• T: ATC equipment
• A: accident/incident
• G: aerodrome capacity
• E: non ATC equipment
• N: non ATC industrial action
• M: airspace management
• P: special event
• W: weather
• V: environmental issue
• O: other

The second letter of the first word represents the phase of flight: “D” for departure, “A” for arrival and “E” for enroute.

The second word is one of the IATA delay codes, basically duplicating the information contained in the first word:

• 73: weather enroute or alternate
• 81: ATFM due to ATC enroute demand/capacity
• 82: ATFM due to ATC staff/equipment enroute
• 83: ATFM due to restriction at destination airport
• 84: ATFM due to weather at destination
• 87: airport facilities
• 89: restrictions at airport of departure
• 98: industrial action outside own airline

For each regulation, the internal name, the cause and the target time over (TTO) are given. The regulations are sorted with the most penalizing (i.e. having the biggest effect) first.

{
  "fplid": 456,
  "ctot": "0735",
  "regulations:
  [
    "LSZBA21M"
  ],
  "regcause":
  [
    "CE 81"
  ],
  "ttos":
  [
    {
      /* altitude in flight level */
      "fl": "F090",
      /* target time over in HHMMZ */
      "to": "0746",
      /* ident of the point */
      "ptid": "WIL"
  ]
}

Message type: “fplan_slot_revised”

This informs of a change in slot with a new CTOT. The new CTOT can either be later or earlier and the regulations can change.

{
  "fplid": 456,
  "ctot": "0730",
  "regulations:
  [
    "LSZBA21M"
  ],
  "regcause":
  [
    "CE 81"
  ],
  "ttos":
  [
    {
      "fl": "F090",
      "to": "0741",
      "ptid": "WIL"
  ]
}

Message type: “fplan_slot_cancelled”

{
  "fplid": 456,
  "reasons":
  [

  ],
  "comments":
  [
  ]
}

Message type: “fplan_suspended”

{
  "fplid": 456,
  "comments":
  [
    "SUSPENDED BY DEPARTURE AIRPORT. PLEASE SEND DLA/CHG OR UPDATE TOBT OF THE FLIGHT"
  ],
  "errors":
  [
  ],
  "newrte":
  [
  ]
}

Message type: “fplan_desuspended”

{
  "fplid: 456
}

Message type: “fplan_ssr_assigned”

Note: this message is currently not sent out.

{
  "fplid": 456,
  "ssrcode": "A7360"
}

Message type: “fplan_ssr_updated”

Note: this message is currently not sent out.

{
 "fplid": 456,
 "ssrcode": "A4632"
}

Message type: “fplan_delayed”

{
  "fplid": 456,
  "eobt": 1474191842,
  "previous_eobt": 1474190842
}

Message type: “fplan_cancelled”

{
  "fplid": 456,
  /* reason for the cancellation, can be null */
  "reason": "externally cancelled"
}

Message type: “fplan_broughtforward”

Bringing a flight plan forward is equivalent to cancelling and filing the plan again with an earlier off block time. You first get a cancel message on the current flight plan with a corresponding status change message and then a status change message for a new plan and a fplan_filed message. Finally you get this message with the details of the new plan and the previous plan.

{
  "fplid": 456,
  "previous_fplid": 455,
  "eobt": 1474190842,
  "previous_eobt": 1474191842
}

Message type: “fplan_dpi_updated”

{
  "fplid": 456,
  /* target offblock time in hhmm UTC */
  "tobt": "0607",
  /* taxi time in minutes */
  "taxitime": "0005",
  /* target takeoff time in hhmm UTC */
  "ttot": "0610",
  /* assigned SID */
  "sid": "TOMPI5E"
}

Message type: “fplan_msg_operator”

This message indicates an information regarding a flight plan that is of operational interest and should be made available to the operator without delay.

{
   "fplid": 456,
   /* a human readable message that should be presented to the operator */
   "message": "FF KSTPXAAP\n 141030 EPWWZEZX\n REF FPL-DEXXX-EHGG1045-EPMR-DOF/181214\nWE CAN NOT ACCEPT YOUR FPL DUE TO BELOWE NOTAM:\n\n(C7446/18 NOTAMN\nQ) EPWW/QXXXX/IV/NBO/E /000/999/5208N01846E250\nA) EPWW B) 1811241104 C) 1812162359\nE) BORDER CONTROL IS TEMPORARY RESTORED FOR PERSONS CROSSING POLISH\nBORDER AT AIRPORTS WHICH ARE INTERNAL BORDER WITHIN THE MEANING OF \nSCHENGEN AGREEMENT. INTERNATIONAL FLIGHTS MAY BE PERFORMED ONLY\nTO/FM AERODROMES LISTED IN AIP VFR POLAND PAGE ENR 1.2-6/7. ARRIVALS\nREQUIREW PRIOR ARRANGEMENT WITH AD OPERATOR.)\n\nPLS CHAG YOUR DEST ASAP.\nRGDS/M.OCHWAT\nPANSA/FLIGHT PLAN DATA PROCESSING DEPARTMENT"
   /* the originator of the message as a human readable string, can be empty */
   "originator": "AIS Poland"
}