Defining Zones

StreetLight InSight® Planning API

Use the Create a zone set endpoint to define the geography that you will analyze. You can define zones to analyze using either of the following:

  • A GeoJSON feature collection where the features are either MultiPolygons or LineStrings
  • A list of OpenStreetMap (OSM) road segment IDs
  • A zone set created in the StreetLight InSight® web app
🚧

For zone sets with OSM IDs or road segments from the Zone Library in the StreetLight InSight® web app, the StreetLight InSight® API does not support segments split at tertiary intersections, only residential intersections.

Defining zones with GeoJSON

A zone set defined with GeoJSON feature collection where the features are either MultiPolygons or LineStrings.

See the GeoJSON specification for details on format requirements.

If you're starting from a shapefile, you can use and adapt this recipe to convert it to GeoJSON:


Any GeoJSON feature in your zone set can include the following properties:

PropertyTypeRequiredDescription
namestring✅The unique, case-insensitive name (max 50 chars) used to reference the zone in metrics.
idinteger❌Optional positive integer ID. Must be unique within the zone set.
is_passinteger (0/1) or null❌Required for LineString features. Determines if the zone captures pass-through traffic.
directioninteger (0–359)❌Direction of traffic (in degrees). Only applicable for pass-through zones.
is_bidiinteger (0/1) or null❌Indicates bi-directional traffic capture. Requires is_pass and direction to be set. Default is "0".

Line Zones

Features with LineString geometry can include the following optional properties:

PropertyTypeDescription
road_typestringOne of: Primary, Secondary, Local, or Ramp.
gate_latfloatLatitude of the custom gate location.
gate_lngfloatLongitude of the custom gate location.
gate_sizeintegerSize (in meters) of the gate used for sampling.

Calibration Zones

To enable single-factor calibration for traffic, pedestrian, or bicycle data, use the following feature properties.

📘

For more information in the Help Center, see What is single factor calibration?

Vehicle Calibration Zones

PropertyTypeDescription
calibration_typestringOne of: ADT, AADT, AWDT, AAWDT.
calibration_valueintegerValue (0–1,000,000) based on selected calibration type.
personal_traffic_ratiofloatProportion of personal vehicle traffic (recommended: 0.96).
medium_commercial_ratiofloatProportion of medium-duty vehicles (recommended: 0.02).
heavy_commercial_ratiofloatProportion of heavy-duty vehicles (recommended: 0.02).

The three traffic ratios must sum to 1.0.

Pedestrian Calibration Zones

PropertyTypeDescription
has_pedestrian_calibrationbooleanEnable pedestrian calibration.
pedestrian_calibration_valueinteger (0–999,999)Required if above is true.

Bicycle Calibration Zones

PropertyTypeDescription
has_bike_calibrationbooleanEnable bicycle calibration.
bike_calibration_valueinteger (0–10,000)Required if above is true.

Defining Zones with OSM IDs

You can specify OpenStreetMap (OSM) segments directly using the osm_ids parameter in the zone set request. To look up OSM segments split at residential intersections in a given geometry, use the Search OSM IDs endpoint. The response includes a columns array (for example osm_id, road_classification, and osm_segment_count), a data array of objects with those fields for each segment, and total_osm_segment_count for the query geometry.

When you create a zone set using OSM IDs, each OSM segment is segmented at residential intersections. These smaller segments are what count toward the zone limit of your analysis. Tertiary intersections are not supported for zones specified with OSM IDs. Zone sets created with OSM IDs use the current OSM vintage; if the platform updates to a newer OSM vintage, older OSM segment zone sets are rejected when creating an analysis and must be recreated.

The Network Origin-Destination analysis type requires zones to be defined with OSM IDs. You can also use zones defined with OSM IDs for any analysis type that allows OSM line segment zones from the zone library. For more information, see What is the Zone Library?

Zone requirements for Truck analyses with Recent data

When creating Zone_Activity_Analysis, OD_Analysis, or OD_MF_Analysis analyses with travel_mode_type set to Truck and Recent data (January 2023 and later):

  • Custom line zones (LineString) are not supported. Use pass-through OSM road segment zones defined with osm_ids instead.
  • Pass-through area zones (MultiPolygon with is_pass: 1) are not supported. Polygon zones must be non-pass-through (is_pass: 0).
  • Middle Filter zones (mfz_sets in OD_MF_Analysis) must be pass-through OSM road segment zones (osm_ids split at residential intersections), up to 5 middle filter zones. Area zones are not supported as middle filters in Recent Truck OD_MF_Analysis.

Defining Zones in StreetLight InSight® Planning

You can also use the StreetLight InSight® Planning web app to create zone sets. You can then use the name of the zone set in a Create and run an analysis request to analyze the zone set with the API.

Zone Quotas

If your account has a unique zone quota, any new unique zones used in an API analysis will count against that quota. For more information in the StreetLight Help Center, see:

zone_sets API Response

After a successful zone set creation, the response includes:

{
  "name": "MyCounty_Zones",
  "status": "success",
  "uuid": "a486a871-c610-4a0e-b87e-9b3c030862a1"
}

You can use either the name or uuid to reference this zone set in subsequent analysis requests.

Once created, the zone set also appears in the StreetLight InSight® Planning web app.


Did this page help you?