Retrieves a weather forecast for a given position (longitude/latitude) for the next seven days. Longitude and Latitude of an address can be retrieved by the Address Search method.
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). Please note that all data must be UTF-8 and URL encoded.
| Parameter | Mandatory | Data Type | Min. | Max. | Description |
|---|---|---|---|---|---|
| license | required | string | 29 | 29 | Your license key used for authentication - keep this key secret! |
| guid | required | string | 30 | 40 | Your GUID used for authentication - keep this key secret! |
| requestproof | optional | string | 0 | 1 | set to 1 if you need a unique request identifier as proof for your API request e.g. for VAT checks; default is 0 |
| returnavailablecredits | optional | string | 0 | 1 | set to 1 to get the number of data.mill credits available in your data.mill account; default is 0; a return value of -1 means that you have unlimited credits |
| responseformat | optional | string | 3 | 4 | format of returned data; possible values are xml or json (default) |
| longitude | required | string | 1 | 10 | the longitude of the position for the weather forecast in decimal degrees |
| latitude | required | string | 1 | 10 | the latitude of the position for the weather forecast in decimal degrees |
| day | required | integer | 1 | 7 | set the day for which to retrieve the forecast. 1=tomorrow, 2=day after tomorrow, etc.; min=1; max=7; note that you will receive a forecast for each the next seven days in the "fullresult" response field |
| locale | optional | string | 1 | 10 | The preferred language of elements in the result. The locale must be provided according to RFC 4647 standard (language code). |
| degrees | optional | string | 1 | 1 | C=metric units - degrees Celsius and cm; F=imperial units - degrees Fahrenheit and inch; default is (of course) C |
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.
| Name | Data Type | Description |
|---|---|---|
| description | string | weather description, e.g. "warm and sunny" |
| skyinfo | string | a code to describe the sky: 1 – Sunny 2 – Clear 3 – Mostly Sunny 4 – Mostly Clear 5 – Hazy Sunshine 6 – Haze 7 – Passing Clouds 8 – More Sun than Clouds 9 – Scattered Clouds 10 – Partly Cloudy 11 – A Mixture of Sun and Clouds 12 – High Level Clouds 13 – More Clouds than Sun 14 – Partly Sunny 15 – Broken Clouds 16 – Mostly Cloudy 17 – Cloudy 18 – Overcast 19 – Low Clouds 20 – Light Fog 21 – Fog 22 – Dense Fog 23 – Ice Fog 24 – Sandstorm 25 – Duststorm 26 – Increasing Cloudiness 27 – Decreasing Cloudiness 28 – Clearing Skies 29 – Breaks of Sun Later 30 – Early Fog Followed by Sunny Skies 31 – Afternoon Clouds 32 – Morning Clouds 33 – Smoke 34 – Low Level Haze |
| skydescription | string | description of the sky, e.g. cloudy |
| temperaturedescription | string | description of the temperature, e.g. warm |
| comfortdegrees | string | Comfort level in degrees. This value indicates what the temperature feels like, depending on a variety of environmental factors such as wind speed and humidity. |
| hightemperature | string | high temperature on that day |
| lowtemperature | string | low temperature on that day |
| humidity | string | air humidity as a percentage |
| dewpoint | string | dew point in Celsius/Fahrenheit |
| rainfall | string | amount of rain in cm/inch |
| snowfall | string | amount of snow in cm/inch |
| precepitationprobability | string | Precipitation probability percentage (%). |
| precepitationdescription | string | Precipitation description, e.g. passing showers |
| windspeed | string | windspeed in km/h or mph |
| winddirection | string | wind direction in degrees |
| winddescription | string | description of wind direction |
| iconname | string | icon to use, e.g. partly_cloudy |
| iconlink | string | URL of icon |
| fullresult | array | JSON result for all days, incl. additional infos like uvIndex, etc. |
| forecaststatuscode | integer | status code of request, 0=no error / OK, 10=could not connect to external data service, 11=invalid parameter for degrees (only C and F allowed), 12=invalid day (only 1-7 allowed) |
| forecaststatusmessage | string | status message in english |
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 license key and/or GUID key is missing, invalid or inactive. |
| 402 | Payment Required Your /data.mill credit quota is exceeded. You need to get more credits. |
| 403 | Forbidden You need to accept all required agreements of this function to be able to use it. |
| 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. |
| 412 | Precondition Failed At least one of the given request parameter has invalid credentials (e.g. data type, length). |
| 428 | Precondition Required At least one of the mandatory request parameter is missing or has an empty value. |
| 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. |
The batch mode allows the execution of thousands of records (limited to 5,000) combined in a single request. This API endpoint as described above uses the single mode execution of records. To use the batch mode you need to combine all request parameters above (excluding license and guid) as array, where each array element represents a single record. This array is converted to a valid JSON string and set as value of the new request parameter called batch. The response of the batch mode is a valid JSON which contains the result for each record set in the request. The response keys of each result element are the same as for the single request mode described above.
In order to enable the payment of different currencies, we have introduced a system based on credit balance as payment for the individual functions. The currency of the account is called /data.mill credits. To use the functions, the account must be charged in advance. If the credit price of a function is higher than the current balance, the function can not be executed. The credits will be deducted from your balance after executing the function. Your credits have no expiration date.
We provide some code snippets for multiple programming languages to easily implement this function in your own application. The code snippets below uses the single request mode. If you want to use the batch mode instead of the single mode you need to modify the snippet. Feel free to copy the code snippets for your preferred programming language.
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.datamill.solutions/address/weather/forecast");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POST, 10);
curl_setopt($curl, CURLOPT_POSTFIELDS, "license=&guid=&requestproof=&returnavailablecredits=&responseformat=&longitude=&latitude=&day=&locale=°rees=");
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://api.datamill.solutions/address/weather/forecast",// 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: append your API keys and value(s) and don't forget to urlencode() them data : "license=&guid=&requestproof=&returnavailablecredits=&responseformat=&longitude=&latitude=&day=&locale=°rees=",// 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("license=&guid=&requestproof=&returnavailablecredits=&responseformat=&longitude=&latitude=&day=&locale=°rees=");
HttpWebRequest Request = (HttpWebRequest)WebRequest.Create("https://api.datamill.solutions/address/weather/forecast");
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') }
}
import java.util.List;
import org.apache.http.NameValuePair;
import java.util.ArrayList;
import org.apache.http.message.BasicNameValuePair;
import java.net.URLDecoder;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.DefaultHttpClient;
List<NameValuePair> dataPairs = new ArrayList<NameValuePair>();
dataPairs.add(new BasicNameValuePair("license", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("guid", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("requestproof", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("returnavailablecredits", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("responseformat", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("longitude", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("latitude", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("day", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("locale", URLDecoder.decode("enter value here", "UTF-8")));
dataPairs.add(new BasicNameValuePair("degrees", URLDecoder.decode("enter value here", "UTF-8")));
HttpPost request = new HttpPost("https://api.datamill.solutions/address/weather/forecast");
request.setEntity(new UrlEncodedFormEntity(dataPairs));
try {
// execute the request and read the response string HttpClient client = new DefaultHttpClient();String response = client.execute(request);// TODO: process the data in 'response'
} catch (IOException ex) {
// TODO: process the exception thrown
}
Enter some example data to test the result of the API.
If you have any questions about the implementation of this API or found an error please don't hesitate to contact our support team.