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.
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).
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:
|
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.
|
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.
The response keys depends on the level and combine-transformations flag 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": {
// 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": { ... },
}
}
"{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
}
}
"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": {
// 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": { ... },
}
}
"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": { ... },
}
"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": {
// 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": { ... },
}
}
"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": { ... },
}
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 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. |
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.
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://gateway.methis.at/report/usage-by-source");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POST, 6);
curl_setopt($curl, CURLOPT_POSTFIELDS, "username=dummy@methis.at&password=loremipsum&start=2016-06-01&end=2016-06-30&level=guid&combine-transformations=0");
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl, CURLOPT_TIMEOUT, 10);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$responseString = curl_exec($curl);
curl_close($curl);
$responseArray = json_decode($responseString, true);
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 }
});
using System.IO;
using System.Web;
using System.Net;
byte[] Data = Encoding.ASCII.GetBytes("username=dummy@methis.at&password=loremipsum&start=2016-06-01&end=2016-06-30&level=guid&combine-transformations=0");
HttpWebRequest Request = (HttpWebRequest)WebRequest.Create("https://gateway.methis.at/report/usage-by-source");
Request.Method = "POST";
Request.ContentType = "application/x-www-form-urlencoded";
Request.ContentLength = Data.Length;
Request.Timeout = 10000;
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 {
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') }
}
If you have any questions about the implementation of this API or found an error please don't hesitate to contact our support team.