Defining Zones

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

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:

📁

StreetLight InSight® API: Convert a shapefile to GeoJSON to create a zone set

Open Recipe

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

Property	Type	Required	Description
`name`	string	✅	The unique, case-insensitive name (max 50 chars) used to reference the zone in metrics.
`id`	integer	❌	Optional positive integer ID. Must be unique within the zone set.
`is_pass`	integer (0/1) or null	❌	Required for LineString features. Determines if the zone captures pass-through traffic.
`direction`	integer (0–359)	❌	Direction of traffic (in degrees). Only applicable for pass-through zones.
`is_bidi`	integer (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 define the following optional properties:

Property	Type	Description
`road_type`	string	One of: `Primary`, `Secondary`, `Local`, or `Ramp`.
`gate_lat`	float	Latitude of the custom gate location.
`gate_lng`	float	Longitude of the custom gate location.
`gate_size`	integer	Size (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

Property	Type	Description
`calibration_type`	string	One of: `ADT`, `AADT`, `AWDT`, `AAWDT`.
`calibration_value`	integer	Value (0–1,000,000) based on selected calibration type.
`personal_traffic_ratio`	float	Proportion of personal vehicle traffic (recommended: `0.96`).
`medium_commercial_ratio`	float	Proportion of medium-duty vehicles (recommended: `0.02`).
`heavy_commercial_ratio`	float	Proportion of heavy-duty vehicles (recommended: `0.02`).

The three traffic ratios must sum to 1.0.

Pedestrian Calibration Zones

Property	Type	Description
`has_pedestrian_calibration`	boolean	Enable pedestrian calibration.
`pedestrian_calibration_value`	integer (0–999,999)	Required if above is `true`.

Bicycle Calibration Zones

Property	Type	Description
`has_bike_calibration`	boolean	Enable bicycle calibration.
`bike_calibration_value`	integer (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 get a list of OSM IDs for segments in a given geometry, use the Search OSM IDs endpoint.

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 see What is the Zone Library?

`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® web app.

Defining zones with GeoJSON

Line Zones

Calibration Zones

📘

Defining Zones with OSM IDs

zone_sets API Response

`zone_sets` API Response