One AI Commute Time Augmentation Guide with Video

The commute time augmentation "augments" your data in One Model with commute times and distances between home and office postal codes. This data is obtained by sending the postal code pairs to the Mapquest API and returning distance and commute time. Postal codes are geocoded to the center of the area. A number of settings are configurable, including whether traffic and return trip are included.

Please note that you are limited to 50,000 Mapquest transactions annually beginning on 10/30/2024. More than one transaction is required for each postal code pair and depends on configuration.

  • The total number of unique postal codes in the two postal code columns (for geocoding)
  • + 1 transaction for each unique combination of (employee_zip_code, office_zip_code) in the data file
  • + If “Include Return Trip” is on, 1 additional transaction for each combo in #2
  • + If “Include Traffic” is on, double 2 and 3

When running the commute time augmentation, your remaining transactions are displayed along with the number of transactions necessary to complete the run. If you select the “Also run Data Destination” option, you won't know if the run will exceed your company's transaction limit until it runs to completion or failure. The results of the run can be found by selecting the completed or errored run and reviewing the "Messages" tab.

Since your data (postal code pairs) will be shared outside of the One Model platform, please consult your internal stakeholders before proceeding.

Jump to 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. We advise that you partner with your Customer Success contact before running the Commute Time augmentation for over 500 employees.
    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
    6. Filter the query down to the smallest result set possible since the number of allowed transactions is limited
  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

Select One AI from the top navigation bar.

NavBar.png
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:

Required Selections

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

  • Person ID

  • Employee Zip Code

  • Office Zip Code

  • Sample Date

Optional Settings

Country, Arrive By, Leave At, and Distance Units 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

  • Distance Units: Miles

Advanced Settings

Although there are not controls for them, a number of additional settings can be applied using Advanced Configuration keys. Setting include_traffic and/or include_return_commute_time to False is a good way to reduce the number of transactions One Model is charged by Mapquest.

  • Traffic Date: by default, traffic is calculated 7 days prior to today's date. Accepted values are any valid date in the past in YYYY-MM-DD format.
    traffic_date: "YYYY-MM-DD"
  • Include Traffic: by default this is set to True. Accepted values are "True" and "False".
    include_traffic: "False"
  • Include Return Commute Time: by default this is set to True. Accepted values are "True" and "False".
    include_return_commute_time: "False"

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.

Note the usage message displayed on the Warning popup. This message informs you of how many transactions you have available for the remainder of the year as well as the number of transactions necessary to complete the run you're executing. Please note that runs that result in an error will not have the number of tokens reduced.

To begin the run, you must "Agree" to your data being sent to Mapquest and click "Confirm".

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 "API call" 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 in the Results Explorer looks sensible and you would like to leverage it in One Model, the results should be 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. Next, please reach out to your Customer Success Lead to arrange for a One Model Data Engineer to model it for use in Explore and Storyboards. Once they have built the appropriate tables and dimensions, you can build metrics and present this data on Storyboards. Remember, your One Model data must reprocess before deployed results will be available for use in Explore or Storyboards. Please plan accordingly.

Rerun and Deploy an Existing Augmentation

In order to rerun and deploy an existing commute time augmentation, follow these steps:

  1. Find the commute time augmentation in the Augmentations list and click Edit.
  2. If you want to use refreshed data, click the "Refresh data from selected data destination" button. You can see how long it’s been since the selected data destination was last run here as well. You can also run the data destination from Data > Destinations if you prefer.

  1. Once the refresh is complete (should only take a few minutes), check that the configuration still looks correct. If so, scroll to the bottom of the screen and click Save
  2. Click Run and Agree and Confirm after reading the warning if you are comfortable. 
  3. Click Runs. Once the augmentation has finished running, it will have a yellow 'Pending’ label. Click it. 
  4. View the results in the "Results Explorer" tab. If everything looks good, click Deploy in the bottom right corner. 
  5. Once your One Model site refreshes, this data will be available 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, unless the include_return_commute_time setting is set to False.

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

Controlled by include_traffic setting - default is True

timeType

Arrive By is 3 and Leave At is 2

to

Office Zip Code (geocoded to the center of the postal code area)

from

Employee Zip Code (geocoded to the center of the postal code area)

country

Country or defaults to US if not specified

date

Controlled by traffic_date setting - default is 7 days prior to today

 

Video - Commute Time Augmentation Guide

This video walks you through the steps to create a One AI Commute Time Augmentation on your One Model site. 

After watching, you will:

  • Understand of what the commute time augmentation is, including its purposes & use of the MapQuest API to provide commute distances & times
  • Be able to create a commute time augmentation, from configuring the data destination to setting up the augmentation & running it successfully
  • See the importance of carefully reviewing the results of the commute time augmentation before deploying
  • Become familiar with how to visualize this data on Storyboards

Run time: >15 minutes

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.