Configuring Analyses

Use the Create and run an analysis endpoint to define analysis type, zone sets, time period, and optional metrics or attributes. Analyses are processed asynchronously.

Analyses are processed asynchronously; you can use the Check analysis status endpoint to check when your analysis is complete.

📘

For more information in the StreetLight Help Center, see Analysis Types Overview .

Analysis Limits

Most accounts can have up to 250 active or queued analyses per API key. Once this limit is reached, wait for analyses to complete before submitting more.

To check analyses that are in the queue, use the in_queue parameter with the Search analyses endpoint.

If you need more capacity, Contact Support .

Defining Day Types and Day Parts

Day Types

Day types are groups of days of the week. Metrics are segmented based on the specified day types. The default day types are:

• All Days (Mon-Sun)
• Weekdays (Mon-Thurs)
• Weekend Days (Sat-Sun)

You can customize day types using the day_types parameter. Each entry follows the format name|startdayendday, where

• name is a descriptive label for the group (e.g., Weekday)
• startday and endday are digits from 1 (Monday) to 7 (Sunday)

Example (default day types):

"day_types": "Weekday|14,Weekend Day|67,All Days|17"

Day Parts

Day parts define time intervals within a day for which metrics are calculated. Each part is a specific time range in 24-hour format.

Define custom day parts using the day_parts parameter. Each entry uses the format name|starthourendhour, where

• name is a descriptive label for the group (e.g. Peak AM)
• starthour and endhour are two-digit hour values in 24-hour time (e.g., 06 for 6 AM, 18 for 6 PM)

You must include at least one entry: All Day|0023. If omitted, it will be added automatically.

Example (default day parts):

"day_parts": "All Day|0023,Early AM|0005,Peak AM|0609,Mid-Day|1014,Peak PM|1518,Late PM|1923"

Origin-Destination Analyses

O-D Zone Sets

For these analysis types, define both oz_sets (origin zones) and dz_sets (destination zones):

• Origin-Destination Analysis
• Origin-Destination through Middle Filters Analysis
• Top Routes between Origins and Destinations Analysis
• Network Origin-Destination Analysis

Truck O-D with historic data (before January 2023)

For Truck Origin-Destination analyses that use historic truck data, October through December 2022 are not supported as analysis months; the API rejects date ranges that include those months.

Recent O-D Analyses for Truck

Origin–Destination analyses using the Truck travel mode with January 2023 or later data are subject to the following constraints:

• Day Types: For these analyses, weekdays include Monday through Friday (in other analysis types, weekdays include Monday through Thursday only)
• Zone Limits: Up to 600 zones when analyzing up to 2 months of data; up to 200 zones when analyzing more than 2 months of data
• Maximum Data Period: 12 months in a single analysis
• Date Range Requirements: Date ranges must span full calendar months (from the first to the last day of each month)
• Non-consecutive Ranges: There is no hard limit on the number of non-consecutive date ranges

Trip Attribute Percentile Metrics

For Recent Truck O-D analyses, you can request percentile-based distributions for additional trip attributes using the following parameters:

• trip_length_percentile_bins
• trip_travel_time_percentile_bins

These parameters return percentile distributions for trip length and trip travel time metrics.

Zone Activity for Truck with Recent data

Zone Activity analyses with analysis_type Zone_Activity_Analysis and travel_mode_type Truck can use Recent truck data when your organization has the relevant Zone Activity truck capabilities enabled (historic medium/heavy-duty versus Recent medium/heavy-duty and light-duty, as provisioned on your subscription).

Historic truck data follows the supported output types and available months for historic ZA Truck on your subscription. You cannot combine historic-only months with Recent truck months in the same analysis when the API applies Recent truck validation (the same rules as Recent O-D Analyses for Truck). Months that are not available for historic Truck analyses under those rules (including October through December 2022 where that validation applies) are rejected with HTTP 400.

Recent truck data (January 2023 through present, when your account uses that data path) follows the same core API constraints as Recent O-D Analyses for Truck for calendar-month date_ranges, the 12-month cap, allowed day_types (All Days|17, Weekday|15, Weekend Day|67, or Weekend|67), and the rule that you must not mix historic-only months with Recent months in one request. Zone counts for this workflow are capped separately from Recent Truck O-D (for example, up to 1000 zones for a single Zone Activity analysis—confirm the limit returned by validation for your build). Pass-through line zones are not supported on this Zone Activity path; use Network Performance for pass-through line analyses instead.

Use commercial_sampling set to true on the Create and run an analysis request when you need commercial vehicle attribute outputs (route type, industry, fuel type) and your subscription includes that add-on for Zone Activity for Truck with Recent data. The commercial_attributes field name appears in Jira/product planning for this rollout, but current merged API request handling uses commercial_sampling.

For trip_attributes on Zone Activity for Truck with Recent data, expect trip length percentile metrics (trip_length_percentile_bins) where supported; speed, travel time, and circuity parameters may be ignored or surfaced as warnings alongside results when the data source does not provide those metrics. See Trip attributes below.

Network Origin-Destination and Network Performance

Network Origin-Destination requirements:

• Define zones using osm_ids
• Set both oz_sets and dz_sets
• Use All_Vehicles_AGPS travel mode

Network Performance requirements:

• Define zones using osm_ids or GeoJSON LineString
• Use All_Vehicles_AGPS or Truck travel mode
• Set metric_type to spot or segment
• When analyzing Truck with 2026 months, weekday day_types must be set as Weekday|15
• For Truck Network Performance analyses, months in 2023-2025 cannot be combined with 2026 or later months in one request

For more information, see Create a Network Performance analysis .

Trip and traveler attributes

Traveler Attributes

Traveler attributes are available only for the following analysis types:

• Origin-Destination
• Origin-Destination through Middle Filters
• Trips to or from Pre-set Geography
• Zone Activity

Trip Attributes

The trip_attributes parameter controls whether the analysis results will include the add-on trip attribute metrics with default bins, or ranges. When enabled, analysis metrics include the percentage of trips in each bin. Includes bins for:

• Duration (minutes)
• Length (miles or km)
• Speed (mph or kph)
• Circuity (distance ratio)

For Zone Activity for Truck with Recent data, trip-length percentiles may be available while speed, travel time, and circuity-related request fields may not change metrics for that data source; see the same section and the Create and run an analysis OpenAPI field descriptions for trip_speed_bins, trip_duration_bins, trip_circuity_bins, enable_speed_percentile, speed_percentile_bins, and trip_travel_time_percentile_bins.

Define custom bins with the following format:

"trip_duration_bins": "0-10,10-20,20+",
"trip_speed_bins": "0-10,10-20,20+"

Speed Percentile Bins

When enable_speed_percentile is true, you can specify percentile values with speed_percentile_bins.

{
  "enable_speed_percentile": true,
  "speed_percentile_bins": "10,20,30,40"
}

If omitted, defaults to "5,15,85,95".

Home and Work Locations

Enable with enable_home_work_locations. Requires at least one of the following:

• hwl_enable_visitor
• hwl_enable_resident
• hwl_enable_worker

Only supported for Zone Activity with travel modes other than Truck or All_Vehicles_CVD+.

zone_intersection_type options:

• all_trips_for_zone
• trips_by_pass_through_setting

📘

For more information in the StreetLight Help Center, see Home and Work Location Methodology .

Supported Analysis Type and Travel Mode Combinations

Note that only certain combinations of analysis_type and travel_mode_type are supported. Here is the current set of supported combinations:

For analyses with travel_mode_type of Bicycle or Pedestrian, only date ranges containing full months are supported.

For Segment_Analysis with travel_mode_type set to Truck, travel_mode_data cannot be LIGHT_DUTY.

The following analysis types are not supported by the StreetLight InSight® API:

• Turning Movement Counts
• Corridor Study
• Active Transportation
• Congestion Management
• Roadway Volumes