Get metrics for a geometry

post

https://api.streetlightdata.com/satc/v1/metrics

Returns segment-level metrics for the specified geometry, filters, and date selection.

Specify exactly one of date, date_range, or date_ranges.

Truck mode (mode: truck): Requires weight_class. Uses US + agps with years 2023-2024 and OSM vintage 202302. See Available Metrics for truck field availability.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Returns metrics for StreetLight segments within your defined geometry. You can request many types of metrics and filter your results. For more information, see Available Metrics.

🚧
Queries to this endpoint count against your quota
Segments queried in calls to the Metrics endpoint count against your segment quota. Each row returned from the metrics endpoint counts against your segment quota, even if you are querying the same segments. Use the Segment Count endpoint to see how many segments will be in your query.

You can merge geometry data from the geometry endpoint with the metrics from the metrics endpoint to visualize the metrics for each segment with the following recipe: Fetch and merge to geojson

Use caution when using the nearest geometry type and a multi-month date selection to get metrics in situations that may have very low sample data, such as pedestrian travel mode with day_parts late at night. This may yield a different selection of segments being returned for each month/year.

Specify one of date, date_range, or date_ranges. For the agps data source, you can use date_ranges to request discontinuous months in a single call. Each range in the array must be disjoint (non-overlapping). You cannot combine months that map to different OSM vintages in one request.

When mode is truck, you must include weight_class, and data is limited to US + agps with years 2023 - 2024. See Truck metrics.

osm_vintage is optional for agps requests; when omitted, the server selects the vintage from your date or year.

Body Params

geometry

required

Geometry used in a query, provided as one of the following geometry types:

segment_id: An array of segment IDs
radius: A radius around a point
nearest: Segments nearest to a point
polygon: A bounding polygon
tract_id, zip_id, blockgroup_id, taz_id,: IDs for various local aggregations (US-only)
places_2020: 7-digit FIPS code from the 2020 U.S. census, where the first 2 digits are the state code and the last 5 digits are the place code. (US-only)
dissemination_area_id, census_division_id, census_subdivision_id: IDs for various local aggregations (CAN-only)
osm_id: An array of OSM IDs

country

string

enum

required

Defaults to us

Country code for the query area.

Allowed:

mode

string

enum

required

Defaults to vehicle

Travel mode for the query.
See Available Metrics for mode-specific fields and constraints.

Allowed:

source

string

enum

The data source that will be used. Check the Available Metrics and Date Ranges for each data source.

Requests that do not specify this parameter default to lbs_plus, except mode: truck which uses agps.

Allowed:

osm_vintage

array of integers

length ≤ 2

The OpenStreetMap (OSM) snapshot that defines segments queried, where 202302 is February 2023, 202501 is January 2025, and 202601 is January 2026.

For the agps data source, this parameter is optional; when omitted, the server selects the vintage from the requested date or year.

Vintage selection guidelines:

Use 202302 for metrics from December 2024 and earlier.
Use 202501 for metrics from 2025.
Use 202601 for metrics from January 2026 and later.
Use two vintages for a date range that spans vintages.

When mode is truck, only 202302 is supported and the parameter defaults to [202302] when omitted.

osm_vintage

Allowed:

roadway_classification

object

If specified, only segments with the given OSM roadway classifications will be returned.
When mode is truck, service is not permitted.

fields

array of objects

required

Defaults to segment_id,year_month,trips_volume

The metrics requested for the given parameters. segment_id is required for all requests; osm_vintage is required for requests where the source is agps.

For more information, see Available Metrics.

fields*

Metric column to return. See Available Metrics for mode and source availability.

weight_class

array of objects

Required when mode is truck. Do not combine light_duty with medium_duty or heavy_duty.
Some metrics (for example trips_volume) are not available for light_duty.

weight_class

Allowed:

day_part

required

0 to 23

Hours of the day desired, available hourly or in 3 hour bins, or the entire day.

day_type

string

enum

required

Defaults to all

Day of the week or day type. weekday includes Monday through Friday; weekend includes Saturday and Sunday.

For mode: truck, grouped commercial attribute fields (route_type, fuel_type, industry, in_out_state, journeys_sample_count, and related trip attribute fields) are returned only when both day_type and day_part are all.

date

object

The month or year for which you want metrics. Omitting month returns metrics for all of the requested year.

date_range

object

A contiguous date range for which you want metrics.

Specifying months and years returns metrics for all months in the range, up to 12 months.
Specifying only years returns metrics for all years in the range, up to 4 years.

For the agps data source, you may instead use date_ranges to request discontinuous months.

date_ranges

array of objects

length ≥ 1

One or more date ranges for which you want metrics. Ranges must be disjoint (non-overlapping).

Supported for the agps data source. Each range follows the same month/year rules as date_range.

date_ranges

A contiguous date range for which you want metrics.

Specifying months and years returns metrics for all months in the range, up to 12 months.
Specifying only years returns metrics for all years in the range, up to 4 years.

For the agps data source, you may instead use date_ranges to request discontinuous months.

start

object

required

end

object

required

direction

string

enum

required

Defaults to bidirectional

Trips either with or against the segment direction, or both directions.

Allowed:

volume

object

Returns metrics for segments with volume greater than (gt) or less than (lt) the specified threshold. Cannot be used with the nearest geometry type.

data_version

integer

enum

Defaults to 1

Allowed:

Queries to this endpoint count against your quota

200Success response

400Validation error

403Date range not available, or area too large or out of bounds