Running Your First Query with the SDK: Retrieving Hourly Wind Gust Data for the Palisades Fire

This tutorial walks through a similar query to the UI tutorial (retrieving hourly surface wind gust data for a utility service territory on January 7–9, 2025) using the Python SDK instead of the web interface. See Getting Started if you do not know how to access the SDK.

Step 1: Import and Authenticate

Import the SDK and create a Session object. You will be prompted for your username and password. Your password will not echo to the console. Once authenticated, a token is cached locally and reused while it remains valid.

from dmsdk import Session, QueryForm

session = Session()

Data Manager username: your_username
Data Manager password: your_password

Step 2: Create a Query Form

Create a QueryForm object, passing in your session. This is the object you will use to configure and submit your query.

form = QueryForm(session)

Step 3: Select a Dataset

Retrieve the list of available datasets and select the one that covers your region, time period, and variables of interest. In this case we are using ens_gfs_020_d03.

print(form.datasets)
form.select_dataset('ens_gfs_020_d03')

Step 4: Select Variables

Retrieve the variable list for the selected dataset, then select near surface wind gusts in mph.

form.get_variables()
print(form.variables)

form.select_variables([('wind gust', 'mph')])

The variable list is a dictionary of hourly and daily variables. Check it to confirm the exact variable name string before selecting.

Step 5: Select Your Area of Interest

For this tutorial we will use a point location. Pass a list of point dictionaries, each with an id, latitude, and longitude.

points = [
    {'id': 'palisades', 'latitude': 34.0522, 'longitude': -118.4437}
]

form.select_points(points)

Replace the coordinates with a location within your service territory. You can pass multiple points in the same list if needed.

Step 6: Set Temporal Parameters

Select hourly time series, set the date range to cover January 7–9, 2025, and set the timezone to PST.

form.select_temporal_resolution('hourly')
form.select_from_datetime('2025-01-07 00:00:00')
form.select_to_datetime('2025-01-09 00:00:00')
form.select_timezone('PST')

Step 7: Set Output Format and Description

Point queries return CSV output. Set a descriptive name for the query.

form.select_output_format('csv')
form.select_description('palisades_wind_gusts_jan2025')

Step 8: Submit the Query

Submit the query and retrieve the Query object, which contains the request_id you will use to check status and download results.

form.submit()
query = form.get_query()
print('Request ID:', query.request_id)

Step 9: Check Status and Download Results

Poll the request status until the query completes, then download the result file to a local directory.

from time import sleep

while True:
    state = session.get_request_state(query.request_id)
    print('Status:', state)
    if state == 'FINISHED':
        save_path = session.save_result(query.request_id, 'results')
        print('Saved to:', save_path)
        break
    sleep(60)

The result file will be saved to a results directory in your working directory. Open the CSV file in your preferred analysis tool. Each row corresponds to a point location and timestep within your selected date range.

Complete Script

from time import sleep
from dmsdk import Session, QueryForm

session = Session()
form = QueryForm(session)

form.select_dataset('ens_gfs_020_d03')
form.get_variables()
form.select_variables([('wind gust', 'mph')])

points = [
    {'id': 'palisades', 'latitude': 34.0522, 'longitude': -118.4437}
]
form.select_points(points)

form.select_temporal_resolution('hourly')
form.select_from_datetime('2025-01-07 00:00:00')
form.select_to_datetime('2025-01-09 00:00:00')
form.select_timezone('PST')

form.select_output_format('csv')
form.select_description('palisades_wind_gusts_jan2025')

form.submit()
query = form.get_query()
print('Request ID:', query.request_id)

while True:
    state = session.get_request_state(query.request_id)
    print('Status:', state)
    if state == 'FINISHED':
        save_path = session.save_result(query.request_id, 'results')
        print('Saved to:', save_path)
        break
    sleep(60)