Analyzing Time Trends with the StreetLight InSight® API

You can compare metrics month over month or year over year to analyze time trends.

When creating analyses with StreetLight InSight®, you can run a series of analyses for months or years for which you want metrics. This lets you to compare metrics over the series of months ("month-over-month") or years ("year-over-year") and analyze changes over time.

Using the StreetLight InSight® API, you can automate the creation of these analyses, rather than manually creating each one. The following recipe provides a sample Python script:

The sample script in the recipe creates a zone set to use, iterates over the specified months or years to create analyses, and saves the results of each analysis as a csv. The steps in the recipe describe the code sample; this article dives deeper into how it works and provides examples. The code samples below describe this recipe.

How to use this recipe

Open the recipe above, then copy the code to a new Python file or notebook to enter your own credentials and customize it for your own purposes.

The following video shows an example of configuring the recipe. The sections below describe configuration in more detail.

Enter your credentials

Set STL_KEY to your API key and set INSIGHT_LOGIN_EMAIL to the email you use to log into StreetLight InSight®. For example:

STL_KEY = 'ABC123xyz456'  
INSIGHT_LOGIN_EMAIL = '[email protected]'

Configure your zone set

The create_zones function creates a new zone set with two zones for neighborhoods in San Francisco. You can use these zones to test out and experiment with this script.

You can edit the parameters of the create_zones function to configure the zones that the script creates. For more information, see Create a zone set.

To use a zone set that you have previously created (in the web app or with the API), edit the zone_set_name in line 16 and comment out the create_zones function call in line 17. This will use the zone set you specify in the functions that create analyses.

Specify date range

Check that the months or years for which you are analyzing time trends can be compared. For more information, see Comparing metrics across time.

If you are analyzing month-over-month

To specify the months to analyze, enter the start_month, start_year, end_month, and end_year variables in lines 20-23.

For example, if we want to analyze month-over-month trends for January through May of 2019, we would enter the following variables:

# define months and years to iterate over
start_month = 1
start_year = 2019
end_month = 5
end_year = 2019

🚧

Due to Rate Limits for the create analysis endpoint, we recommend analyzing 6 months at a time with this code sample.

If you are analyzing year-over-year

To analyze year-over-year time trends, you must use the create_yoy_analyses function instead of the create_mom_analyses function.

To specify the years to analyze, enter the start_year and end_year variables in line 21 and 23; start_month and end_month are not used in create_yoy_analyses.

For example, lines 19 through 27 of the main function would look like the following for an analysis of 2019 through 2020:

# define months and years to iterate over
# start_month = 6
start_year = 2019
# end_month = 6
end_year = 2020

# analyses = create_mom_analyses(zone_set_name, start_month, start_year, end_month, end_year)
# Comment out the line above and uncomment the line below to run YoY analyses
analyses = create_yoy_analyses(start_year, end_year, zone_set_name)

🚧

Important

Make sure you only run create_mom_analyses OR create_yoy_analyses in the main function, NOT BOTH.

Configure analyses

You can edit the configuration of the analysis that will be iterated by editing the create_analysis function in the script. By default, it is set to run a Zone Activity analysis with the All Vehicles LBS+ travel mode. For more information, see Create and run an analysis.

🚧

This script does not support AADT analyses for month-over-month or year-over-year analyses. Ensure the parameters are defined correctly for your analysis type.

Create analyses for month-over-month time trends

The create_mom_analyses function creates an analysis for all of each month you want to analyze. For example, if you want to analyze January through May, the function creates an analysis for January, an analysis for February, etc.

The script prefixes each analysis title with "MoMTimeTrendsAllVehicles_" and appends the year and month. You can edit the name of each analysis in line 185; note that analysis names must be unique - analyses with duplicate names will not be created.

Create analyses for year-over-year time trends

The create_yoy_analyses function is set to return metrics for entire years; the years to analyze are set by start_year and end_year in the main function. To specify a set of months in the year, edit the startDate and endDate strings in lines 198 and 199, but don’t remove +str(i). For example, the script contains the following startDate and endDate:

    start_date = "01/01/" + str(i)
    end_date = "12/31/" + str(i)

To analyze year-over-year time trends for January through May, change the startDate and endDate to the following:

        start_date = "01/01/" + str(i)  
        end_date = "05/31/" + str(i)

Similar to create_mom_analyses, the script prefixes each analysis title with "YoYTimeTrendsAllVehicles_" and appends the year. Ensure that analysis names are unique.

Check metrics and analyze results

The download_metrics function takes a list of analyses created by the create_mom_analyses or create_yoy_analyses function and checks the status of each analysis. When each analysis runs successfully, the function downloads its metrics in a CSV file in your working directory with the same name as the analysis.

The script waits for 5 minutes for the analyses to run before continuing the script to download results. If you are analyzing a large area or year-over-year time trends, increase the seconds specified by time.sleep(300) in line 216.

When the script completes, you should have CSV files for each month or year that you specified. You can now analyze how metrics changed over time.