Summer 2 Python Assignment: OpenWeatherMap Weather Forecast
Friday, July 19, 11:59pm via Moodle. Look for the "Python Programming: OpenWeatherMap API Assignment" link.
The assignment for this year's Summer Session 2 Python module involves using the OpenWeatherMap weather API and simple analytics on forecast weather data. You will be asked to:
temp.csv, one line per city.
In order to use the OpenWeatherMap API, you must first register with the site to obtain a free developer's API key. This key is required for every query you make, to track your use of the site.
It may take a few hours for your API key to activate. Wait at least a day before checking on API calls returning code 401 (Invalid API key.)
Take careful note of the query restrictions placed on free accounts. You are only allowed to make 60 queries per minute, after which queries will be blocked. You should plan your development accordingly.
As an example, here is some simple Python code that gets the four-day
forecast for Peterhead, Scotland. You will want to focus on
the forecase API call, since this will contain the
information you need to build your 4-day forecasts. I've obfuscated my
API key, so you would insert your own key as a string for
the api_key variable.
Replace XXXXX with the API key you were issued by the
OpenWeatherMap site. The variable data will contain
Python-encoded representations of numerous fields with information on
Peterhead and its forecasted
weather. data[ 'list' ] is just one of the
fields available. You can print data to view the
different dictionary entries available. Note that OpenWeatherMap
returns a 40-element array data[ 'list' ] with
entry 0 corresponding to the first three-hour block, and entry 39
corresponding to the last three-hour block. Also note that the
default temperature units are Kelvin, which is why the values seem
high (286.11 Kelvin is 55.33 Fahrenheit or 12.96 Celsius.) More
information about the 5-day/3-hour forecast call is available
on OpenWeatherMap's API
reference. Finally, note that we use the geo API to
convert a city's name and country into a latitude and longitude needed
to identify the location were we want to query a weather forecast.
Below is a list of the 16 cities to query. We have tested the name and
country of each city to ensure OpenWeatherMap's API will return proper
data if you specify use the geo API to convert the city
to a latitude and longitude, then use the latitude and longitude to
retrieve the 5 day/3 hour forecast data.
You can hard-code these city and country names directly into your program. There is no requirement that you provide any mechanism to enter them into the program as it runs. We will modify your code as needed if we want to run it on cities that are different than the ones we gave you to test with.
The 4-day forecast you build starts at midnight tomorrow, and includes tomorrow plus the three days following tomorrow. For example, if the date when you run your program is August 23, you would provide a 4-day forecast for August 24 through August 28.
OpenWeatherMap always returns dates and times in UTC (Coordinated Universal Time or Greenwich Mean Time.) This means that, technically, to get the proper forecast for a general location, you would first need to convert all dates and times from UTC to the timezone of the location, then use these to identify the first three-hour block corresponding to 12am-3am in the target city's timezone.
Unfortunately, this is non-trivial for a variety of reasons: certain countries define non-standard time zones, daylight savings time is used in some countries (or parts of countries) but not others, and so on. Because of this, we will allow you to use the date and time OpenWeatherMap returns as though it were properly corrected for the timezone of the city you query. This means the 4-day forecast will most likely be offset forward some number of three-hour multiples, but for the purpose of the assignment, this is not critical.
To find the first block that corresponds to the beginning of
"tomorrow", start at
block data[ 'list' ][ 0 ] and look at
the dt_txt field. If it contains the
time 00:00:00, this is the first block for tomorrow. If
it does not contain 00:00:00, move to the next
block data[ 'list' ][ 1 ] and see if
that block's dt_txt
contains 00:00:00. Continue searching forward one block at
a time until you find the first occurrence of midnight
(00:00:00). This identifies the block at the beginning of
tomorrow. Each day is eight blocks long (eight 3-hour blocks spans 24
hours). For example, if you determine block 3 is the start of
tomorrow, you now know that blocks 3–10 cover all of tomorrow,
blocks 11–18 cover all of the day after tomorrow, and so on.
Once you have the eight forecasts for minimum temperatures and the eight forecasts for maximum temperatures for a given day, the minimum you need to extract is the smallest of the eight forecast minimum temperatures. Similarly, the maximum you need to extract is the largest of the eight forecast maximum temperatures. These are the values you should write as \(min_{i}\) and \(max_{i}\) for day \(i\).
After you have completed retrieving data from the OpenWeatherMap site,
write your results to an output file
called temp.csv. Each line will correspond to a single
city, and will contain the following entries
where \(min_i\) corresponds to the minimum forecast temperature in Celsius for \(i\) days in the future, \(max_i\) corresponds to the maximum forecast temperature in Celsius for \(i\) days in the future, and \(min_{\textrm{avg}}\) and \(max_{\textrm{avg}}\) correspond to the average minimum and maximum temperature. In your case, \(i\) ranges from 1 to 4.
Your CSV file must also contain a header line as its first line, formatted as follows.
Below is an example of the output you should create in your CSV file. Note that these are just examples, and are not the ones your program will generate, since it will be run sometime in the future.
Note: Your CSV output must match ours EXACTLY. Pay special attention to the specific wording and order of items in the header line, the exact order of temperatures in the data lines, and the fact that the city and country are separated by comma and space (e.g., "City, Country", NOT "City,Country", with double quotes around the city name and country, NOT without them).
OpenWeatherMap returns temperatures with up to two decimal places of precision. You should ensure that your average minimum and maximum forecast temperatures Minavg and Maxavg are output with EXACTLY two decimal places of precision ("exactly" means if the temperature is 29.2, you would write 29.20 to your output file, NOT 29.2).
When you examine your file temp.csv to validate its
content, DO NOT DO IT IN EXCEL. Excel will truncate decimal
values. This means if the file contains 12.00, it will
appear as 12 in Excel, and you will think your program is
not generating two decimals of precision properly. If you load
temp.csv into a text editor like Notepad, you will most
likely see 12.00, exactly as expected. Lesson:
Excel will screw you. Do not trust it.
Your completed program is due by 11:59pm EST on Friday, July 19. Each student must submit their Python code using Moodle. Look for "Python Programming: OpenWeatherMap API Assignment" in the Programming → Python section on Moodle's AA 500 (001) course page.
Although it might seem odd to specify these, here are things we DO NOT want you to submit.
.ipynb file). We
want a Python source code file (a .py file) that we can
run with Python directly from the command line. You can export a
Python from from a Jupyter notebook, if needed.
temp.csv file. It would be
useless to submit a CSV file, because the values it contains depends
on when your program is run.
Your program will be graded on a 101-point scale from 0 to 100. Grading will be performed in two parts.
temp.csv
output file to our known, correct answers.
Please pay special attention to requirement 2. This means you cannot hard-code any temperature values into your program. Each result you write to the CSV file must be based on values parsed directly from OpenWeatherMap's results for the given city and day the program is run.