---
title: "Connect StreetLight Data to AI Agents: Automate GIS & Traffic Data"
slug: connect-streetlight-data-to-ai-agents-automate-gis-traffic-data
date: 2026-07-16
author: Roopendra Talekar
categories: ["AI & Agents"]
excerpt: "Learn how to connect StreetLight Data to AI agents using Truto's tools endpoint. Automate spatial searches, zone sets, and traffic metrics dynamically."
tldr: "Connect StreetLight Data to AI agents to automate GIS operations. This guide covers fetching tools via Truto, managing GeoJSON, and building agentic loops to query SATC metrics safely."
canonical: https://truto.one/blog/connect-streetlight-data-to-ai-agents-automate-gis-traffic-data/
---

# Connect StreetLight Data to AI Agents: Automate GIS & Traffic Data


You want to connect StreetLight Data to an AI agent so your internal systems can independently run traffic analyses, map GIS geometries, extract SATC metrics, and build dynamic mobility zone sets based on historical context. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to manually build custom integrations for complex geospatial APIs.

Giving a Large Language Model (LLM) read and write access to a specialized GIS and traffic analytics platform like StreetLight Data is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the nuances of GeoJSON, spatial search, and asynchronous analysis queues, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on [connecting StreetLight Data to ChatGPT](https://truto.one/connect-streetlight-data-to-chatgpt-analyze-mobility-zone-sets/), or if you are building on Anthropic's models, read our guide on [connecting StreetLight Data to Claude](https://truto.one/connect-streetlight-data-to-claude-manage-satc-metrics-analyses/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for StreetLight Data, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex traffic engineering workflows. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of Custom StreetLight Data Connectors

Building AI agents is easy. Connecting them to external specialized APIs is hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an `@tool` decorator. In production, this approach collapses entirely, especially with a spatial analytics ecosystem like StreetLight Data.

If you decide to build this integration yourself, you own the entire API lifecycle. StreetLight Data's API introduces highly specific challenges that break standard LLM assumptions.

### The Geospatial Payload Trap
StreetLight Data relies heavily on GeoJSON for defining spatial boundaries, segments, and search areas. When an agent needs to retrieve SATC (Segment Analysis Traffic Counts) metrics or search for OSM (OpenStreetMap) segments, it must pass perfectly formatted nested coordinate arrays. LLMs are notoriously bad at generating exact, valid GeoJSON from scratch without hallucinating floating-point anomalies or breaking the right-hand rule for polygons. If you hand-code this integration, you must write strict validation layers to reject invalid geometries before they hit the StreetLight API. Truto's [unified tool layer](https://truto.one/best-unified-api-for-llm-function-calling-ai-agent-tools-2026/) enforces strict JSON schemas on the tool inputs, ensuring the LLM is constrained to valid request shapes.

### Asynchronous Analysis and Paging State
Traffic analyses are computationally expensive. Creating an analysis via the StreetLight Data API does not return data immediately; it returns an analysis UUID and a status. The agent must understand how to check the status queue, wait for completion, and then fetch the metrics. Furthermore, endpoints like SATC metrics return large datasets requiring specific `paging_id` tokens for cursor-based pagination. If you rely on basic REST wrappers, the LLM will lose the `paging_id` in context windows or hallucinate the status of a queued job. 

### Segment Quotas and Billable Operations
Unlike standard SaaS CRMs, querying StreetLight Data SATC metrics counts against a hard segment quota, and queries can result in billable usage. Giving an autonomous loop unchecked access to `list_all_street_light_data_satc_metrics` without understanding the underlying count via `list_all_street_light_data_satc_segment_counts` is a recipe for burning through your organizational budget. You need an architecture that allows the agent to safely check counts before executing the expensive metric retrieval.

## Architecture: How Truto Exposes Tools to Agents

Instead of writing a custom integration wrapper for StreetLight Data, Truto handles the API abstractions. Truto maps StreetLight Data endpoints into a REST-based CRUD API and exposes a `/tools` endpoint that your LLM framework can consume directly.

```mermaid
flowchart TD
    Agent["AI Agent (LangChain / CrewAI)"]
    TrutoSDK["Truto SDK (TrutoToolManager)"]
    TrutoAPI["Truto API (/tools Endpoint)"]
    Upstream["StreetLight Data API"]

    Agent -->|"1. Fetch tools"| TrutoSDK
    TrutoSDK -->|"2. Request available tools"| TrutoAPI
    TrutoAPI -->|"3. Return standardized JSON schemas"| TrutoSDK
    TrutoSDK -->|"4. bindTools() to LLM"| Agent
    Agent -->|"5. LLM decides to call a tool"| TrutoSDK
    TrutoSDK -->|"6. Execute proxy request"| TrutoAPI
    TrutoAPI -->|"7. Passthrough to upstream"| Upstream
```

### Factual Note on Rate Limits and Reliability
When dealing with programmatic agents hitting the StreetLight Data API, you will inevitably encounter HTTP 429 (Too Many Requests). **Truto does not retry, throttle, or apply backoff on rate limit errors.** When the upstream API returns an HTTP 429, Truto passes that error directly back to the caller.

However, Truto abstracts away the pain of parsing proprietary rate limit headers. Truto normalizes upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller (your agent loop) is entirely responsible for reading these headers and implementing its own [retry or backoff logic](https://truto.one/how-to-handle-third-party-api-rate-limits-when-an-ai-agent-is-scraping-data/).

## Fetching StreetLight Data Tools via API

Using the `truto-langchainjs-toolset`, developers can dynamically inject StreetLight Data tools into their agent frameworks. Here is a TypeScript example demonstrating how to initialize the tools and bind them to a model.

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";

async function initializeStreetLightAgent() {
  // 1. Initialize the Truto Tool Manager with your Integrated Account ID
  const toolManager = new TrutoToolManager({
    trutoToken: process.env.TRUTO_API_KEY,
    integratedAccountId: "streetlight-data-account-id"
  });

  // 2. Fetch the tools specific to StreetLight Data
  const streetLightTools = await toolManager.getTools();
  console.log(`Loaded ${streetLightTools.length} StreetLight Data tools.`);

  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });

  // 4. Bind the tools to the LLM
  const llmWithTools = llm.bindTools(streetLightTools);

  return { llmWithTools, streetLightTools };
}
```

## Hero Tools for StreetLight Data

Below are the highest-leverage tools available for StreetLight Data AI agent integration. These tools bypass basic CRUD operations and focus on the core value of the platform: geospatial search, zone generation, and traffic metrics.

### Search OSM Segments
`street_light_data_osm_ids_search`

Agents use this tool to search for OpenStreetMap (OSM) segments based on an input geometry (GeoJSON). It returns an array of records containing the `osm_id`, road classification, and segment counts. This is critical for agents needing to identify specific road networks before analyzing them.

> "I have a bounding box for downtown Austin. Find all the arterial OSM road segments within this geometry so we can begin our traffic study."

### Create Zone Sets
`create_a_street_light_data_zone_set`

This tool allows the agent to create a new zone set in StreetLight InSight. The tool schema enforces that `zones` and `osm_ids` are mutually exclusive, preventing the LLM from sending conflicting payload structures. It requires the `insight_login_email`.

> "Create a new StreetLight Data zone set named 'Austin Core Intersections'. Use the list of OSM IDs we just identified and assign it to my login email."

### Create and Run Analysis
`create_a_street_light_data_analysis`

Agents use this tool to programmatically define and kick off a StreetLight analysis. The agent must pass the `analysis_type`, `travel_mode_type`, and the previously generated `oz_sets`. This tool returns the analysis name, status, and UUID.

> "Run a new Origin-Destination analysis for commercial trucks using the 'Austin Core Intersections' zone set. Kick off the job and give me the analysis UUID."

### Retrieve SATC Geometries
`list_all_street_light_data_satc_geometries`

When visualizing data or mapping metrics, the agent needs the actual geographic line strings. This tool lists StreetLight segment geometries in GeoJSON format based on mode, geometry, and country.

> "Fetch the SATC geometries for bicycle traffic mode within the provided GeoJSON polygon in the US. We need the LineStrings to render a heatmap."

### Query SATC Metrics
`list_all_street_light_data_satc_metrics`

This is the core data extraction tool. It fetches StreetLight traffic metrics for segments within a defined geometry. The agent must specify the required fields, day part, day type, and direction. Because queries count against segment quotas, agents should typically run the segment count tool first.

> "Pull the SATC traffic metrics for weekday morning rush hour (6AM-9AM) inside the defined geometry. I need the average daily traffic volume and speed metrics."

For a complete list of available operations, required parameters, and JSON schemas, visit the [StreetLight Data integration page](https://truto.one/integrations/detail/streetlightdata).

## Workflows in Action

Exposing individual endpoints is step one. The real power of connecting StreetLight Data to AI Agents is orchestrating multi-step workflows. Here are concrete examples of how an agent uses these tools in sequence.

### Scenario 1: Autonomous Congestion Study Setup
An Urban Planner needs to analyze traffic volume on a newly proposed transit corridor, but they only have a rough GeoJSON polygon of the area.

> "Find all primary road segments in the provided GeoJSON polygon, group them into a new zone set called 'Transit Corridor Alpha', and run a traffic volume analysis for personal vehicles."

1. **`street_light_data_osm_ids_search`**: The agent searches the provided geometry to find all `osm_id` values classified as primary roads.
2. **`create_a_street_light_data_zone_set`**: The agent compiles the `osm_ids` and calls the zone set creation tool, associating it with the user's email.
3. **`create_a_street_light_data_analysis`**: The agent triggers a new analysis job using the newly created zone set UUID, specifying personal vehicles as the travel mode.

**Result**: The agent autonomously bridges the gap between raw spatial coordinates and a running StreetLight traffic study, returning the analysis UUID to the planner.

### Scenario 2: Budget-Safe Metric Extraction
A Traffic Engineer wants to extract detailed SATC metrics for a massive geographic region but needs to ensure the query won't blow through their segment quota.

> "I need the weekend evening traffic metrics for this large regional polygon. Check the segment count first. If it is over 5,000 segments, stop and warn me. If it is under, pull the metrics."

1. **`list_all_street_light_data_satc_segment_counts`**: The agent first checks the segment count for the requested geometry and parameters.
2. **Logic Evaluation**: The agent reads the count (e.g., 3,200 segments) and determines it is safe to proceed based on the user's prompt.
3. **`list_all_street_light_data_satc_metrics`**: The agent executes the actual metric query.
4. **`list_all_street_light_data_satc_metric_pages`**: If the initial response indicates more data is available, the agent uses the `paging_id` to iterate through the remaining results.

**Result**: The agent acts as a guardrail against expensive API operations, safely paginates through large datasets, and returns a compiled summary of the weekend evening traffic.

## Building Multi-Step Workflows

To execute the workflows described above, your agent framework must be capable of looping through tool calls, evaluating responses, and handling errors - specifically HTTP 429 Rate Limits.

Because Truto passes rate limits directly to the caller, your execution loop must parse the standardized `ratelimit-reset` headers and wait accordingly. Here is a realistic agent loop built with LangChain that implements error handling and state management.

```typescript
import { HumanMessage, AIMessage, ToolMessage } from "@langchain/core/messages";

async function runStreetLightAgent(prompt: string) {
  const { llmWithTools, streetLightTools } = await initializeStreetLightAgent();
  
  let messages = [new HumanMessage(prompt)];
  const toolMap = new Map(streetLightTools.map(t => [t.name, t]));

  console.log("Starting agent loop...");

  while (true) {
    // Invoke the LLM with the current conversation history
    const response = await llmWithTools.invoke(messages);
    messages.push(response);

    // If the LLM didn't request a tool call, we are done
    if (!response.tool_calls || response.tool_calls.length === 0) {
      console.log("Final Answer:", response.content);
      break;
    }

    // Execute each requested tool
    for (const toolCall of response.tool_calls) {
      console.log(`Executing tool: ${toolCall.name}`);
      const tool = toolMap.get(toolCall.name);
      
      if (!tool) {
        messages.push(new ToolMessage({
          tool_call_id: toolCall.id,
          content: "Error: Tool not found."
        }));
        continue;
      }

      try {
        // Execute the tool via Truto proxy
        const toolResult = await tool.invoke(toolCall.args);
        
        messages.push(new ToolMessage({
          tool_call_id: toolCall.id,
          content: JSON.stringify(toolResult)
        }));
      } catch (error: any) {
        // Handle HTTP 429 Rate Limits using IETF standard headers
        if (error.status === 429) {
          const resetTime = error.headers['ratelimit-reset'];
          const waitSeconds = resetTime ? parseInt(resetTime, 10) : 5;
          
          console.warn(`Rate limit hit. Agent should wait ${waitSeconds} seconds.`);
          
          // Pass the error back to the LLM so it knows it failed
          messages.push(new ToolMessage({
            tool_call_id: toolCall.id,
            content: `HTTP 429 Rate Limit Exceeded. The agent must wait ${waitSeconds} seconds before retrying.`
          }));
        } else {
          // Generic error handling
          messages.push(new ToolMessage({
            tool_call_id: toolCall.id,
            content: `Execution failed: ${error.message}`
          }));
        }
      }
    }
  }
}

// Example execution
runStreetLightAgent(
  "Check how many segments are in this GeoJSON bounding box [paste geojson here]. If it's less than 1000, create a zone set."
);
```

This loop is framework-agnostic in concept. It ensures the LLM stays grounded in reality. If a StreetLight Data tool fails due to a geometry validation error or a rate limit, the error is fed back into the context window as a `ToolMessage`, allowing the LLM to adjust its geometry or back off before trying again.

## Moving from Scripts to Autonomous GIS Operations

Giving AI agents access to StreetLight Data transforms how organizations handle traffic analysis. Instead of relying on manual GIS engineers to extract coordinates, build zone sets, and pull CSV metrics, you can orchestrate these exact steps via a natural language interface or automated triggers.

By leveraging a unified API toolset, you avoid the technical debt of building custom OAuth flows, maintaining GeoJSON parsers, and managing pagination logic. The agent sees a clean, documented list of tools with strict input schemas, significantly reducing hallucination risk and operational overhead.

> Stop spending engineering cycles building point-to-point API integrations for AI agents. Let Truto handle the integration boilerplate so your team can focus on building intelligent agent workflows.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)