Segment Quota Usage

Requests to the Metrics endpoint in the StreetLight Advanced Traffic Counts API count against your organization's API segment quota. Specifically, each row in the response of a metrics query counts as 1 against this quota. Each query of a road segment counts against your quota, even if you have queried the same road segment before.

How is quota usage calculated?

Only requests to the Metrics endpoint count against your quota.
Each row in the Metrics endpoint response counts as a segment queried, even if it’s metrics for different months for the same road segment.
Querying multiple months or years with the date_range parameter will count against your quota for each month or year in the response.
Road segments, date range, day types, and day parts affect of rows in the response, not the number of metrics fields in a request
If your metrics request returns an error, it will not count against your quota

For example, if you request average daily traffic for October 2020, and there are 5 road segments in your geography, there will be 5 rows in the response, and 5 will be counted against your API segment quota.

['segment_id', 'year_month', 'trips_volume']
[1000000000000001, '2020-10-01', 2921]
[2000000000000001, '2020-10-01', 5915]
[3000000000000001, '2020-10-01', 10792]
[4000000000000001, '2020-10-01', 2118]
[5000000000000001, '2020-10-01', 15791]

Metrics parameters affecting quota usage

These are the different parameters in the metrics endpoint that can affect the number of rows in your response, and thus how the response counts against the API segment quota.

geometry: This parameter defines the amount of road segments in the request. You can verify the number of road segments in your geometry with the Segment Count endpoint. For more information, see Defining Geometry.

date_range: Each month or year in the date range will be returned as a separate row. For example, if you define a date_range of October through November 2020, the response would include a row for October, November, and December 2020 for each road segment.
So if you are querying 5 road segments in a query with the above date range, the response will look like the example below, and it will count as 15 against your API segment quota (5 road segments * 3 months).

['segment_id', 'year_month', 'trips_volume']
[1000000000000001, '2020-10-01', 2971]
[1000000000000001, '2020-11-01', 2717]
[1000000000000001, '2020-12-01', 2504]
[2000000000000001, '2020-10-01', 4955]
[2000000000000001, '2020-11-01', 4373]
[2000000000000001, '2020-12-01', 4250]
[3000000000000001, '2020-10-01', 11792]
[3000000000000001, '2020-11-01', 10918]
[3000000000000001, '2020-12-01', 9921]
[4000000000000001, '2020-10-01', 2318]
[4000000000000001, '2020-11-01', 2206]
[4000000000000001, '2020-12-01', 2238]
[5000000000000001, '2020-10-01', 11791]
[5000000000000001, '2020-11-01', 10936]
[5000000000000001, '2020-12-01', 10166]

day_parts and day_types: You can only have one day_part (hours of the day) and one day_type (parts of the week) per metrics request. If you want to get metrics for 2 different day types, such as Monday and Tuesday, for 5 road segments, you would have to send 2 metrics requests. The response for the Mondays request could be:
```
['segment_id', 'year_month', 'day_type', 'trips_volume']
[1000000000000001, '2020-10-01', 1, 2490]
[2000000000000001, '2020-10-01', 1, 3904]
[3000000000000001, '2020-10-01', 1, 9597]
[4000000000000001, '2020-10-01', 1, 2310]
[5000000000000001, '2020-10-01', 1, 9575]
```
And the response for the Tuesdays request could be:
```
['segment_id', 'year_month', 'day_type', 'trips_volume']
[1000000000000001, '2020-10-01', 2, 2233]
[2000000000000001, '2020-10-01', 2, 4333]
[3000000000000001, '2020-10-01', 2, 10408]
[4000000000000001, '2020-10-01', 2, 1740]
[5000000000000001, '2020-10-01', 2, 10566]
```
The two responses would count as 10 total against your API segment quota. Even though it was the same 5 road segments, we queried them multiple times to get these different metrics.

Tips

Check how many road segments you are querying. Use the Segment Count endpoint to estimate the number of road segments you are querying, but note that for the reasons explained above, this may not be equal to the amount counted against your API segment quota.
Multiple fields in one request does not affect quota usage; you can request multiple metrics fields in one request. If you request multiple metrics fields for 1 road segment, that only counts as 1 segment queried. The response below includes multiple metrics fields (trips_volume, vmt) for one segment, and only counts as 1 API segment queried.
```
['segment_id', 'year_month', 'trips_volume', 'vmt']  
[1000000000000001, '2020-10-01', 2233, 362.0]
```
However, if you request one metrics field in one request for a road segment, and a different metrics field for the same road segment in a different request, then those 2 requests count as 2 API segments queried.
Keep track of your responses. Be sure to save and store responses to the metrics endpoint so that you don’t need to repeat queries. For large responses, see Pagination.

Examples

If you are doing a before and after study on a single road, looking at traffic behavior for each hour of the day and each day of the week, the calculation would be:

1 road segment x 2 months x 7 day types x 24 day parts = 336 API segments

This would have to be done in multiple API requests, and each time you query the road segment it counts against the API segment quota.

If you are looking at average daily traffic volumes for 100 road segments (for “all” day types and “all” day parts, rather than broken down) , the calculation would be:

100 road segments x 1 month x 1 day types x 1 day part = 100 API segments

Checking quota usage

You can use the Usage endpoint to check how many API segment metrics rows you have queried. A response to the usage endpoint looks like this, where each job is a request:

{
    "jobs": [
        {
            "billed_fields_queried": 0,
            "created_date": "2024-09-09T08:39:32.029629-07:00",
            "is_billable": True,
            "job_id": "ede72fb6-4f42-4934-93e8-7a2eca12b881",
            "segments_queried": 48,
            "status": "done",
            "type": "metrics"
        },
        {
            "billed_fields_queried": 0,
            "created_date": "2024-09-09T08:39:23.480895-07:00",
            "is_billable": True,
            "job_id": "cbe5694f-6eee-4f4b-9b01-aae0eccf94ca",
            "segments_queried": 272,
            "status": "done",
            "type": "metrics"
        }
    ],
    "status": "done"
}

If "is_billable": True for a request, then the "segments_queried" value for the job will count against your segment quota.

To determine how much of the quota you have used up, send a request to the usage endpoint where the term_start is the start of your subscription. For jobs where "is_billable": True, count up the "segments_queried". You can use the recipe below to quickly calculate this number.

➕

Calculate segment usage

Open Recipe

Subtract this amount from your quota to determine how many API segments you have remaining. If you do not know your organization’s API segment quota, Contact Support to find out.