--- updatedAt: 2025-06-04T20:41:26.000Z agentTools: projectIndex: https://docs.tomorrow.io/llms.txt --- # [Sports] - Optimize your merchandising sales with historical weather data ```python Python import datetime as dt import pytz import requests import matplotlib.pyplot as plt import pandas as pd # set the Historical API POST endpoint as the target URL postHistoricalURL = "https://api.tomorrow.io/v4/historical" # get your key from app.tomorrow.io/development/keys apikey = "add your API key here" # pick the location, as a latlong pair location = [32.74803421602789, -97.09298781655534] # list the fields fields = [ "totalPrecipitationAccumulation", "temperature", "humidity" ] # choose the unit system, either metric or imperial units = "imperial" # set the timesteps, like "current", "1h" and "1d" timesteps = ["1h"] # configure the time frame within the historical bounderies (January 1st, 2015 till 7 days in the past) now = dt.datetime.now(pytz.UTC) startTime = '2021-09-15T12:00:00.000Z' #(now + dt.timedelta(days=-430)).isoformat() endTime = '2021-09-16T12:00:00.000Z' #(now + dt.timedelta(days=-422)).isoformat() # specify the timezone, using standard IANA timezone format timezone = "US/Central" # request the historical timelines with all the body parameters as options body = {"location": location, "fields": fields, "units": units, "timesteps": timesteps, "startTime": startTime, "endTime": endTime, "timezone":timezone} response = requests.post(f'{postHistoricalURL}?apikey={apikey}', json=body) data = response.json() data = data["data"]["timelines"] # create a dataframe with the response values df = pd.DataFrame() for item in data: item = item["intervals"] df = pd.json_normalize(item) df.rename(columns={'startTime': 'DateTime'}, inplace=True) df.Date = pd.to_datetime(df['DateTime'], format='%Y-%m-%d %H:%M:%S') # bring your own data (we used mock data below) apparelSales = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 514, 6934, 48124, 542, 231, 728, 5156, 789, 126, 0, 0, 0, 0, 0] foodSales = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 514, 6934, 48124, 542, 231, 728, 5156, 789, 126, 0, 0, 0, 0, 0] beverageSales = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 514, 6934, 48124, 542, 231, 728, 5156, 789, 126, 0, 0, 0, 0, 0] employeesStaff = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 50, 120, 320, 120, 100, 300, 100, 60, 20, 20, 20, 0, 0, 0] df['apparelSales'] = apparelSales df['foodSales'] = foodSales df['beverageSales'] = beverageSales df['employees staff'] = employeesStaff # visualize: df.plot(x="DateTime", y=["beverageSales"]) df.plot(x="DateTime", y=["values.temperature"]) plt.show() print('done') ``` ```json Response Example { "data": { "timelines": [ { "timestep": "1h", "endTime": "2021-09-16T07:00:00-05:00", "startTime": "2021-09-15T07:00:00-05:00", "intervals": [ { "startTime": "2021-09-15T07:00:00-05:00", "values": { "humidity": 91.05, "temperature": 20.64, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T08:00:00-05:00", "values": { "humidity": 87.86, "temperature": 21.09, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T09:00:00-05:00", "values": { "humidity": 75.33, "temperature": 23.02, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T10:00:00-05:00", "values": { "humidity": 66.08, "temperature": 24.93, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T11:00:00-05:00", "values": { "humidity": 59.38, "temperature": 26.8, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T12:00:00-05:00", "values": { "humidity": 54.32, "temperature": 28.45, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T13:00:00-05:00", "values": { "humidity": 50.41, "temperature": 29.74, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T14:00:00-05:00", "values": { "humidity": 49.86, "temperature": 29.59, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T15:00:00-05:00", "values": { "humidity": 49.68, "temperature": 29.7, "totalPrecipitationAccumulation": 0.01 } }, { "startTime": "2021-09-15T16:00:00-05:00", "values": { "humidity": 49.93, "temperature": 29.71, "totalPrecipitationAccumulation": 0.03 } }, { "startTime": "2021-09-15T17:00:00-05:00", "values": { "humidity": 48.88, "temperature": 29.88, "totalPrecipitationAccumulation": 0.03 } }, { "startTime": "2021-09-15T18:00:00-05:00", "values": { "humidity": 47.98, "temperature": 29.99, "totalPrecipitationAccumulation": 0.03 } }, { "startTime": "2021-09-15T19:00:00-05:00", "values": { "humidity": 51.58, "temperature": 29.35, "totalPrecipitationAccumulation": 0.02 } }, { "startTime": "2021-09-15T20:00:00-05:00", "values": { "humidity": 55.4, "temperature": 28.31, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T21:00:00-05:00", "values": { "humidity": 59.26, "temperature": 27.42, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T22:00:00-05:00", "values": { "humidity": 62.89, "temperature": 26.6, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-15T23:00:00-05:00", "values": { "humidity": 66.65, "temperature": 25.74, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T00:00:00-05:00", "values": { "humidity": 70.83, "temperature": 24.9, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T01:00:00-05:00", "values": { "humidity": 74.72, "temperature": 24.23, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T02:00:00-05:00", "values": { "humidity": 80.08, "temperature": 23.81, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T03:00:00-05:00", "values": { "humidity": 82.16, "temperature": 23.27, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T04:00:00-05:00", "values": { "humidity": 82.64, "temperature": 23.02, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T05:00:00-05:00", "values": { "humidity": 84.23, "temperature": 22.57, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T06:00:00-05:00", "values": { "humidity": 86.24, "temperature": 22.1, "totalPrecipitationAccumulation": 0 } }, { "startTime": "2021-09-16T07:00:00-05:00", "values": { "humidity": 87.37, "temperature": 21.88, "totalPrecipitationAccumulation": 0 } } ] } ] } } ``` # Intorduction **With our Historical endpoint, you can query weather data from January 1st, 2015.** This tool will help you understand what kind of weather events are causing operational disruptions. In this guide, we'll walk you through collecting weather data from Tomorrow.io historical API and bring your own data, to look for correlation between weather events and their impact on merchandise sales. We will use the following weather data: Total precipitation accumulation Temperature Humidity We will use the following Sports operation data: Apparel Sales Food Sales Beverage Sales Employees Staffed # Get your key Before we begin, make sure to [sign up for our platform](https://www.tomorrow.io/weather-api/) and, once logged in, [grab your key](https://app.tomorrow.io/development/keys). # Pick the location In this type of call, you can use any [type of location](https://docs.tomorrow.io/reference/api-formats#locations) In your tool, you can change this per query dynamically, though we chose to only get the weather data for a point location in Dallas, Texas. # List the fields The complete list of available data fields for the Historical API can be found [here](https://docs.tomorrow.io/reference/historical) Note that [some field values might be null](https://docs.tomorrow.io/reference/api-formats#nulls), when there isn't a valid numerical value - like wind direction when there's no wind. # Choose the unit system You can select either the imperial or metric unit system. This applies to all of the fields in the query. The Timeline response payload is lean, flat, and language-agnostic by design, containing only the raw field values as numbers, enums, or [ISO-8601 timestamps](https://docs.tomorrow.io/reference/api-formats#date-and-time). This allows our developers to use it on mobile devices and translate the [field units' representative strings](https://docs.tomorrow.io/reference/data-layers-overview#field-descriptors) to the language of their choice. # Set the timestep The Historical API supports "1h" and "1d" timesteps. In this case, we ask for the '1h' timestep but in case we use the `1d` timesteps, it's important to highlight that whenever a [Min/Max/Avg suffix](https://docs.tomorrow.io/reference/data-layers-overview#field-availability) is not added to the named field, the API will resolve the max value. You can always get super-specific by adding Min/Max/Avg to get the values you want. Moreover, you can add MinTime and MaxTime if you want to know when at the earliest these values will be met in the day interval. # Configure the time frame In this example, we're only interested in getting 25 hours, though most of our data points are supported from January 1st, 2015 to -7 days. Check out the [available data fields](https://docs.tomorrow.io/reference/historical)) of each data point to learn more about its availability. Notice that we used `utc` as the input timezone, but your can use whichever zone you want. # Specify the timezone Regardless of the input timezone, mentioned in the `startTime` and `endTime` timestamps, you can request the returned timestamps to be in a different zone. Just make sure to use the [standard IANA Time Zone Database format](https://docs.tomorrow.io/reference/api-formats#timezone). Since we're going to get the data for Dallas, Texas, we will want it in US/Central timezone. # Request the timelines You can compile all of the query string parameters as part of the options. Don't forget to "enrich" the fields with their [corresponding units](https://docs.tomorrow.io/reference/historical?), # Parse the response into a Datafram We use python Pandas to parse the response directly to a Dataframe object. # Bring your own data Enrich weather data with your own data to find correlations between weather events and your operations. # Visualize your output Create charts to present your analysis and put your findings into action by informing your retail teams about relevant weather trends