Example Workflow

StreetLight InSight® API

This example describes an end-to-end workflow using the StreetLight InSight® API. This example shows you how to create zones, configure and submit an analysis, and get the metrics.

This example uses an Origin-Destination analysis for the Truck travel mode for two neighborhoods in San Francisco: the Mission and the Financial District. The data period is all of 2019.

📘

Required to complete this example

You need the following to run the requests as described in this example:

  • API key
  • StreetLight InSight® login email
  • cURL installation

You can use the example calls below as a starting point for your own calls with cURL. Replace [stl-api-key] with your own API key and [email protected] with your StreetLight InSight® login email for the calls to be successful.

1. Confirm connectivity :link:

Before you begin, echo a "hello world" message to confirm that you can connect to the StreetLight InSight® API with your API key. To echo a message, make a POST request to the /debug/echo endpoint.

curl -i -d '{"message": "hello world"}' \
    -H "content-type: application/json" \
    https://insight.streetlightdata.com/api/v2/debug/echo?key=[stl-api-key]

The response returns the following:

{
    "message": "hello world",
    "status": "success"
}

This response means that StreetLight is able to authenticate the request with the API key provided.

📘

API Reference: Echo a message for debugging

Next, specify zones to analyze.

2. Create a zone set :round-pushpin:

To create a zone set and define the zones to use in the analysis, make a POST request to the /zone_sets endpoint.

Zones can be GeoJSON MultiPolygons or LineStrings; here is where you define MultiPolygons. Each zone must have the following properties:

  • name: A name for each zone. Here, you use the neighborhoods covered by each zone.
  • id: A unique integer for each zone in a zone set (integer, nullable).
  • is_pass: Specifies whether the zone is pass-through, 0 for no or 1 for yes. You are interested in trips that start or end in these zones, so we set "is_pass" = 0 to make the zones non pass-through.
  • direction: If the zone is pass-through, indicates the direction of the zone. Decimal from 0 to 359 degrees, only applicable if is_pass is equal to 1.
  • geom_type: Optional, specifies whether the zone is a line zone or polygon zone, with a default value of polygon.
curl --request POST \
     --url 'https://insight.streetlightdata.com/api/v2/zone_sets?key=[stl-api-key]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "zones": [
          {
               "type": "FeatureCollection",
               "features": [
                  { "type": "Feature", "properties": { "id": 1, "name": "Mission", "is_pass": 0, "direction": null }, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ -122.426698258661972, 37.769562689936315 ], [ -122.423394859041892, 37.772083876030344 ], [ -122.42225575572462, 37.770418101996292 ], [ -122.411206453547067, 37.769427623969634 ], [ -122.406991771273155, 37.769067446852375 ], [ -122.404656609472752, 37.767716767038294 ], [ -122.405169205965521, 37.762628984940662 ], [ -122.406593085112107, 37.760557752167074 ], [ -122.405795712790038, 37.758441432691242 ], [ -122.403232730326167, 37.75722564731312 ], [ -122.402549268335804, 37.751821915004783 ], [ -122.403346640657901, 37.749390106706535 ], [ -122.407561322931784, 37.748399347080543 ], [ -122.424875693354338, 37.74781389197571 ], [ -122.426698258661972, 37.769562689936315 ] ] ] ] } },
                  { "type": "Feature", "properties": { "id": 2, "name": "Financial District", "is_pass": 0, "direction": null }, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ -122.405425504211919, 37.798033588378779 ], [ -122.398476973976571, 37.798933675051543 ], [ -122.396654408668923, 37.799698740100226 ], [ -122.397024617247041, 37.79929370664977 ], [ -122.396768319000643, 37.798911173018389 ], [ -122.395828558763895, 37.797898574431919 ], [ -122.393607307295227, 37.799113691070012 ], [ -122.392610591892605, 37.797876072083447 ], [ -122.394233814119715, 37.79690846455324 ], [ -122.393037755636598, 37.795670808599994 ], [ -122.3913575782436, 37.796278387822021 ], [ -122.390987369665496, 37.795693311702443 ], [ -122.392439726395011, 37.794500642185817 ], [ -122.389278714689581, 37.791462623416393 ], [ -122.401182344355107, 37.781965196242638 ], [ -122.405824190372982, 37.785701296639232 ], [ -122.406222876534017, 37.785723802695827 ], [ -122.407134159187834, 37.790337399578668 ], [ -122.404058580231194, 37.790764986655553 ], [ -122.405425504211919, 37.798033588378779 ] ] ] ] } }
                    ]
          }
     ],
     "insight_login_email": "[email protected]",
     "zone_set_name": "Quickstart_Zone_Set"
}'

The following is an example response:

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

These zones are available to view and edit from the StreetLight InSight® web app.

The zone set has a UUID (universally unique ID) included in the response body. If zone_set_name is not specified, the zone set name is the same as the UUID.

📘

Related Links

Next, verify the available date range for the Truck travel mode.

3. Query available data periods :date:

You are running an analysis with the Truck travel mode, so you need to look up the data periods available for the Truck travel mode. To look up data periods, make a GET request to the /date_ranges endpoint.

We recommend checking data availability before running an analysis, as StreetLight regularly adds new data months. Note that the travel mode is included in the URL for this endpoint.

curl --request GET \
     --url 'https://insight.streetlightdata.com/api/v2/date_ranges/US/Truck?key=[stl-api-key]' \
     --header 'accept: application/json'

The following is an example response:

{
  "date_ranges": {
    "supports": [
        {
            "start_date": "01/01/2019",
            "end_date": "12/31/2019",
        }
    ],
    "default": [
        {
            "start_date": "03/01/2019",
            "end_date": "04/30/2019",
        },
        {
            "start_date": "09/01/2019",
            "end_date": "10/31/2019",
        }
    ]
  }
}

📘

Related links

Next, create and run an analysis.

4. Create an Origin-Destination Analysis :truck:

To configure and run an Origin-Destination Analysis, make a POST request to the /analyses endpoint.

The body of the request specifies the travel mode, origin Zone Set, destination Zone Set, data periods, and more.

These parameters specify the options for our analysis:

  • insight_login_email Required. You must have access to the specified organization to create a analysis
  • analysis_name Optional. If specified, it must be case-insensitive unique and must be no more than 50 characters long. If you do not specify an analysis name, the server assigns a UUID-based name. This analysis is named "Quickstart_OD_Analysis".
  • analysis_type You are running an Origin-Destination analysis, so the analysis type is OD_Analysis.
  • oz_sets and dz_sets can also be specified by UUID instead of by name. You can also refer to Zone Sets created in the StreetLight InSight® web application with their names. This analysis uses "Quickstart_Zone_Set" as the origin and destination zones, so you can analyze trips in both directions between the two zones in the Zone Set.
  • date_ranges A list of pairs of start and end dates in MM/DD/YYYY format.
  • day_typesA comma-separated list of day types in the analysis. Each day type has a name separated by the vertical bar from the start day of week to the end day of week (1 for Monday through 7 for Sunday). Average Day is defined as "17" (Monday through Sunday), Average Weekday is defined as "14" (Monday through Thursday) and Average Weekend Day is defined as "67". This analysis uses the default for this option.
  • day_parts A comma-separated list of day parts in the analysis. Each day part has a name separated by the vertical bar from the start hour and end hour from 00 (midnight) to 23 (11 PM). For example, 'All Day|0023' ranges from midnight (00:00) to 11:59 PM. All Day is defined as 0023 (midnight to midnight). This analysis uses the default for this option.
curl --request POST \
     --url 'https://insight.streetlightdata.com/api/v2/analyses?key=[stl-api-key]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "output_type": "index",
     "date_ranges": [
          {
               "start_date": "01/01/2019",
               "end_date": "12/31/2019"
          }
     ],
     "day_parts": "All Day|0023,Early AM|0005,Peak AM|0609,Mid-Day|1014,Peak PM|1518,Late PM|1923",
     "day_types": "Average Day|17,Average Weekday|14,Average Weekend Day|67",
     "oz_sets": [
          {
               "name": "Quickstart_Zone_Set"
          }
     ],
     "dz_sets": [
          {
               "name": "Quickstart_Zone_Set"
          }
     ],
     "insight_login_email": "[email protected]",
     "analysis_name": "Quickstart_OD_Analysis",
     "analysis_type": "OD_Analysis",
     "travel_mode_type": "Truck",
     "traveler_attributes": false,
     "trip_attributes": false
}
'

The following is an example response:

{
    "name": "Quickstart_OD_Analysis",
    "status": "success",
    "uuid": "fb6ae5d5-088f-4761-82ef-9d52af084863"
}

📘

Related links

We can check the analysis status to see when it is complete.

5. Query the status of your analysis :white-check-mark:

As it is running, you may want to check the status of the analysis to see if it has completed and to verify the metrics it includes. To query analysis status, we will make a POST request to the /analyses/status endpoint.

You can use the name or UUID of the analysis.

curl --request POST \
     --url https://insight.streetlightdata.com/api/v2/analyses/status \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "analyses": [
          {
               "name": "Quickstart_OD_Analysis"
          }
     ]
}
'

The response includes the status of the analysis, as well as the metrics it includes. We use these metrics strings to request metrics in the next step.

If the analysis is completed, the response should be similar to the following:

{
    "analyses": [
        {
            "metrics": [
                "od_all",
                "zone_od_all",
                "sample_size"
            ],
            "name": "Quickstart_OD_Analysis",
            "status": "Data Available",
            "uuid": "fb6ae5d5-088f-4761-82ef-9d52af084863"
        }
    ],
    "status": "success"
}

📘

Related links

Now that the analysis is complete, you can request the metrics.

6. Get metrics for the analysis :bar-chart:

To get metrics for a completed analysis, make a GET request to the /analyses/download/name/Quickstart_OD_Analysis/za_all endpoint, where Quickstart_OD_Analysis is the name of the analysis.

curl --request GET \
     --url 'https://insight.streetlightdata.com/api/v2/analyses/download/name/Quickstart_OD_Analysis/od_pers?key=[stl-api-key]' \
     --header 'accept: application/json'

The following is an example response:

device_type,origin_zone_id,origin_zone_name,origin_zone_is_pass_through,origin_zone_direction,destination_zone_id,destination_zone_name,destination_zone_is_pass_through,destination_zone_direction,day_type,day_part,o_d_traffic,origin_zone_traffic,destination_zone_traffic,avg_trip_duration
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),0: All Day (12am-12am),6635,40580,46777,441
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),1: Early AM (12am-6am),116,979,881,402
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),2: Peak AM (6am-10am),1017,6954,7933,409
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),3: Mid-Day (10am-3pm),2193,12531,14843,446
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),4: Peak PM (3pm-7pm),2331,12993,15452,455
Personal,1,Mission,no,N/A,1,Mission,no,N/A,0: Average Day (M-Su),5: Late PM (7pm-12am),977,7122,7668,430
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),0: All Day (12am-12am),6934,42379,48669,435
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),1: Early AM (12am-6am),70,708,696,370
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),2: Peak AM (6am-10am),1240,8758,9756,410
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),3: Mid-Day (10am-3pm),2089,11657,14062,438
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),4: Peak PM (3pm-7pm),2547,14024,16488,450
Personal,1,Mission,no,N/A,1,Mission,no,N/A,1: Average Weekday (M-Th),5: Late PM (7pm-12am),987,7233,7666,422

You can run a similar API call to retrieve the other metrics that this analysis supports. The list of available metrics was provided in the response to the Query Analysis Status API call. For more information, see Requesting Metrics

📘

Related links

👍

Success

You have successfully defined zones, configured and run an analysis, requested metrics, and you can now analyze the metrics you got.

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