Files upload and download API

The ACARS system is capable of simple file transfer. Given the purpose of the system, the transfer is never directly station to station, but always in terms of a store-and-forward buffer.

All files of a (virtual) company are isolated in their own namespace, based on the three-letter company code. A ground station, such as a dispatch client, "publishes" a file with a name that typically relates it to a specific flight, or a specific route. Airplane clients then request data from their dispatcher, and the system looks in the buffer instead of relaying the request to the dispatch station. This allows dispatchers to pre-publish files and even serve aircraft when the dispatch station is no longer staffed.

File Retrieval

When an ACARS client retrieves a file, it is completely up to the client what to do with it. Some files are suitable for display, others should be saved on a disk and fed into a flight simulator (such as FMS route files). ACARS itself cannot do this, so it depends on your client what you can do here, and usually also on the particular brand of flight sim.

Server Storage and Web Storage

If the central buffer of the ACARS server is used, the published files are erased after 24 hours. Dispatch stations therefore may want to refresh their files in time for their flights to pick them up.

An alternative publication method is to publish the same files on your own web site, and register the common URL prefix of all files with the ACARS server, based on your three-letter company code. This is a manual action by the ACARS server developer, so please contact me (address below) if you want such a URL registered.

The Connection Protocol

The file upload and download commands are sent to the server in the same way as all other ACARS "radio links". Connect to the Web server with the following URL (subject to change):

You need to supply a few data items with each request. You may use either the GET or the POST protocol, or both intermixed.

• logon is the secret string you have received when requesting your ACARS access (use the auto-registration page).
• from contains the callsign of the sending station. For dispatch stations, this must be the three-letter company code, such as KLM. For aircraft, their normal call sign, such as KLM1234.
• to for uploads contains the filename of the target file in the buffer. It is always converted to upper case. For downloads, it contains the company three-letter code.
• type contains the message type, one of "putfile", "putbinfile", or "datareq".
• packet is used to carry the file content in the "put*" commands, and the requested file name minus the company code in the "datareq" command.

Just as for all other ACARS command URLs, you can use either GET or POST or a mix of the two methods to get your arguments across.

Upload example if you use a plain GET protocol URL:
.../connect.html?from=KLM&to=KLM1234.TST&type=putfile&logon=65FGH8&packet=THIS+IS+A+TEST

Note that this example does not use proper URL encoding, though it tends to work in most browsers. Please use whatever works for you. After this command, the server file buffer holds a file KLM1234.TST in the KLM namespace.

This file can be retrieved by:
.../connect.html?logon=4df7ihfd&from=KLM1234&to=KLM&type=datareq&packet=KLM1234.TST

For retrievals, there is no hard relationship between the "from" callsign and the file name, this is purely whatever your ACARS client wants to put there. The company code in "to" is relevant, to select the correct name space.

The file is always returned in simple hex-encoded ASCII, so you can retrieve binary files this way. Every programming language has a function to convert from hex to binary; PHP uses pack() and unpack() for this.

To upload binary files, you need to use exactly the same method as for text files, but with the type=putbinfile command, and supply the file in hex in the "packet" argument.

Typically, file names are related to a flight of the day (KLM2345.TOP for today's flight takeoff perfomance) or to a route (AMSLHR4.ROU for the fourth route from Amsterdam to London as used by this company). It is completely up to you and your simulator what is handy here. There is no standard.