Credit Usage By Source

Get a detailed report about the number of consumed credits and executed transformation functions for all your license and guid keys within a selected time period.

Request Url: https://gateway.methis.at/report/usage-by-source
Request Method: POST

Table of Contents

Request Parameters

The API uses the POST request method to send data in the HTTP message body to avoid data being stored in the cache of the web server. A request is valid if all parameters are provided as described below (data type, minimum and maximum length).

POST /report/usage-by-source HTTP/1.1
Host: https://gateway.methis.at

name1=value1&name2=value2
Parameter Mandatory Data Type Min. Max. Description
username required string 1 255 Email address of your account (same as used for the login) used for authentication.
password required string 8 60 Password of your account (same as used for the login) used for authentication.
start required string 10 10 Starting timestamp for the report. The date must be formatted as YYYY-MM-DD and may not be before 2014-01-01 or after tomorrow.
end required string 10 10 Ending timestamp for the report. The date must be formatted as YYYY-MM-DD and may not be before the starting timestamp or after tomorrow.
level required string 4 8 The source level you want to create the report in detail for. Possible values are:
  • customer: Creates a single report for your account with all licenses combined
  • license: Creates the report for each license key of your account
  • guid: Creates the report for each guid key of your account
combine-transformations optional boolean 0 1 Flag if the report should be created for each transformation function or if they should be combined to a single value.
  • 0: Do not combine the transformation functions to get a value for each route (default)
  • 1: Combine all transformation functions to a single value

Response

The API returns all data in valid JSON. A few programming languages include native support for JSON. For those that don't, you can find a suitable library at http://www.json.org. Valid requests always returns all response keys listed below. Depending on the request parameters some response keys may be empty.

HTTP/1.1 200 OK

Server: Apache
Content-Type: application/json; charset=UTF-8
Date: Sun, 15 Dec 2019 14:24:52 GMT
Content-Length: 33
Access-Control-Allow-Origin: *

{"key1":"value1","key2":"value2"}

The response keys depends on the level and combine-transformations flag set in the request.

level is set to customer and combine-transformations is unset
// the username as it is set in the request "{username}": {
// transformation id 1 (take a look on the meta key for more information) "t_id_1": {
// consumed credits of all transformation id 1 executions by all licenses / guids of your account "credits": 123456, // number of transformation 1 executions by all licenses / guids of your account "transformations": 50123
}, // nth transformation id "t_id_n": { ... },
}, // meta information "meta": {
// collection of all transformation functions (ids and route names) "transformations": {
// transformation id 1 "t_id_1": {
// properties of transformation id 1 "route": "/address/search
}, // nth transformation id "t_id_n": { ... },
}
}
level is set to customer and combine-transformations is set
// the username as it is set in the request "{username}": {
// values of all transformation functions are combined in a single value "total": {
// consumed credits (all transformations) by all licenses / guids of your account "credits": 123456, // number of executions (all transformations) by all licenses / guids of your account "transformations": 50123
}
}
level is set to license and combine-transformations is unset
"licenses": {
// first license key of your account "A1B2C-3D4E5-F6G7H-9I0J1-K2L3M": {
// transformation id 1 (take a look on the meta key for more information) "t_id_1": {
// consumed credits of all transformation id 1 executions by this license key "credits": 123456, // number of transformation 1 executions by this license key "transformations": 50123
}, // nth transformation id "t_id_n": { ... },
}, // second license key of your account "M3TH1-51STH-3B35T-0F4LL-D4T45": { ... },
}, // meta information "meta": {
// collection of all transformation functions (ids and route names) "transformations": {
// transformation id 1 "t_id_1": {
// properties of transformation id 1 "route": "/address/search
}, // nth transformation id "t_id_n": { ... },
}
}
level is set to license and combine-transformations is set
"licenses": {
// first license key of your account "A1B2C-3D4E5-F6G7H-9I0J1-K2L3M": {
// values of all transformation functions are combined in a single value "total": {
// consumed credits (all transformations) by this license key "credits": 123456, // number of executions (all transformations) by this license key "transformations": 50123
}
}, // second license key of your account "M3TH1-51STH-3B35T-0F4LL-D4T45": { ... },
}
level is set to guid and combine-transformations is unset
"guids": {
// first guid key of your account "a1b2c3d4-e5f6-g7h8-i9j0k1l2m3n4": {
// transformation id 1 (take a look on the meta key for more information) "t_id_1": {
// consumed credits of all transformation id 1 executions by this guid key "credits": 123456, // number of transformation 1 executions by this guid key "transformations": 50123
}, // nth transformation id "t_id_n": { ... },
}, // second guid key of your account "m3th1551-mply-th3b-35t4-ddr3554w3s0m3": { ... },
}, // meta information "meta": {
// collection of all transformation functions (ids and route names) "transformations": {
// transformation id 1 "t_id_1": {
// properties of transformation id 1 "route": "/address/search
}, // nth transformation id "t_id_n": { ... },
}
}
level is set to guid and combine-transformations is set
"guids": {
// first guid key of your account "a1b2c3d4-e5f6-g7h8-i9j0k1l2m3n4": {
// values of all transformation functions are combined in a single value "total": {
// consumed credits (all transformations) by this guid key "credits": 123456, // number of executions (all transformations) by this guid key "transformations": 50123
}
}, // second guid key of your account "m3th1551-mply-th3b-35t4-ddr3554w3s0m3": { ... },
}

Response Errors

If the request fails the API returns a HTTP status code according to the reason. A reason may be a missing mandatory request parameter, invalid parameter credentials (minimum/maximum length) or invalid API keys. The response body is a valid JSON containing detail information about the reason (except for status code 500).

HTTP/1.1 404 Not Found

Server: Apache
Content-Type: application/json; charset=UTF-8
Date: Sun, 15 Dec 2019 14:24:52 GMT
Content-Length: 71
Access-Control-Allow-Origin: *

{"errorcode":404,"errormessage":"transformation function name invalid"}
HTTP Status Code Reason
401 Unauthorized
The username and password does not match.
404 Not Found
The request path in combination with the request method does not exist.
405 Method Not Allowed
The request method is not allowed for the requested path.
422 Unprocessable Entity
At least one of the given request parameter has invalid credentials (e.g. is mandatory, data type, length).
500 Internal Server Error
An unexpected condition terminated the request.
503 Service Unavailable
The service is currently in maintenance mode and will be alive later.

Code Snippets

We provide some code snippets for multiple programming languages to easily implement this function in your own application. Feel free to copy the code snippets for your preferred programming language.

// the following code requires cURL php extension installed on your server (http://php.net/manual/en/book.curl.php) // initialize a new cURL session and store the cURL handler object $curl = curl_init(); // set the url to which the request will be sent curl_setopt($curl, CURLOPT_URL, "https://gateway.methis.at/report/usage-by-source"); // set the HTTP method to use for the request curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); // set the number of parameters to be sent to the server curl_setopt($curl, CURLOPT_POST, 6); // data to be sent to the server // TODO: set your authentication credentials and customize the request curl_setopt($curl, CURLOPT_POSTFIELDS, "username=dummy@methis.at&password=loremipsum&start=2016-06-01&end=2016-06-30&level=guid&combine-transformations=0"); // set a timeout in seconds for the request curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10); curl_setopt($curl, CURLOPT_TIMEOUT, 10); // return the raw data from the server curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); // execute the previously created cURL session $responseString = curl_exec($curl); // close the cURL session after execution curl_close($curl); // convert the response (string) to an array $responseArray = json_decode($responseString, true); // TODO: process the data in the response array (you may process the data in the response string too)
/* Note: We highly recommend to NOT use this code as it is written here. If you choose JavaScript as your preferred programming language, please change the following code to request your own server (without username and password) and further redirect the request from your own server to the METHIS /API including your account credentials. Otherwise everyone will be able to read your account credentials and use them for their own purpose! */ // the following code requires jQuery JavaScript library (minimum version 1.8.1) added to your website (http://jquery.com/download/) // perform an asynchronous HTTP (Ajax) request jQuery.ajax({
// set the url to which the request is sent url : "https://gateway.methis.at/report/usage-by-source", // set the HTTP method to use for the request type: "POST", // data to be sent to the server (you may use a JavaScript object instead of a string) // TODO: set your authentication credentials and customize the request data : "username=dummy@methis.at&password=loremipsum&start=2016-06-01&end=2016-06-30&level=guid&combine-transformations=0", // type of data that we are expecting back from the server dataType: "JSON", // set a timeout in milliseconds for the request timeout: 10000, // function to be called if the request succeeds success:function(data, textStatus, jqXHR) {
// {object} data The data returned from the server, formatted according to the dataType parameter. // {string} textStatus String describing the status. // {object} jqXHR A XMLHttpRequest object describing the response. // TODO: process the data in the 'data' JavaScript object
}, // function to be called if the request fails error: function(jqXHR, textStatus, errorThrown) {
// {object} jqXHR A XMLHttpRequest object describing the response. // {string} textStatus String describing the type of error occurred. // {string} errorThrown Text portion of the HTTP status, such as "Not Found" or "Internal Server Error". // TODO: process the error occurred
}
});
// the following code uses standard libraries included in Microsoft Visual Studio 2013 or higher using System.IO; using System.Web; using System.Net;
// create an array of bytes representing the data to be sent to the server // TODO: set your authentication credentials and customize the request byte[] Data = Encoding.ASCII.GetBytes("username=dummy@methis.at&password=loremipsum&start=2016-06-01&end=2016-06-30&level=guid&combine-transformations=0"); // create a new web request resource and set the url to which the request is sent HttpWebRequest Request = (HttpWebRequest)WebRequest.Create("https://gateway.methis.at/report/usage-by-source"); // set the HTTP method to use for the request Request.Method = "POST"; // set the request content type Request.ContentType = "application/x-www-form-urlencoded"; // set the number of bytes being sent to the server Request.ContentLength = Data.Length; // set a timeout in milliseconds for the request Request.Timeout = 10000; // try to send all data to the newly created web request resource try {
using(var Stream = Request.GetRequestStream()) {
Stream.Write(Data, 0, Data.Length);
}
} catch (Exception ex) {
// TODO: process the exception thrown (e.g. url not found) return;
} // try to read the response from the web resource try {
HttpWebResponse ResponseObject = (HttpWebResponse)Request.GetResponse(); StreamReader Reader = new StreamReader(ResponseObject.GetResponseStream()); // read the whole response as string and store it String ResponseMessage = System.Net.WebUtility.HtmlDecode(Reader.ReadToEnd()); // TODO: process the data in 'ResponseMessage'
} catch (WebException ex) {
// error occurred, http status code != 200 (e.g. timeout or parameter invalid) if(ex.Status == WebExceptionStatus.Timeout) {
// TODO: process the timeout reached
} else {
// read the response from the web exception HttpWebResponse ResponseObject = (HttpWebResponse)ex.Response; StreamReader Reader = new StreamReader(ResponseObject.GetResponseStream()); // read the whole response as string and store it String ResponseMessage = System.Net.WebUtility.HtmlDecode(Reader.ReadToEnd()); // TODO: process the error response received from the server (stored in 'ResponseMessage')
}
}

Need help?

If you have any questions about the implementation of this API or found an error please don't hesitate to contact our support team.