Defining Zones

The zones request body property must be a GeoJSON feature collection where the features are either MultiPolygons or LineStrings. For more information, see the GeoJSON spec at geojson.org.

📘

For documentation of endpoint parameters, see Create a zone set.

All features in the GeoJSON feature collection can have the following five properties (optional properties can be omitted):

• name (required): Zone name is required, and will be used to reference that zone in the metrics. It must be case-insensitive unique within the zone set and must be no longer than 50 characters.
• id (optional): Zone ID as non-null can be optional. If non-null, it must be an integer greater than zero, and it will be used in addition to the Zone Name to reference that zone in the metric results. It must be unique within the zone set.
• is_pass (optional): null, 0, or 1. is_pass is always set to 1 for line zones. If 1, the zone will be analyzed in terms of traffic that passes through the Zone. Otherwise, depending on analysis type, the zone will be analyzed in terms of traffic that starts or stops in the zone.
• direction (optional): integer from 0 to 359. This can be non-null only for pass-through zones. If specified, traffic passing through the zone is included in analyses only if it is traveling in that direction.
• is_bidi (optional): null, 0, or 1. Default value is 0. If is_bidi is set, direction is defined and is_pass is set, then traffic going to and from the specified direction will be captured in the zone's metric values.

You can also use this recipe to get GeoJSON coordinates from a shapefile:

💡

Tip

If you split up a shapefile with a large number of zones into multiple zone sets, ensure that you group zones by geohash. This allows the zones to be more efficiently processed by StreetLight InSight®.

Specifying zones with OSM IDs

In the Create a zone set endpoint, you can specify zones with the osm_ids parameter. This allows you to specify OSM line segments as zones using their IDs, and include these zones in your analyses.

To search OSM IDs based on a given geometry, use the Search OSM IDs endpoint.

Zones specified by OSM IDs are required for use with the Network Performance and Network Origin-Destination analysis types. You can also use zones specified with OSM IDs for any analysis type that allows OSM line segment zones from the zone library. For more information, see Configuring Analyses.

📘

For more information in the Help Center, see What is the Zone Library?

Line zone optional properties

Features with LineString geometry can define the following optional properties:

• road_type: Primary, Secondary, Local, or Ramp. Road type describe the type of the road segment.
• gate_lat: float number from -90 to 90. Latitude of line segemnt custom gate.
• gate_lng: float number from -180 to 180. Longitude of line segment custom gate.
• gate_size: integer. Size of line segment custom gate.

Calibration zone optional properties

Features may also contain properties to specify Zone Calibration settings. If with_calibration is set to true in the Zone Set parameters, the following parameters can be added to a pass-through (is_pass enabled) zone's feature properties in order to specify Zone Calibration settings:

• calibration_type: String with value ADT, AADT, AWDT, or AADWT. Specify the type of calibration for this Zone.
• calibration_value: Integer with a value between 0 and 1,000,000. Required if calibration_type is set. Specifies the traffic at the Zone based on the calibration_type.
• personal_traffic_ratio: Float number between 0.000 and 1.000. The recommended value is 0.96. Required if calibration_type is set. Specifies the ratio of traffic for this Zone that is due to personal vehicles.
• medium_commercial_ratio: Float number between 0.000 and 1.000. The recommended value is 0.02. Required if calibration_type is set. Specifies the ratio of traffic for this Zone that due is to medium-duty vehicles.
• heavy_commercial_ratio: Float number between 0.000 and 1.000. The recommended value is 0.02. Required if calibration_type is set. Specifies the ratio of traffic for this Zone that due is to heavy-duty vehicles.

Note that if specified, the sum of personal_traffic_ratio, medium_commercial_ratio and heavy_commercial_ratio should be 1.0. e.g { ... "personal_traffic_ratio": 0.96, "medium_commercial_ratio": 0.02, "heavy_commercial_ratio": 0.02, }

The following optional properties can be set to specify Pedestrian Calibration:

• has_pedestrian_calibration: Boolean. Set to true to enable Pedestrian Calibration.
• pedestrian_calibration_value: Integer with a value between 0 and 999,999. Required if has_pedestrian_calibration is enabled. Specifies the pedestrian traffic at the zone.

The following optional properties can be set to specify Bicycle Calibration:

• has_bike_calibration: Boolean. Set to true to enable Bicycle Calibration.
• bike_calibration_value: Integer with a value between 0 and 10,000. Required if has_bike_calibration is enabled. Specifies the bicycle traffic at the Zone.

📘

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

zone_sets response body

The response for a successful zones request includes the zone set name, a success status, and a unique universal identification, or UUID. If you do not specify a zone set name, the name will be the UUID.

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

After the zone set is created, you can view it from the StreetLight InSight® web app.

You can use the name or the UUID to identify the zone sets to use when you create an analysis with the analyses endpoint. You can also use zone sets created in the StreetLight InSight® web app in your analyses request by using the zone set name.