Guides

Querying Segments Using the "Radius" Geometry

StreetLight Advanced Traffic Counts API

Suggest Edits

This example shows the intended workflow and sequence of requests to make with the StreetLight Advanced Traffic Counts API through a scenario where a company can use StreetLight Advanced Traffic Counts to help inform an important decision.

This example makes use of the radius geometry type to specify the segments to analyze, and the segment counts endpoint to verify the segments.

Scenario

A billboard company in Los Angeles wants to build more billboards in their city. They want to see which roads have the most traffic, in order to maximize the impact of each billboard. We can use StreetLight Advanced Traffic Counts to get metrics for roads in their area and help them decide where to build new billboards.

📘

Before you begin

You can use the example calls below as a starting point for your own calls with cURL. Replace [API Key] with your own API key for the calls to be successful. For more information, see Authentication.

1. Check available dates 📅

To begin, we make a call to the date_ranges endpoint to check the dates for which metrics are available. Since we're interested in traffic that would see a billboard, we only check the vehicle travel mode. We are interested in metrics from 2021, so we want to confirm that months in 2021 are available.

curl --request GET \
     --url https://api.streetlightdata.com/satc/v1/date_ranges/us/vehicle \
     --header 'accept: application/json' \
     --header 'x-stl-key: [API key]'

The response would be similar to the following, which is truncated for brevity:

{
  "months": [
    {
      "month": 1,
      "year": 2019
    },
    {
      "month": 2,
      "year": 2019
    },
...
    {
      "month": 4,
      "year": 2022
    }
  ],
  "status": "done",
  "years": [
    {
      "year": 2019
    },
    {
      "year": 2020
    },
    {
      "year": 2021
    }
  ]
}

Based on the response, we see that the data we are interested in is available, so we can continue on to define the geometry for which we want metrics.

📘

For more information, see /date_ranges/{country}/{travel_mode}.

2. Identify the geometry to study 🔍

The business is interested in building billboards close to downtown Los Angeles, so we define the geometry with a 5 mile radius around a pair of coordinates near downtown Los Angeles. This is one of multiple ways to define geometry.

We define the geometry in the same way for all the endpoints, so the following information is required for each call:

  • Coordinates: 34.0556° N, 118.2457° W
  • Radius: 5 miles

We use this information in API calls in the steps below.

📘

For more information, see Defining Geometry.

3. Check the number of road segments ✅

StreetLight charges for calls to the metrics endpoint based on the number of StreetLight segments queried and the metrics fields requested. Before we request metrics, we check the number of StreetLight segments within the geometry we want to study with the segmentcount endpoint. To do this, we use the same radius and coordinates defined previously, and check how many segments are included in our geometry.

📘

Ensure that you enter your coordinates in the order "Longitude, Latitude" for each of the following requests.

The segmentcount endpoint returns the maximum possible number of road segments in our defined geography for which metrics will be returned. The actual number of segments can vary based on metrics available for the dates and travel mode.

curl --request POST \
     --url https://api.streetlightdata.com/satc/v1/segmentcount \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-stl-key: [API Key]' \
     --data '
{
     "geometry": {
          "radius": {
               "point": {
                    "type": "point",
                    "coordinates": [
                         -118.2457,
                         34.0556
                    ]
               },
               "geom_mode": "within",
               "buffer": 5,
               "unit": "mile"
          }
     },
     "country": "us",
     "mode": "vehicle"
}
'

The response returns the number of segments in the geometry, along with a unique request ID.

{
  "request_id": "e659e45d-e0da-4bc3-b3d0-dbc1eae5bc1f",
  "segment_count": 11497,
  "status": "done"
}

Our geometry includes 11,497 segments. Now we know that when we request our metrics with this geometry, we will get metrics for up to 11,497 segments.

📘

For more information, see /segmentcount.

4. Get geometry data in GeoJSON format 📍

Before requesting metrics, we get StreetLight Segment IDs and GeoJSON line strings for the segments we are analyzing so we can visualize the individual segments in a GIS tool. To visualize the geometry, we use the geometry endpoint.

We can merge this geometry data with the metrics from the metrics endpoint to visualize the metrics for each segment. For more information, see the following recipe:

🗺️
Fetch and merge to GeoJSON
Open Recipe

We can also specify roadway classifications for specific roads we want to analyze. Since billboards are only on certain classifications of roads, we look at the following roadway classifications:

  • Motorway
  • Trunk
  • Primary
  • Secondary
curl --request POST \
     --url https://api.streetlightdata.com/satc/v1/geometry \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-stl-key: [API Key]' \
     --data '
{
     "geometry": {
          "radius": {
               "point": {
                    "type": "point",
                    "coordinates": [
                         -118.2457,
                         34.0556
                    ]
               },
               "geom_mode": "within",
               "buffer": 5,
               "unit": "mile"
          }
     },
     "country": "us",
     "roadway_classification": {
          "include": [
               "trunk",
               "primary",
               "secondary"
          ]
     },
     "mode": "vehicle"
}
'

The response includes segment ids and GeoJSON line strings along with a unique request ID. We can use these to visualize the geometry in a GIS tool.

You can use the response ID with the geometry/paging endpoint to page a previous geometry query. For more information, see Pagination.

The following example response is truncated for brevity.

{
  "columns": [
    "segment_id",
    "line_geometry"
  ],
  "data": [
    [
      3975317620000001,
      {
        "coordinates": [
          [
            -118.2311139,
            34.0950953
          ],
          [
            -118.2308441,
            34.0947723
          ]
        ],
        "type": "LineString"
      }
    ],
    ...
  "paging": null,
  "query_rows": 6998,
  "request_id": "9723e2ae-af43-460f-9da6-07ea22e1be81",
  "status": "done"
}

There are fewer query rows, or segments, returned because we filtered by roadway classification. If we had not filtered by roadway classification, the query rows or segments returned would be 11,497, or the count that was returned by our segmentcount call.

📘

For more information, see /geometry.

5. Retrieve the metrics 📊

Now that we have counted the StreetLight segments in our geometry and retrieved geometry data, we can retrieve the metrics for the geometry using the metrics endpoint.

🚧

StreetLight only charges for calls to the metrics endpoint, based on the number of StreetLight segments queried and the metrics fields requests. For more information, see Available Metrics. Save and store these metrics when you get them.

The following parameters are required:

  • geometry: The geometry defined in the previous requests.
  • fields: These are the different metrics we can request. In this case, we are interested in segment IDs, year and month of the data, and trip volume. If the billboard company only made billboards for luxury watches, they could use such as trip_purpose or income if they wanted to advertise to a specific demographic. For a complete list, see Available Metrics.
  • country: For this example, we are studying the US.
  • mode: We are only interested in vehicles.
  • day_part: We will look at all parts of the day
  • day_type: We are looking at all days of the week.
  • direction: If the billboards are dual sided, drivers in both directions would be able to view them, so we choose bidirectional.
  • date: We are interested in data from the entire year of 2021.

In addition, we use the roadway_classification parameter to filter our metrics for roadways that can have billboards.

You can see how the choices above are entered in the example call below.

curl --request POST \
     --url https://api.streetlightdata.com/satc/v1/metrics \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-stl-key: [API Key]' \
     --data '
{
     "geometry": {
          "radius": {
               "point": {
                    "type": "point",
                    "coordinates": [
                         -118.2457,
                         34.0556
                    ]
               },
               "geom_mode": "within",
               "buffer": 5,
               "unit": "mile"
          }
     },
     "fields": [
          "segment_id",
          "year_month",
          "trips_volume"
     ],
     "country": "us",
     "mode": "vehicle",
     "day_part": 3,
     "day_type": "all",
     "direction": "bidirectional",
     "date": {
          "year": 2021
     },
     "roadway_classification": {
          "include": [
               "trunk",
               "primary",
               "secondary"
          ]
     },
     "data_version": 1
}
'

The following example response shows the columns returned and the contents of one row. The rest of the rows have been omitted for brevity.

{
  "columns": [
    "segment_id",
    "year_month",
    "trips_volume"
  ],
  "data": [
    [
      94674850000001,
      "2021-01-01",
      73
    ],
...
"data_version": 1,
  "query_rows": 6998,
  "request_id": "cb4a03fb-e0eb-4877-84a1-70f3037c7630",
  "status": "done"
}

So the segment ID is 94674850000001, the month is January, and the trip volume is 73.

You can use the response ID with the metrics/paging endpoint to page a previous metrics query. For more information, see /metrics/paging/{uuid}.

📘

For more information, see /metrics.

If we requested metrics for enough data, the response would be paginated, and include a URL for the next page. Log or save this URL so that you can return to it. For more information, see Pagination.

👍

Success!

The billboard company can now incorporate these metrics into their data analysis workflows in order to determine sites for new billboards.

You can use these calls as an example to make your own calls with the StreetLight Advanced Traffic Counts API, or you can use the API Reference to learn more and create your own.

Updated 9 months ago