Commute Time Augmentation Guide

The commute time augmentation "augments" your data in One Model with commute times and distances between home and office locations. This data is obtained by sending zip code pairs (employee home and office locations) to the mapquest API and returning time and distance for both the AM and PM commute. As your data (zip code pairs) will be shared outside of the One Model platform, please consult your internal stakeholders before proceeding.

Watch the video - Commute Time Augmentation Guide.

Pre-work

The first step in creating a commute time augmentation is preparing the necessary data.

A data destination of type "One AI" that generates a single file must be created. 

  1. From the Data menu on the top navigation bar, select Destinations
  2. Click Add Data Destination and select One AI from the dropdown
  3. Assign a Display Name such as "Commute Time" and Save
  4. Select the + icon on the row for the destination you just created and select Query Source
  5. Assign a file name and click Save and Explore Query 
  6. Create an Explore query that follows these guidelines:
    1. Must contain a headcount metric and time selection
      1. Headcount (EOP) is the most commonly selected headcount metric
      2. Today is the most commonly selected time selection
      3. You can apply whatever filters you desire
    2. a unique person identifier - person_id in the image above
    3. a date formatted as a date - we recommend you use one.timeperiods.date column as shown in the image
    4. a home zip code - home_zip_code in the image above
    5. an office zip code - work_zip_code in the image above
  7. Click the Run query button if you have not
  8. Hover over the pin icon above the table and select Update Data Destination Query
  9. From the Data menu on the top navigation bar, select Destinations again
  10. Run the data destination by clicking the Run Data Destination icon (Play symbol) on the row for the destination you just created
  11. Validate that the destination ran successfully by clicking the View Data Destination History icon on the row for the destination you just created

Configuration

Click the Data tab and select Augmentations from the dropdown to navigate to the Augmentations page.

Once on the Augmentations page, click the “Add Data Augmentation” button to prompt a new augmentation.

Enter a name into the Display Name field and then select “Commute Time” from the dropdown menu under “Augmentation Type.”

Select the appropriate data destination from the “Select Data Destination” dropdown menu. This should be the destination you created in your pre-work step.

Once you have selected the appropriate data destination, click “Refresh data from selected data destination” to ensure that the data destination is up to date.

Once these steps are completed, the following configuration options should be displayed:

The following selections should be associated with the corresponding column from the data destination:

  • Person ID

  • Employee Zip Code

  • Office Zip Code

  • Sample Date

Country, Arrive By, and Leave At are optional. If nothing is selected for these options, the following defaults will be used:

  • Country: United States of America (US)

  • Arrive By: 09:00

  • Leave At: 17:00

Although there is not a control for it, a custom date can also be passed by selecting "Show YAML Template" and entering the following, replacing the MM/DD/YYYY with a valid date. By default, today's date is used.

traffic_date: "MM/DD/YYYY"

Once you have filled in your configurations, click the “Create” button at the bottom of the Add Augmentation screen.

Run and Review

Now that the augmentation has been created, find it in the Augmentations list and click “Run” to kick off a run that will return the commute data.

Click “Runs” to see the status of the run. Depending on the volume of data, it can take some time to run. When it is complete, you will see an orange “Pending” bar. Select the Pending bar to inspect the results.

Select the “Results Explorer” tab to review the results.

 

The columns returned are as follows:

  • person_id - the employee identifier you configured

  • arrive_by_commute_time_seconds - the AM commute time in seconds

  • leave_at_commute_time_seconds - the PM commute time in seconds

  • arrive_by_commute_time_formatted - the AM commute time formatted as time

  • leave_at_commute_time_formatted - the AM commute time formatted as time

  • arrive_by_distance - the AM distance of the route in miles

  • leave_at_distance - the PM distance of the route in miles

  • sample_date - the sample date you configured

  • aug_name - the name of the augmentation

  • aug_id - the ID of the augmentation run

Note that there is a row in the screen shot that displays errors. If invalid zip code combinations are passed or if zip codes are incorrectly formatted, you will receive these errors.

Deploy and Model

If the data you received looks sensible and you would like to leverage it in One Model, please reach out to your Customer Success contact. Results are deployed from the "Results Explorer" tab by selecting the blue “Deploy” button in the bottom right corner. Doing so loads the data into a data source where it can be accessed by your processing script. A One Model Data Engineer can then model it for use in Explore and Storyboards.

Technical Notes

The commute time augmentation leverages the Mapquest Directions API. Documentation about this API can be found at the following links:

The commute time augmentation pulls “time” and “distance” at both the “arrive by” and “leave at” times.

Note: Data is sent and received at a zip code to zip code level, not a per employee level. Person identifier is not sent to Mapquest. The mapping from person to zip codes is performed on the One Model end.

Values passed to the API are as follows:

Mapquest Parameter

Value

dateType

0 (Specific Date & Time)

useTraffic

True

timeType

Arrive By is 3 and Leave At is 2

to

Office Zip Code

from

Employee Zip Code

country

Country or defaults to US if not specified

date

defaults to today unless overridden in YAML

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.