As a project for my Software Documentation class at Carnegie Mellon, I documented a pseudo-web API titled GetMyWeather.
I wrote this as a developer-facing document, explaining how to make an API call to GetMyWeather, the necessary parameters, and how to interpret the results.
The GetMyWeather API provides a weather forecast for a given region and time. It provides the temperature, wind speed, humidity, and chance of precipitation.
Developers who are familiar with HTML and Javascript can use GetMyWeather API for a variety of reasons:
-
Provide weather information on websites and mobile applications.
-
Add parameters to a code base so content is displayed as a function of the weather. This can be useful for sites that make recommendations or predications based on weather.
GetMyWeather's confidence is a function of how far in the future the request is made. Its confidence is high (up to 90 and 100 percent) for 1 and 2 days from the time the request is made. Its confidence decreases as predictions move further out. At 10 days out, GetMyWeather will be only 50 percent confident. After 10 days, the confidence range is significantly less than 50 percent.
A region is determined by providing two values: an origin and a radius. The origin must be given in latitude and longitude. The radius must be given as a numerical value, which can be a decimal value (floating point) and represents meters from the origin.
The time is determined by providing a specific day at a specific time. The day must be provided within month/day/year format and the time must be provided in the hour/minute format using the 24 hour standard.
For example, if you wanted a forecast for Leicester, England within 100 meters of the city on a given day, you would supply the latitude and longitude for Leicester as the origin point, 100 as the value in meters away from the origin, and then the day, month, year, and then the hour and minute.
If you supplied 52.6369, 1.1398 and 100 and 09/07/2018/23/55, you would get a weather forecast within 100 meters of that lat/long on September, 7, 2018 at 11 PM and 23 minutes.
The forecast would encompass the following area within the red circle at 11:23 PM on September 7, 2018.
GetMyWeather provides four weather values: temperature, humidity, wind speed, and chance of precipitation. It also provides a value for its confidence in the predicted forecast, returned as a percentage.
| Value | Returned number | Example |
|---|---|---|
| Temperature | A number that represents degrees Fahrenheit | 72 means 72 degrees Fahrenheit |
| Wind speed | A number that represents kph (kilometers per hour) | 21 means 21 kph |
| Humidity | A number between 0-100 that represents a percentage | 80 means 80 percent humidity. |
| Precipitation | A number between 0-100 that represents a percentage | 50 means 50 percent chance of precipitation |
| Trust | A number between 0-100 that represents a percentage for the confidence in the forecast | 90 means there is a 90 percent degree of certainty for the predicted forecast |
- First 100,000 calls/day: $.01 cent per call
- After 100,000 calls/day contact us at 1-888-alan-getweather
You will need to supply the following parameters:
- ORIGIN: this must be supplied in latitude and longitude
- METERS AWAY FROM ORIGIN: this must be supplied as a numerical value
- TIME: this must be supplied in the month/day/year format and the time in hour/minute format
- API KEY: this must be supplied for all requests
Provide latitude and longitude in the following format:
<NN.NNNN>:<NN.NNNN>
For example, Leicester's latitude and longitude would be supplied as the following:
52.6369:1.1398
BE CAUTIOUS: GetMyWeather must have location data in latitude:longitude format. If you provide incorrect values, you will get the following error message returned:
error: invalid location data supplied
GetMyWeather only uses latitude and longitude. Therefore, you will need to convert a user's location value into latitude and longitude before making a request to the API.
Here is a reference link for converting location data: How do I convert a location into latitude and longitude?
Provide a numerical value that represents the meters away from the origin. The value can be a decimal (floating point) but must greater than zero.
BE CAUTIOUS: A value larger than 200 will result in a trust value of zero. This occurs because a circle encompassing an area greater than 200 meters includes multiple weather systems, making it difficult to provide an accurate forecast.
BE CAUTIOUS: A value less than zero will return the following error message:
error: radius value not within range
Provide a time period in two-digit month, two-digit day, four-digit year, two-digit hour (24hr standard), and two-digit minute, with each value separated by a backslash.
mm/dd/year/hr/minute
For example, 09/07/2018/23/55 is a request on for September, 7, 2018 at 11PM and 23 minutes.
BE CAUTIOUS: Values not provided in this format will return the following error message:
error: date range incorrect
Predicting weather is hard. Use this table to accurately inform your users of the confidence for the forecast.
| Days out | Confidence as a percentage |
|---|---|
| 1 - 2 | 100 % |
| 3 - 4 | 80 % |
| 5 - 6 | 70 % |
| 7 - 8 | 60 % |
| 9 - 10 | 50 % |
| 10 or more | less than 50 % |
Register for a API key at getmyweather.com. To register, you will need a credit card.
BE CAUTIOUS: Without an API key, you cannot make a request. You will receive the following error message:
error: request invalid
//Injecting result into HTML page
<div id='forecast'></div>
//Initializing getWeather
<script type='text/javascript'>
var weatherForecast;
function init(){
weatherForecast =
new getWeather (document.getElementByID('forecast'))
}
</script>
//Calling getWeather
<script async defer
src="https:www.getmyweather.com/getWeather?"
key=<Your_API_Key>&
callback=initMap&
location=<Lat:Long>&
specificity=<Specificity>&
time=<Time>&
>
</script>sample return package
<div class="forecast">
<div class="temperature">78</div>
<div class="windspeed">15</div>
<div class="chanceRain">30</div>
<div class="humidity">80</div>
</div>Email alan.support@getmyweather.com or ask a question on our support forum at getmyweathersupport.com.