The GlobalTuners web API is still in development. We will try to keep newer versions backwards compatible, but can not guarantee that this is always possible. In the current version, the command structure is quite consistent, but the response format is not. The API can be accessed through a HTTP GET request to https://www.globaltuners.com/api.php with a properly formatted query string. The possible operations are described below. All responses start with either the character 'O' (capital o) or 'E', followed by a new line character (ASCII 10 decimal, 0xA hexadecimal). An 'O'-response indicates a successful operation, an 'E'-response indicates an error. If an error response is received, the following line may contain an error message. The format of the 'O'-response depends on the actual operation. In case another character is received, an error condition should be raised, preferably quoting the entire response for debugging purposes. === Authentication === Some operations need to be authenticated by a valid GlobalTuners account with proper permissions. An authentication method is always in addition to another operation. Some commands do not need any kind of authentication. There are two ways to authenticate against the GlobalTuners system - direct authentication and session authentication. If the authentication fails for some reason, an error reply is sent and the actual operation is not executed. Direct authentication is always used at least once every session. The GlobalTuners account name and hashed password are sent to the API server. * Query string: ?login=[ACCOUNTNAME]&password=[PASSWORDHASH]&salt=[SALT] * [ACCOUNTNAME] is the properly URL-encoded GlobalTuners account name * [PASSWORDHASH] is the doubly-hashed password, eg SHA1( MD5([PASSWORD]) + [SALT] + [ACCOUNTNAME] ) - without any spaces, the + sign indicates a string concatenation, SHA1() is the SHA1-hash function, MD5() is the MD5-hash function. * [PASSWORD] is the plain-text password * [SALT] is a random string (may be empty, but not recommended) to improve security by enhancing the hash value complexity Session authentication uses a session key. The session key is optained by calling the 'login' operation using direct authentication (see below). The advantage of session authentication is that there's no need to send the actual password with every request, thus reducing the query string complexity and improving security. In addition, the obtained session key can be used to authenticate against the main website or hub server. It is possible to either send the session ID in the query string, or as a cookie. * Either query string: ?S=[SESSIONID] * Or cookie: GlobalTuners=[SESSIONID] * Where [SESSIONID] is the 32-byte hexadecimal session ID obtained from the 'login' operation. === Supported operations === login operation Request a session ID for session based authentication. The obtained session ID can be used to authenticate against the website or the API. * Query string: ?A=login * Response: [SID] * Where [SID] indicates the session ID to be used in any further transactions. * The session ID is a 32-character hexadecimal string * The session ID may expire after a few hours of inactivity * Like all responses, a successful response is prefixed by O\n (a capital o, followed by a newline - ASCII 10 or 0xA - character), see above. websetcookie operation Sets the session ID as a browser cookie and optionally redirects the client. For this command to work, it is required that session authentication is used. This operation can be used to open a website session with the same credentials as have been used on the API. It is also possible to just automate the login process. * Query string: ?A=websetcookie * Or, to redirect on success: ?A=websetcookie&R=/[PATH] * Where R=/[PATH] is optional, and should only be used if it the client should be redirected to another page on the GlobalTuners site * Where [PATH] is the [PATH] in https://www.globaltuners.com/[PATH] * Response: * Either a HTTP redirect code (if the R variable is specified) * Or an empty success reply (O\n) logout operation Invalidates the current session ID, to destroy the current login session. It will not erase the client side cookie! No error will be raised if the session has expired or does not exist. * Query string: ?A=logout * Response: empty success response checklogin operation Verifies the credentials or session ID - can also be used to prevent the login session from expiring. * Query string: ?A=checklogin * Response: either an empty success response if the credentials are valid, or an error response otherwise. receiver_name operation Returns the name of the receiver indicated by the R variable * Query string: ?A=receiver_name&R=[RID] * Where [RID] is the receiver ID number * Response: the receiver name, with all \r and \n characters removed, terminated by a \n character. receiver_list operation Returns a list of receivers that are currently online and accessible using the specified credentials * Query string: ?A=receiver_list * Response: * A newline (\n or ASCII 10 decimal or ASCII 0xA hexadecimal) separated list of receiver ID numbers and names * All \r and \n characters are removed from the receiver names * Receiver ID numbers and names are separated by a single space character, eg [ID] + ' ' + [Name] * The receiver name may contain spaces receiver_open operation Requests a session key for a specific receiver. Also returns the connection information. * Query string: ?A=receiver_open&R=[RID] * Where [RID] is the receiver ID number * Response: [IP] + ' ' + [PORT] + ' ' + [KEY] * Where ' ' is a single space character, + indicates a string concatenation * [IP] is the IP address or hostname of the receiver server or relay server * [PORT] is the port number to connect to * [KEY] is the session key for accessing the receiver receiver_status operation Requests the receiver status code * Query string: ?A=receiver_status&R=[RID] * Response: the receiver status code, 0=offline, 1=online, anything else indicates an error or offline status receiver_fullstatus operation Requests extended status information from the receiver * Query string: ?A=receiver_fullstatus&R=[RID] * Response: a PHP serialized string, containing a nested associative array with all status information from the receiver * 'ID' => receiver ID number, * 'Sitename' => receiver name, * 'Status' => receiver status code, * if the receiver is not offline: * 'Users' => an array, containing associative arrays for all connected users, * 'Connections' => an array, containing associative arrays for all direct incoming connections mynodes operation Requests a list of nodes owned by the authenticated user * Query string: ?A=mynodes * Response: * A newline (\n or ASCII 10 decimal or ASCII 0xA hexadecimal) separated list of receiver GUID code and names * All \r and \n characters are removed from the receiver names * Receiver GUID codes and names are separated by a single space character, eg [GUID] + ' ' + [Name] * The receiver name may contain spaces * The receiver GUID code is a 32 character hexadecimal string * The GUID code can be used to set up the initial radioserver configuration file (eg NodeID=[GUID])