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, or if you are building on Anthropic's models, read our guide on connecting StreetLight Data to Claude. 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.

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 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.

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.

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.

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.

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.

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.